home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tk3.3b1 / doc / GetGC.3 < prev    next >
Encoding:
Text File  |  1993-04-30  |  3.6 KB  |  92 lines
  1. '\"
  2. '\" Copyright (c) 1990 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/GetGC.3,v 1.6 93/04/30 11:41:39 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tk_GetGC tkc
  25. .BS
  26. .SH NAME
  27. Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tk.h>\fR
  31. .sp
  32. GC
  33. \fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR)
  34. .sp
  35. .VS
  36. .VE
  37. \fBTk_FreeGC(\fIdisplay, gc\fR)
  38. .SH ARGUMENTS
  39. .AS "unsigned long" valueMask
  40. .AP Tk_Window tkwin in
  41. Token for window in which the graphics context will be used.
  42. .AP "unsigned long" valueMask in
  43. Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR)
  44. indicating which fields of \fI*valuePtr\fR are valid.
  45. .AP XGCValues *valuePtr in
  46. Pointer to structure describing the desired values for the
  47. graphics context.
  48. .AP Display *display in
  49. Display for which \fIgc\fR was allocated.
  50. .VS
  51. .VE
  52. .AP GC gc in
  53. X identifier for graphics context that is no longer needed.
  54. Must have been allocated by \fBTk_GetGC\fR.
  55. .BE
  56.  
  57. .SH DESCRIPTION
  58. .PP
  59. \fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts
  60. being used by an application.  The procedures allow graphics contexts to be
  61. shared, thereby avoiding the server overhead that would be incurred
  62. if a separate GC were created for each use.  \fBTk_GetGC\fR takes arguments
  63. describing the desired graphics context and returns an X identifier
  64. for a GC that fits the description.  The graphics context that is returned
  65. will have default values in all of the fields not specified explicitly
  66. by \fIvalueMask\fR and \fIvaluePtr\fR.
  67. .PP
  68. \fBTk_GetGC\fR maintains a
  69. database of all the graphics contexts it has created.  Whenever possible,
  70. a call to \fBTk_GetGC\fR will
  71. return an existing graphics context rather than creating a new one.  This
  72. approach can substantially reduce server overhead, so \fBTk_GetGC\fR
  73. should generally be used in preference to the Xlib procedure
  74. \fBXCreateGC\fR, which creates a new graphics context on each call.
  75. .PP
  76. Since the return values of \fBTk_GetGC\fR
  77. are shared, callers should never modify the graphics contexts
  78. returned by \fBTk_GetGC\fR.
  79. If a graphics context must be modified dynamically, then it should be
  80. created by calling \fBXCreateGC\fR instead of \fBTk_GetGC\fR.
  81. .PP
  82. When a graphics context
  83. is no longer needed, \fBTk_FreeGC\fR should be called to release it.
  84. There should be exactly one call to \fBTk_FreeGC\fR for
  85. each call to \fBTk_GetGC\fR.
  86. When a graphics context is no longer in use anywhere (i.e. it has
  87. been freed as many times as it has been gotten) \fBTk_FreeGC\fR
  88. will release it to the X server and delete it from the database.
  89.  
  90. .SH KEYWORDS
  91. graphics context
  92.