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

DESCRIPTION

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

KEYWORDS

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