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
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 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 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 #RGB
86 #RRGGBB
88 #RRRGGGBBB
90 #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 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 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 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 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)