80 lines
2.9 KiB
Groff
80 lines
2.9 KiB
Groff
'\"
|
|
'\" Copyright (c) 1990-1992 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) GetFontStr.3 1.10 96/03/26 18:10:03
|
|
'\"
|
|
.so man.macros
|
|
.TH Tk_GetFontStruct 3 "" Tk "Tk Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tk_GetFontStruct, Tk_NameOfFontStruct, Tk_FreeFontStruct \- maintain database of fonts
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tk.h>\fR
|
|
.sp
|
|
XFontStruct *
|
|
\fBTk_GetFontStruct(\fIinterp, tkwin, nameId\fB)\fR
|
|
.sp
|
|
char *
|
|
\fBTk_NameOfFontStruct(\fIfontStructPtr\fB)\fR
|
|
.sp
|
|
\fBTk_FreeFontStruct(\fIfontStructPtr\fB)\fR
|
|
.SH ARGUMENTS
|
|
.AS "XFontStruct" *fontStructPtr
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter to use for error reporting.
|
|
.AP Tk_Window tkwin in
|
|
Token for window in which font will be used.
|
|
.AP Tk_Uid nameId in
|
|
Name of desired font.
|
|
.AP XFontStruct *fontStructPtr in
|
|
Font structure to return name for or delete.
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBTk_GetFont\fR loads the font indicated
|
|
by \fInameId\fR and returns a pointer to information about the
|
|
font. The pointer returned by \fBTk_GetFont\fR
|
|
will remain valid until \fBTk_FreeFont\fR
|
|
is called to release it.
|
|
\fINameId\fR can be either a font name or pattern; any
|
|
value that could be passed to \fBXLoadQueryFont\fR may be
|
|
passed to \fBTk_GetFont\fR. If \fBTk_GetFont\fR is unsuccessful
|
|
(because, for example, there is no font corresponding to
|
|
\fInameId\fR) then it returns \fBNULL\fR and stores an error
|
|
message in \fIinterp->result\fR.
|
|
.PP
|
|
\fBTk_GetFont\fR maintains a database of all fonts it has allocated.
|
|
If the same \fInameId\fR is requested multiple times (e.g. by
|
|
different windows or for different purposes), then additional
|
|
calls for the same \fInameId\fR will be handled very quickly, without
|
|
involving the X server. For this reason, it is generally better
|
|
to use \fBTk_GetFont\fR in place of X library procedures like
|
|
\fBXLoadQueryFont\fR.
|
|
.PP
|
|
The procedure \fBTk_NameOfFontStruct\fR is roughly the inverse of
|
|
\fBTk_GetFontStruct\fR. If its \fIfontStructPtr\fR argument was created
|
|
by \fBTk_GetFontStruct\fR, then the return value is the \fInameId\fR
|
|
argument that was passed to \fBTk_GetFontStruct\fR to create the
|
|
font. If \fIfontStructPtr\fR was not created by a call
|
|
to \fBTk_GetFontStruct\fR, then the return value is a hexadecimal string
|
|
giving the X identifier for the associated font.
|
|
Note: the string returned by \fBTk_NameOfFontStruct\fR is
|
|
only guaranteed to persist until the next call to \fBTk_NameOfFontStruct\fR.
|
|
.PP
|
|
When a font returned by \fBTk_GetFont\fR is no longer
|
|
needed, \fBTk_FreeFont\fR should be called to release it.
|
|
There should be exactly one call to \fBTk_FreeFont\fR for
|
|
each call to \fBTk_GetFont\fR. When a font is no longer in
|
|
use anywhere (i.e. it has been freed as many times as it has been gotten)
|
|
\fBTk_FreeFont\fR will release it to the X server and delete it from
|
|
the database.
|
|
|
|
.SH KEYWORDS
|
|
font
|