Tk_AllocFontFromObj(3) Tk Library Procedures Tk_AllocFontFromObj(3)
____________________________________________________________________________________________________________
NAME
Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont -maintain Tk_FreeFontmaintain
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) |
CONST 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 messages
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 documentation 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 cached.
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_Mea- |
sureChars, and Tk_FreeFont. The Tk_Font token will remain valid until Tk_FreeFontFromObj or Tk_Free- |
Font 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_AllocFontFro- |
mObj is unsuccessful (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_AllocFont- |
FromObj 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 efficient 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_GetFontFromObj 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 noone
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_FreeFontFromObj the font to release is specified with the same information used to create it; |
for Tk_FreeFont the font to 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
Tk 8.1 Tk_AllocFontFromObj(3)
|