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) │
45 String value describes desired │
46 color; internal rep will be modified │
47 to cache pointer to corresponding │
48 (XColor *). │
49 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 XColor *prefPtr (in) Indicates red, green, and blue
56 intensities of desired color.
57 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 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
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 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 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 #RGB
88 #RRGGBB
90 #RRRGGGBBB
92 #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 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 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 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 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 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 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 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 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 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
171 color, intensity, object, pixel value
172Tk 8.1 Tk_AllocColorFromObj(3)