93 lines
3.7 KiB
Groff
93 lines
3.7 KiB
Groff
'\"
|
|
'\" Copyright (c) 1990-1992 The Regents of the University of California.
|
|
'\" All rights reserved.
|
|
'\"
|
|
'\" Permission is hereby granted, without written agreement and without
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
|
'\" documentation for any purpose, provided that the above copyright
|
|
'\" notice and the following two paragraphs appear in all copies.
|
|
'\"
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
'\"
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
|
'\"
|
|
'\" $Header: /user6/ouster/wish/man/RCS/GetFontStr.3,v 1.6 93/04/01 09:41:27 ouster Exp $ SPRITE (Berkeley)
|
|
'\"
|
|
.so man.macros
|
|
.HS Tk_GetFontStruct tkc
|
|
.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
|