Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tk_AllocFontFromObj(3)	     Tk	Library	Procedures	Tk_AllocFontFromObj(3)


       Tk_AllocFontFromObj,   Tk_GetFont,   Tk_GetFontFromObj,	Tk_NameOfFont,
       Tk_FreeFontFromObj, Tk_FreeFont - maintain database of fonts

       #include	<tk.h>

       Tk_AllocFontFromObj(interp, tkwin, objPtr)

       Tk_GetFont(interp, tkwin, string)

       Tk_GetFontFromObj(tkwin,	objPtr)

       const char *

       Tk_FreeFontFromObj(tkwin, objPtr)


       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

       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.

       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 er-
       ror message in interp's result if interp	is not NULL.  Tk_AllocFontFro-
       mObj  caches information	about the return value in objPtr, which	speeds
       up future calls to procedures such as Tk_AllocFontFromObj  and  Tk_Get-

       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 re-
       lease 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.



Tk				      8.1		Tk_AllocFontFromObj(3)


Want to link to this manual page? Use this URL:

home | help