tk/doc/GetGC.3

   1 '\"
   2 '\" Copyright (c) 1990 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH Tk_GetGC 3 "" Tk "Tk Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tk.h>\fR
  18 .sp
  19 GC
  20 \fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR)
  21 .sp
  22 \fBTk_FreeGC(\fIdisplay, gc\fR)
  23 .SH ARGUMENTS
  24 .AS "unsigned long" valueMask
  25 .AP Tk_Window tkwin in
  26 Token for window in which the graphics context will be used.
  27 .AP "unsigned long" valueMask in
  28 Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR)
  29 indicating which fields of \fI*valuePtr\fR are valid.
  30 .AP XGCValues *valuePtr in
  31 Pointer to structure describing the desired values for the
  32 graphics context.
  33 .AP Display *display in
  34 Display for which \fIgc\fR was allocated.
  35 .AP GC gc in
  36 X identifier for graphics context that is no longer needed.
  37 Must have been allocated by \fBTk_GetGC\fR.
  38 .BE
  39
  40 .SH DESCRIPTION
  41 .PP
  42 \fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts
  43 being used by an application.  The procedures allow graphics contexts to be
  44 shared, thereby avoiding the server overhead that would be incurred
  45 if a separate GC were created for each use.  \fBTk_GetGC\fR takes arguments
  46 describing the desired graphics context and returns an X identifier
  47 for a GC that fits the description.  The graphics context that is returned
  48 will have default values in all of the fields not specified explicitly
  49 by \fIvalueMask\fR and \fIvaluePtr\fR.
  50 .PP
  51 \fBTk_GetGC\fR maintains a
  52 database of all the graphics contexts it has created.  Whenever possible,
  53 a call to \fBTk_GetGC\fR will
  54 return an existing graphics context rather than creating a new one.  This
  55 approach can substantially reduce server overhead, so \fBTk_GetGC\fR
  56 should generally be used in preference to the Xlib procedure
  57 \fBXCreateGC\fR, which creates a new graphics context on each call.
  58 .PP
  59 Since the return values of \fBTk_GetGC\fR
  60 are shared, callers should never modify the graphics contexts
  61 returned by \fBTk_GetGC\fR.
  62 If a graphics context must be modified dynamically, then it should be
  63 created by calling \fBXCreateGC\fR instead of \fBTk_GetGC\fR.
  64 .PP
  65 When a graphics context
  66 is no longer needed, \fBTk_FreeGC\fR should be called to release it.
  67 There should be exactly one call to \fBTk_FreeGC\fR for
  68 each call to \fBTk_GetGC\fR.
  69 When a graphics context is no longer in use anywhere (i.e. it has
  70 been freed as many times as it has been gotten) \fBTk_FreeGC\fR
  71 will release it to the X server and delete it from the database.
  72
  73 .SH KEYWORDS
  74 graphics context