Tk_AllocFontFromObj - Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, maintain database of fonts
#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)
Tk_AllocFontFromObj(3tk) Tk Library Procedures Tk_AllocFontFromObj(3tk)
______________________________________________________________________________
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)
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 report-
ing. If NULL, then no error messages
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 result-
ing Tk_Font is not 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 subse-
quent calls to procedures such as Tk_GetFontMetrics, Tk_MeasureChars,
and Tk_FreeFont. The Tk_Font token will remain valid until Tk_Free-
FontFromObj 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_Alloc-
FontFromObj is unsuccessful (because, for example, objPtr did not con-
tain a valid font specification) then it returns NULL and leaves an
error message in interp's result if interp is not NULL. Tk_AllocFont-
FromObj caches information about the return value in objPtr, which
speeds up future calls to procedures such as Tk_AllocFontFromObj and
Tk_GetFontFromObj.
Tk_GetFont is identical to Tk_AllocFontFromObj except that the descrip-
tion 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 does
not 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_GetFont-
FromObj 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 guar-
anteed 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.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | runtime/tk-8 |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
SEE ALSO
Tk_FontId(3)
KEYWORDS
font
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from https://source-
forge.net/projects/tcl/files/Tcl/8.6.7/tk8.6.7-src.tar.gz/download.
Further information about this software can be found on the open source
community website at https://www.tcl.tk/.
Tk 8.1 Tk_AllocFontFromObj(3tk)