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. For
98 example, #3a7 is the same as #3000a0007000.
99 Tk_AllocColorFromObj returns a pointer to an XColor structure; the
101 structure indicates the exact intensities of the allocated color (which
102 may differ slightly from those requested, depending on the limitations
103 of the screen) and a pixel value that may be used to draw with the
104 color in tkwin. If an error occurs in Tk_AllocColorFromObj (such as an
105 unknown color name) then NULL is returned and an error message is
106 stored in interp's result if interp is not NULL. If the colormap for
107 tkwin is full, Tk_AllocColorFromObj will use the closest existing color
108 in the colormap. Tk_AllocColorFromObj caches information about the
109 return value in objPtr, which speeds up future calls to procedures such
110 as Tk_AllocColorFromObj and Tk_GetColorFromObj.
111 Tk_GetColor is identical to Tk_AllocColorFromObj except that the
113 description of the color is specified with a string instead of an
114 object. This prevents Tk_GetColor from caching the return value, so
115 Tk_GetColor is less efficient than Tk_AllocColorFromObj.
116 Tk_GetColorFromObj returns the token for an existing color, given the
118 window and description used to create the color. Tk_GetColorFromObj
119 does not actually create the color; the color must already have been
120 created with a previous call to Tk_AllocColorFromObj or Tk_GetColor.
121 The return value is cached in objPtr, which speeds up future calls to
122 Tk_GetColorFromObj with the same objPtr and tkwin.
123 Tk_GetColorByValue is similar to Tk_GetColor except that the desired
125 color is indicated with the red, green, and blue fields of the struc‐
126 ture pointed to by colorPtr.
127 This package maintains a database of all the colors currently in use.
129 If the same color is requested multiple times from Tk_GetColor or
130 Tk_AllocColorFromObj (e.g. by different windows), or if the same inten‐
131 sities are requested multiple times from Tk_GetColorByValue, then
132 existing pixel values will be re-used. Re-using an existing pixel
133 avoids any interaction with the window server, which makes the alloca‐
134 tion much more efficient. These procedures also provide a portable
135 interface that works across all platforms. For this reason, you should
136 generally use Tk_AllocColorFromObj, Tk_GetColor, or Tk_GetColorByValue
137 instead of lower level procedures like XAllocColor.
138 Since different calls to this package may return the same shared pixel
140 value, callers should never change the color of a pixel returned by the
141 procedures. If you need to change a color value dynamically, you
142 should use XAllocColorCells to allocate the pixel value for the color.
143 The procedure Tk_NameOfColor is roughly the inverse of Tk_GetColor. If
145 its colorPtr argument was created by Tk_AllocColorFromObj or Tk_Get‐
146 Color then the return value is the string that was used to create the
147 color. If colorPtr was created by a call to Tk_GetColorByValue, or by
148 any other mechanism, then the return value is a string that could be
149 passed to Tk_GetColor to return the same color. Note: the string
150 returned by Tk_NameOfColor is only guaranteed to persist until the next
151 call to Tk_NameOfColor.
152 Tk_GCForColor returns a graphics context whose foreground field is the
154 pixel allocated for colorPtr and whose other fields all have default
155 values. This provides an easy way to do basic drawing with a color.
156 The graphics context is cached with the color and will exist only as
157 long as colorPtr exists; it is freed when the last reference to col‐
158 orPtr is freed by calling Tk_FreeColor.
159 When a color is no longer needed Tk_FreeColorFromObj or Tk_FreeColor
161 should be called to release it. For Tk_FreeColorFromObj the color to
162 release is specified with the same information used to create it; for
163 Tk_FreeColor the color to release is specified with a pointer to its
164 XColor structure. There should be exactly one call to Tk_FreeColorFro‐
165 mObj or Tk_FreeColor for each call to Tk_AllocColorFromObj, Tk_Get‐
166 Color, or Tk_GetColorByValue.
167
169 color, intensity, object, pixel value
170Tk 8.1 Tk_AllocColorFromObj(3)