man/XQueryColor.man

   1 '\" t
   2 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
   3 .\"
   4 .\" Permission is hereby granted, free of charge, to any person obtaining
   5 .\" a copy of this software and associated documentation files (the
   6 .\" "Software"), to deal in the Software without restriction, including
   7 .\" without limitation the rights to use, copy, modify, merge, publish,
   8 .\" distribute, sublicense, and/or sell copies of the Software, and to
   9 .\" permit persons to whom the Software is furnished to do so, subject to
  10 .\" the following conditions:
  11 .\"
  12 .\" The above copyright notice and this permission notice shall be included
  13 .\" in all copies or substantial portions of the Software.
  14 .\"
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  16 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  19 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  20 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  21 .\" OTHER DEALINGS IN THE SOFTWARE.
  22 .\"
  23 .\" Except as contained in this notice, the name of the X Consortium shall
  24 .\" not be used in advertising or otherwise to promote the sale, use or
  25 .\" other dealings in this Software without prior written authorization
  26 .\" from the X Consortium.
  27 .\"
  28 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
  29 .\" Digital Equipment Corporation
  30 .\"
  31 .\" Portions Copyright \(co 1990, 1991 by
  32 .\" Tektronix, Inc.
  33 .\"
  34 .\" Permission to use, copy, modify and distribute this documentation for
  35 .\" any purpose and without fee is hereby granted, provided that the above
  36 .\" copyright notice appears in all copies and that both that copyright notice
  37 .\" and this permission notice appear in all copies, and that the names of
  38 .\" Digital and Tektronix not be used in in advertising or publicity pertaining
  39 .\" to this documentation without specific, written prior permission.
  40 .\" Digital and Tektronix makes no representations about the suitability
  41 .\" of this documentation for any purpose.
  42 .\" It is provided ``as is'' without express or implied warranty.
  43 .\"
  44 .\"
  45 .ds xT X Toolkit Intrinsics \- C Language Interface
  46 .ds xW Athena X Widgets \- C Language X Toolkit Interface
  47 .ds xL Xlib \- C Language X Interface
  48 .ds xC Inter-Client Communication Conventions Manual
  49 .na
  50 .de Ds
  51 .nf
  52 .\\$1D \\$2 \\$1
  53 .ft 1
  54 .\".ps \\n(PS
  55 .\".if \\n(VS>=40 .vs \\n(VSu
  56 .\".if \\n(VS<=39 .vs \\n(VSp
  57 ..
  58 .de De
  59 .ce 0
  60 .if \\n(BD .DF
  61 .nr BD 0
  62 .in \\n(OIu
  63 .if \\n(TM .ls 2
  64 .sp \\n(DDu
  65 .fi
  66 ..
  67 .de FD
  68 .LP
  69 .KS
  70 .TA .5i 3i
  71 .ta .5i 3i
  72 .nf
  73 ..
  74 .de FN
  75 .fi
  76 .KE
  77 .LP
  78 ..
  79 .de IN          \" send an index entry to the stderr
  80 ..
  81 .de C{
  82 .KS
  83 .nf
  84 .D
  85 .\"
  86 .\"     choose appropriate monospace font
  87 .\"     the imagen conditional, 480,
  88 .\"     may be changed to L if LB is too
  89 .\"     heavy for your eyes...
  90 .\"
  91 .ie "\\*(.T"480" .ft L
  92 .el .ie "\\*(.T"300" .ft L
  93 .el .ie "\\*(.T"202" .ft PO
  94 .el .ie "\\*(.T"aps" .ft CW
  95 .el .ft R
  96 .ps \\n(PS
  97 .ie \\n(VS>40 .vs \\n(VSu
  98 .el .vs \\n(VSp
  99 ..
 100 .de C}
 101 .DE
 102 .R
 103 ..
 104 .de Pn
 105 .ie t \\$1\fB\^\\$2\^\fR\\$3
 106 .el \\$1\fI\^\\$2\^\fP\\$3
 107 ..
 108 .de ZN
 109 .ie t \fB\^\\$1\^\fR\\$2
 110 .el \fI\^\\$1\^\fP\\$2
 111 ..
 112 .de hN
 113 .ie t <\fB\\$1\fR>\\$2
 114 .el <\fI\\$1\fP>\\$2
 115 ..
 116 .de NT
 117 .ne 7
 118 .ds NO Note
 119 .if \\n(.$>$1 .if !'\\$2'C' .ds NO \\$2
 120 .if \\n(.$ .if !'\\$1'C' .ds NO \\$1
 121 .ie n .sp
 122 .el .sp 10p
 123 .TB
 124 .ce
 125 \\*(NO
 126 .ie n .sp
 127 .el .sp 5p
 128 .if '\\$1'C' .ce 99
 129 .if '\\$2'C' .ce 99
 130 .in +5n
 131 .ll -5n
 132 .R
 133 ..
 134 .               \" Note End -- doug kraft 3/85
 135 .de NE
 136 .ce 0
 137 .in -5n
 138 .ll +5n
 139 .ie n .sp
 140 .el .sp 10p
 141 ..
 142 .ny0
 143 .TH XQueryColor __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 144 .SH NAME
 145 XQueryColor, XQueryColors, XLookupColor, XParseColor \- obtain color values
 146 .SH SYNTAX
 147 .HP
 148 int XQueryColor\^(\^Display *\fIdisplay\fP\^, Colormap \fIcolormap\fP\^, XColor
 149 *\fIdef_in_out\fP\^);
 150 .HP
 151 int XQueryColors\^(\^Display *\fIdisplay\fP\^, Colormap \fIcolormap\fP\^,
 152 XColor \fIdefs_in_out\fP[\^]\^, int \fIncolors\fP\^);
 153 .HP
 154 Status XLookupColor\^(\^Display *\fIdisplay\fP\^, Colormap \fIcolormap\fP\^,
 155 char *\fIcolor_name\fP\^, XColor *\fIexact_def_return\fP\^, XColor
 156 *\fIscreen_def_return\fP\^);
 157 .HP
 158 Status XParseColor\^(\^Display *\fIdisplay\fP\^, Colormap \fIcolormap\fP\^,
 159 char *\fIspec\fP\^, XColor *\fIexact_def_return\fP\^);
 160 .SH ARGUMENTS
 161 .IP \fIcolormap\fP 1i
 162 Specifies the colormap.
 163 .IP \fIcolor_name\fP 1i
 164 Specifies the color name string (for example, red) whose color
 165 definition structure you want returned.
 166 .IP \fIdef_in_out\fP 1i
 167 Specifies and returns the RGB values for the pixel specified in the structure.
 168 .IP \fIdefs_in_out\fP 1i
 169 Specifies and returns an array of color definition structures for the pixel
 170 specified in the structure.
 171 .IP \fIdisplay\fP 1i
 172 Specifies the connection to the X server.
 173 .IP \fIexact_def_return\fP 1i
 174 Returns the exact RGB values.
 175 .IP \fIncolors\fP 1i
 176 .\"Specifies the number of color definition structures.
 177 Specifies the number of
 178 .ZN XColor
 179 structures in the color definition array.
 180 .IP \fIscreen_def_return\fP 1i
 181 Returns the closest RGB values provided by the hardware.
 182 .IP \fIspec\fP 1i
 183 Specifies the color name string;
 184 case is ignored.
 185 .IP \fIexact_def_return\fP 1i
 186 Returns the exact color value for later use and sets the
 187 .ZN DoRed ,
 188 .ZN DoGreen ,
 189 and
 190 .ZN DoBlue
 191 flags.
 192 .SH DESCRIPTION
 193 The
 194 .ZN XQueryColor
 195 function returns the current RGB value for the pixel in the
 196 .ZN XColor
 197 structure and sets the
 198 .ZN DoRed ,
 199 .ZN DoGreen ,
 200 and
 201 .ZN DoBlue
 202 flags.
 203 The
 204 .ZN XQueryColors
 205 function returns the RGB value for each pixel in each
 206 .ZN XColor
 207 structure and sets the
 208 .ZN DoRed ,
 209 .ZN DoGreen ,
 210 and
 211 .ZN DoBlue
 212 flags in each structure.
 213
 214 .LP
 215 .ZN XQueryColor
 216 and
 217 .ZN XQueryColors
 218 can generate
 219 .ZN BadColor
 220 and
 221 .ZN BadValue
 222 errors.
 223 .LP
 224 The
 225 .ZN XLookupColor
 226 function looks up the string name of a color with respect to the screen
 227 associated with the specified colormap.
 228 It returns both the exact color values and
 229 the closest values provided by the screen
 230 with respect to the visual type of the specified colormap.
 231 If the color name is not in the Host Portable Character Encoding,
 232 the result is implementation-dependent.
 233 Use of uppercase or lowercase does not matter.
 234 .ZN XLookupColor
 235 returns nonzero if the name is resolved;
 236 otherwise, it returns zero.
 237 .LP
 238 The
 239 .ZN XParseColor
 240 function looks up the string name of a color with respect to the screen
 241 associated with the specified colormap.
 242 It returns the exact color value.
 243 If the color name is not in the Host Portable Character Encoding,
 244 the result is implementation-dependent.
 245 Use of uppercase or lowercase does not matter.
 246 .ZN XParseColor
 247 returns nonzero if the name is resolved;
 248 otherwise, it returns zero.
 249 .LP
 250 .ZN XLookupColor
 251 and
 252 .ZN XParseColor
 253 can generate
 254 .ZN BadColor
 255 error.
 256 .SH "COLOR NAMES"
 257 An RGB Device specification is identified by
 258 the prefix ``rgb:'' and conforms to the following syntax:
 259 .LP
 260 .\" Start marker code here
 261 .Ds 0
 262 rgb:\fI<red>/<green>/<blue>\fP
 263
 264     \fI<red>\fP, \fI<green>\fP, \fI<blue>\fP := \fIh\fP | \fIhh\fP | \fIhhh\fP | \fIhhhh\fP
 265     \fIh\fP := single hexadecimal digits (case insignificant)
 266 .De
 267 .\" End marker code here
 268 .LP
 269 Note that \fIh\fP indicates the value scaled in 4 bits,
 270 \fIhh\fP the value scaled in 8 bits,
 271 \fIhhh\fP the value scaled in 12 bits,
 272 and \fIhhhh\fP the value scaled in 16 bits, respectively.
 273 .LP
 274 For backward compatibility, an older syntax for RGB Device is
 275 supported, but its continued use is not encouraged.
 276 The syntax is an initial sharp sign character followed by
 277 a numeric specification, in one of the following formats:
 278 .LP
 279 .TS
 280 l l.
 281 \&#RGB  (4 bits each)
 282 \&#RRGGBB       (8 bits each)
 283 \&#RRRGGGBBB    (12 bits each)
 284 \&#RRRRGGGGBBBB (16 bits each)
 285 .TE
 286 .LP
 287 The R, G, and B represent single hexadecimal digits.
 288 When fewer than 16 bits each are specified,
 289 they represent the most significant bits of the value
 290 (unlike the ``rgb:'' syntax, in which values are scaled).
 291 For example, the string ``#3a7'' is the same as ``#3000a0007000''.
 292 .LP
 293 An RGB intensity specification is identified
 294 by the prefix ``rgbi:'' and conforms to the following syntax:
 295 .LP
 296 .\" Start marker code here
 297 .Ds 0
 298 rgbi:\fI<red>/<green>/<blue>\fP
 299 .De
 300 .\" End marker code here
 301 .LP
 302 Note that red, green, and blue are floating-point values
 303 between 0.0 and 1.0, inclusive.
 304 The input format for these values is an optional sign,
 305 a string of numbers possibly containing a decimal point,
 306 and an optional exponent field containing an E or e
 307 followed by a possibly signed integer string.
 308 .LP
 309 The standard device-independent string specifications have
 310 the following syntax:
 311 .LP
 312 .\" Start marker code here
 313 .Ds 0
 314 CIEXYZ:\fI<X>/<Y>/<Z>\fP
 315 CIEuvY:\fI<u>/<v>/<Y>\fP
 316 CIExyY:\fI<x>/<y>/<Y>\fP
 317 CIELab:\fI<L>/<a>/<b>\fP
 318 CIELuv:\fI<L>/<u>/<v>\fP
 319 TekHVC:\fI<H>/<V>/<C>\fP
 320 .De
 321 .\" End marker code here
 322 .LP
 323 All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
 324 floating-point values.
 325 The syntax for these values is an optional plus or minus sign,
 326 a string of digits possibly containing a decimal point,
 327 and an optional exponent field consisting of an ``E'' or ``e''
 328 followed by an optional plus or minus followed by a string of digits.
 329 .SH DIAGNOSTICS
 330 .TP 1i
 331 .ZN BadColor
 332 A value for a Colormap argument does not name a defined Colormap.
 333 .TP 1i
 334 .ZN BadValue
 335 Some numeric value falls outside the range of values accepted by the request.
 336 Unless a specific range is specified for an argument, the full range defined
 337 by the argument's type is accepted.  Any argument defined as a set of
 338 alternatives can generate this error.
 339 .SH "SEE ALSO"
 340 XAllocColor(__libmansuffix__),
 341 XCreateColormap(__libmansuffix__),
 342 XStoreColors(__libmansuffix__)
 343 .br
 344 \fI\*(xL\fP