1Tk_AllocColorFromObj(3)      Tk Library Procedures     Tk_AllocColorFromObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_AllocColorFromObj,  Tk_GetColor,  Tk_GetColorFromObj, Tk_GetColorBy‐
9       Value, Tk_NameOfColor,  Tk_FreeColorFromObj,  Tk_FreeColor  -  maintain
10       database of colors
11

SYNOPSIS

13       #include <tk.h>
14
15       XColor *                                                                │
16       Tk_AllocColorFromObj(interp, tkwin, objPtr)                             
17
18       XColor *                                                                │
19       Tk_GetColor(interp, tkwin, name)                                        
20
21       XColor *                                                                │
22       Tk_GetColorFromObj(tkwin, objPtr)                                       
23
24       XColor *
25       Tk_GetColorByValue(tkwin, prefPtr)
26
27       CONST char *
28       Tk_NameOfColor(colorPtr)
29
30       GC
31       Tk_GCForColor(colorPtr, drawable)
32
33       Tk_FreeColorFromObj(tkwin, objPtr)                                      
34
35       Tk_FreeColor(colorPtr)
36

ARGUMENTS

38       Tcl_Interp   *interp     (in)      Interpreter to use for error report‐
39                                          ing.
40
41       Tk_Window    tkwin       (in)      Token for window in which color will
42                                          be used.
43
44       Tcl_Obj      *objPtr     (in/out)                                       │
45                                          String   value   describes   desired │
46                                          color; internal rep will be modified │
47                                          to  cache  pointer  to corresponding │
48                                          (XColor *).                          │
49
50       char         *name       (in)                                           │
51                                          Same as objPtr except description of │
52                                          color  is  passed  as  a  string and │
53                                          resulting (XColor *) isn't cached.
54
55       XColor       *prefPtr    (in)      Indicates  red,  green,   and   blue
56                                          intensities of desired color.
57
58       XColor       *colorPtr   (in)      Pointer   to  X  color  information.
59                                          Must have been allocated by previous
60                                          call     to    Tk_AllocColorFromObj,
61                                          Tk_GetColor  or  Tk_GetColorByValue,
62                                          except  when  passed  to  Tk_NameOf‐
63                                          Color.
64
65       Drawable     drawable    (in)      Drawable in which the result  graph‐
66                                          ics context will be used.  Must have
67                                          same screen and depth as the  window
68                                          for which the color was allocated.
69_________________________________________________________________
70
71

DESCRIPTION

