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)           String   value   describes   desired
45                                          color; internal rep will be modified
46                                          to  cache  pointer  to corresponding
47                                          (XColor *).
48
49       char *name (in)                    Same as objPtr except description of
50                                          color  is  passed  as  a  string and
51                                          resulting (XColor *) is not cached.
52
53       XColor *prefPtr (in)               Indicates  red,  green,   and   blue
54                                          intensities of desired color.
55
56       XColor *colorPtr (in)              Pointer   to  X  color  information.
57                                          Must have been allocated by previous
58                                          call     to    Tk_AllocColorFromObj,
59                                          Tk_GetColor  or  Tk_GetColorByValue,
60                                          except  when  passed  to  Tk_NameOf‐
61                                          Color.
62
63       Drawable drawable (in)             Drawable in which the result  graph‐
64                                          ics context will be used.  Must have
65                                          same screen and depth as the  window
66                                          for which the color was allocated.
67_________________________________________________________________
68
69

DESCRIPTION

71       These  procedures  manage  the  colors  being used by a Tk application.
72       They allow colors to be shared  whenever  possible,  so  that  colormap
73       space  is  preserved,  and they pick closest available colors when col‐
74       ormap space is exhausted.
75
76       Given a textual description of a color, Tk_AllocColorFromObj locates  a
77       pixel  value  that may be used to render the color in a particular win‐
78       dow.  The desired color is specified with an object whose string  value
79       must have one of the following forms:
80
81       colorname           Any  of the valid textual names for a color defined
82                           in the server's color database file, such as red or
83                           PeachPuff.
84
85       #RGB
86
87       #RRGGBB
88
89       #RRRGGGBBB
90
91       #RRRRGGGGBBBB       A numeric specification of the red, green, and blue
92                           intensities to use to display the color.   Each  R,
93                           G, or B represents a single hexadecimal digit.  The
94                           four forms  permit  colors  to  be  specified  with
95                           4-bit,  8-bit, 12-bit or 16-bit values.  When fewer
96                           than 16 bits are provided for each color, they rep‐
97                           resent  the  most  significant  bits  of the color,
98                           while the lower unfilled bits  will  be  repeatedly
99                           replicated  from  the  available  higher bits.  For
100                           example, #3a7 is the same as #3333aaaa7777.
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 is not 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       does  not  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