1Tk_AllocColorFromObj(3) Tk Library Procedures Tk_AllocColorFromObj(3)
2______________________________________________________________________________
6
8 Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorBy‐
9 Value, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor - maintain
10 database of colors
11
13 #include <tk.h>
14 XColor *
16 Tk_AllocColorFromObj(interp, tkwin, objPtr)
17 XColor *
19 Tk_GetColor(interp, tkwin, name)
20 XColor *
22 Tk_GetColorFromObj(tkwin, objPtr)
23 XColor *
25 Tk_GetColorByValue(tkwin, prefPtr)
26 const char *
28 Tk_NameOfColor(colorPtr)
29 GC
31 Tk_GCForColor(colorPtr, drawable)
32 Tk_FreeColorFromObj(tkwin, objPtr)
34 Tk_FreeColor(colorPtr)
36
38 Tcl_Interp *interp (in) Interpreter to use for error report‐
39 ing.
40 Tk_Window tkwin (in) Token for window in which color will
42 be used.
43 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 char *name (in) Same as objPtr except description of
50 color is passed as a string and
51 resulting (XColor *) is not cached.
52 XColor *prefPtr (in) Indicates red, green, and blue
54 intensities of desired color.
55 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 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
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 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 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 #RGB
85 #RRGGBB
87 #RRRGGGBBB
89 #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 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 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 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 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 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 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 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 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 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
170 color, intensity, value, pixel value
171Tk 8.1 Tk_AllocColorFromObj(3)