73       These  procedures  manage  the  colors  being used by a Tk application. │
74       They allow colors to be shared  whenever  possible,  so  that  colormap │
75       space  is  preserved,  and they pick closest available colors when col‐ │
76       ormap space is exhausted.                                               │
77
78       Given a textual description of a color, Tk_AllocColorFromObj locates  a │
79       pixel  value  that may be used to render the color in a particular win‐ │
80       dow.  The desired color is specified with an object whose string  value │
81       must have one of the following forms:
82
83       colorname           Any  of the valid textual names for a color defined
84                           in the server's color database file, such as red or
85                           PeachPuff.
86
87       #RGB
88
89       #RRGGBB
90
91       #RRRGGGBBB
92
93       #RRRRGGGGBBBB       A numeric specification of the red, green, and blue
94                           intensities to use to display the color.   Each  R,
95                           G, or B represents a single hexadecimal digit.  The
96                           four forms  permit  colors  to  be  specified  with
97                           4-bit,  8-bit, 12-bit or 16-bit values.  When fewer
98                           than 16 bits are provided for each color, they rep‐
99                           resent the most significant bits of the color.  For
100                           example, #3a7 is the same as #3000a0007000.
101
102       Tk_AllocColorFromObj returns a pointer to  an  XColor  structure;   the │
103       structure indicates the exact intensities of the allocated color (which │
104       may differ slightly from those requested, depending on the  limitations │
105       of  the  screen)  and  a  pixel value that may be used to draw with the │
106       color in tkwin.  If an error occurs in Tk_AllocColorFromObj (such as an │
107       unknown  color  name)  then  NULL  is  returned and an error message is │
108       stored in interp's result if interp isn't NULL.  If  the  colormap  for │
109       tkwin is full, Tk_AllocColorFromObj will use the closest existing color │
110       in the colormap.  Tk_AllocColorFromObj  caches  information  about  the │
111       return value in objPtr, which speeds up future calls to procedures such │
112       as Tk_AllocColorFromObj and Tk_GetColorFromObj.                         │
113
114       Tk_GetColor  is  identical  to  Tk_AllocColorFromObj  except  that  the │
115       description  of  the  color  is  specified  with a string instead of an │
116       object.  This prevents Tk_GetColor from caching the  return  value,  so │
117       Tk_GetColor is less efficient than Tk_AllocColorFromObj.                │
118
119       Tk_GetColorFromObj  returns  the token for an existing color, given the │
120       window and description used to create  the  color.   Tk_GetColorFromObj 
121       doesn't  actually  create  the  color; the color must already have been │
122       created with a previous call to  Tk_AllocColorFromObj  or  Tk_GetColor. │
123       The  return  value is cached in objPtr, which speeds up future calls to │
124       Tk_GetColorFromObj with the same objPtr and tkwin.
125
126       Tk_GetColorByValue is similar to Tk_GetColor except  that  the  desired
127       color  is  indicated with the red, green, and blue fields of the struc‐
128       ture pointed to by colorPtr.
129
130       This package maintains a database of all the colors currently  in  use.
131       If  the  same  color  is  requested  multiple times from Tk_GetColor or
132       Tk_AllocColorFromObj (e.g. by different windows), or if the same inten‐
133       sities  are  requested  multiple  times  from  Tk_GetColorByValue, then
134       existing pixel values will be  re-used.   Re-using  an  existing  pixel
135       avoids  any interaction with the window server, which makes the alloca‐
136       tion much more efficient.  These procedures  also  provide  a  portable
137       interface that works across all platforms.  For this reason, you should
138       generally use Tk_AllocColorFromObj, Tk_GetColor, or  Tk_GetColorByValue
139       instead of lower level procedures like XAllocColor.
140
141       Since  different calls to this package may return the same shared pixel
142       value, callers should never change the color of a pixel returned by the
143       procedures.   If  you  need  to  change  a color value dynamically, you
144       should use XAllocColorCells to allocate the pixel value for the color.
145
146       The procedure Tk_NameOfColor is roughly the inverse of Tk_GetColor.  If
147       its  colorPtr  argument  was created by Tk_AllocColorFromObj or Tk_Get‐
148       Color then the return value is the string that was used to  create  the
149       color.   If colorPtr was created by a call to Tk_GetColorByValue, or by
150       any other mechanism, then the return value is a string  that  could  be
151       passed  to  Tk_GetColor  to  return  the same color.  Note:  the string
152       returned by Tk_NameOfColor is only guaranteed to persist until the next
153       call to Tk_NameOfColor.
154
155       Tk_GCForColor  returns a graphics context whose foreground field is the
156       pixel allocated for colorPtr and whose other fields  all  have  default
157       values.   This  provides  an easy way to do basic drawing with a color.
158       The graphics context is cached with the color and will  exist  only  as
159       long  as  colorPtr exists;  it is freed when the last reference to col‐
160       orPtr is freed by calling Tk_FreeColor.
161
162       When a color is no longer needed  Tk_FreeColorFromObj  or  Tk_FreeColor 
163       should  be  called to release it.  For Tk_FreeColorFromObj the color to │
164       release is specified with the same information used to create  it;  for │
165       Tk_FreeColor  the  color  to release is specified with a pointer to its │
166       XColor structure.  There should be exactly one call to Tk_FreeColorFro‐ 
167       mObj  or  Tk_FreeColor  for  each call to Tk_AllocColorFromObj, Tk_Get‐ 
168       Color, or Tk_GetColorByValue.
169

KEYWORDS

171       color, intensity, object, pixel value
172
173
174
175Tk                                    8.1              Tk_AllocColorFromObj(3)
Impressum