man/XGetWindowProperty.man

   1 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining
   4 .\" a copy of this software and associated documentation files (the
   5 .\" "Software"), to deal in the Software without restriction, including
   6 .\" without limitation the rights to use, copy, modify, merge, publish,
   7 .\" distribute, sublicense, and/or sell copies of the Software, and to
   8 .\" permit persons to whom the Software is furnished to do so, subject to
   9 .\" the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice shall be included
  12 .\" in all copies or substantial portions of the Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  17 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  18 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  19 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  20 .\" OTHER DEALINGS IN THE SOFTWARE.
  21 .\"
  22 .\" Except as contained in this notice, the name of the X Consortium shall
  23 .\" not be used in advertising or otherwise to promote the sale, use or
  24 .\" other dealings in this Software without prior written authorization
  25 .\" from the X Consortium.
  26 .\"
  27 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
  28 .\" Digital Equipment Corporation
  29 .\"
  30 .\" Portions Copyright \(co 1990, 1991 by
  31 .\" Tektronix, Inc.
  32 .\"
  33 .\" Permission to use, copy, modify and distribute this documentation for
  34 .\" any purpose and without fee is hereby granted, provided that the above
  35 .\" copyright notice appears in all copies and that both that copyright notice
  36 .\" and this permission notice appear in all copies, and that the names of
  37 .\" Digital and Tektronix not be used in in advertising or publicity pertaining
  38 .\" to this documentation without specific, written prior permission.
  39 .\" Digital and Tektronix makes no representations about the suitability
  40 .\" of this documentation for any purpose.
  41 .\" It is provided ``as is'' without express or implied warranty.
  42 .\"
  43 .\"
  44 .ds xT X Toolkit Intrinsics \- C Language Interface
  45 .ds xW Athena X Widgets \- C Language X Toolkit Interface
  46 .ds xL Xlib \- C Language X Interface
  47 .ds xC Inter-Client Communication Conventions Manual
  48 .na
  49 .de Ds
  50 .nf
  51 .\\$1D \\$2 \\$1
  52 .ft 1
  53 .\".ps \\n(PS
  54 .\".if \\n(VS>=40 .vs \\n(VSu
  55 .\".if \\n(VS<=39 .vs \\n(VSp
  56 ..
  57 .de De
  58 .ce 0
  59 .if \\n(BD .DF
  60 .nr BD 0
  61 .in \\n(OIu
  62 .if \\n(TM .ls 2
  63 .sp \\n(DDu
  64 .fi
  65 ..
  66 .de FD
  67 .LP
  68 .KS
  69 .TA .5i 3i
  70 .ta .5i 3i
  71 .nf
  72 ..
  73 .de FN
  74 .fi
  75 .KE
  76 .LP
  77 ..
  78 .de IN          \" send an index entry to the stderr
  79 ..
  80 .de C{
  81 .KS
  82 .nf
  83 .D
  84 .\"
  85 .\"     choose appropriate monospace font
  86 .\"     the imagen conditional, 480,
  87 .\"     may be changed to L if LB is too
  88 .\"     heavy for your eyes...
  89 .\"
  90 .ie "\\*(.T"480" .ft L
  91 .el .ie "\\*(.T"300" .ft L
  92 .el .ie "\\*(.T"202" .ft PO
  93 .el .ie "\\*(.T"aps" .ft CW
  94 .el .ft R
  95 .ps \\n(PS
  96 .ie \\n(VS>40 .vs \\n(VSu
  97 .el .vs \\n(VSp
  98 ..
  99 .de C}
 100 .DE
 101 .R
 102 ..
 103 .de Pn
 104 .ie t \\$1\fB\^\\$2\^\fR\\$3
 105 .el \\$1\fI\^\\$2\^\fP\\$3
 106 ..
 107 .de ZN
 108 .ie t \fB\^\\$1\^\fR\\$2
 109 .el \fI\^\\$1\^\fP\\$2
 110 ..
 111 .de hN
 112 .ie t <\fB\\$1\fR>\\$2
 113 .el <\fI\\$1\fP>\\$2
 114 ..
 115 .de NT
 116 .ne 7
 117 .ds NO Note
 118 .if \\n(.$>$1 .if !'\\$2'C' .ds NO \\$2
 119 .if \\n(.$ .if !'\\$1'C' .ds NO \\$1
 120 .ie n .sp
 121 .el .sp 10p
 122 .TB
 123 .ce
 124 \\*(NO
 125 .ie n .sp
 126 .el .sp 5p
 127 .if '\\$1'C' .ce 99
 128 .if '\\$2'C' .ce 99
 129 .in +5n
 130 .ll -5n
 131 .R
 132 ..
 133 .               \" Note End -- doug kraft 3/85
 134 .de NE
 135 .ce 0
 136 .in -5n
 137 .ll +5n
 138 .ie n .sp
 139 .el .sp 10p
 140 ..
 141 .ny0
 142 .TH XGetWindowProperty __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 143 .SH NAME
 144 XGetWindowProperty, XListProperties, XChangeProperty, XRotateWindowProperties, XDeleteProperty \- obtain and change window properties
 145 .SH SYNTAX
 146 .HP
 147 int XGetWindowProperty\^(\^Display *\fIdisplay\fP\^, Window \fIw\fP\^, Atom
 148 \fIproperty\fP\^, long \fIlong_offset\fP\^, long \fIlong_length\fP\^, Bool
 149 \fIdelete\fP\^, Atom \fIreq_type\fP\^, Atom *\fIactual_type_return\fP\^, int
 150 *\fIactual_format_return\fP\^, unsigned long *\fInitems_return\fP\^, unsigned
 151 long *\fIbytes_after_return\fP\^, unsigned char **\fIprop_return\fP\^);
 152 .HP
 153 Atom *XListProperties\^(\^Display *\fIdisplay\fP\^, Window \fIw\fP\^, int
 154 *\fInum_prop_return\fP\^);
 155 .HP
 156 int XChangeProperty\^(\^Display *\fIdisplay\fP\^, Window \fIw\fP\^, Atom
 157 \fIproperty\fP\^, Atom \fItype\fP\^, int \fIformat\fP\^, int \fImode\fP\^,
 158 unsigned char *\fIdata\fP\^, int \fInelements\fP\^);
 159 .HP
 160 int XRotateWindowProperties\^(\^Display *\fIdisplay\fP\^, Window \fIw\fP\^,
 161 Atom \fIproperties\fP\^[]\^, int \fInum_prop\fP\^, int \fInpositions\fP\^);
 162 .HP
 163 int XDeleteProperty\^(\^Display *\fIdisplay\fP\^, Window \fIw\fP\^, Atom
 164 \fIproperty\fP\^);
 165 .SH ARGUMENTS
 166 .IP \fIactual_format_return\fP 1i
 167 Returns the actual format of the property.
 168 .IP \fIactual_type_return\fP 1i
 169 Returns the atom identifier  that defines the actual type of the property.
 170 .IP \fIbytes_after_return\fP 1i
 171 Returns the number of bytes remaining to be read in the property if
 172 a partial read was performed.
 173 .IP \fIdata\fP 1i
 174 Specifies the property data.
 175 .IP \fIdelete\fP 1i
 176 Specifies a Boolean value that determines whether the property is deleted.
 177 .IP \fIdisplay\fP 1i
 178 Specifies the connection to the X server.
 179 .IP \fIformat\fP 1i
 180 Specifies whether the data should be viewed as a list
 181 of 8-bit, 16-bit, or 32-bit quantities.
 182 Possible values are 8, 16, and 32.
 183 This information allows the X server to correctly perform
 184 byte-swap operations as necessary.
 185 If the format is 16-bit or 32-bit,
 186 you must explicitly cast your data pointer to an (unsigned char *) in the call
 187 to
 188 .ZN XChangeProperty .
 189 .IP \fIlong_length\fP 1i
 190 Specifies the length in 32-bit multiples of the data to be retrieved.
 191 .IP \fIlong_offset\fP 1i
 192 Specifies the offset in the specified property (in 32-bit quantities)
 193 where the data is to be retrieved.
 194 .\" Changed name of this file to prop_mode.a on 1/13/87
 195 .IP \fImode\fP 1i
 196 Specifies the mode of the operation.
 197 You can pass
 198 .ZN PropModeReplace ,
 199 .ZN PropModePrepend ,
 200 or
 201 .ZN PropModeAppend .
 202 .IP \fInelements\fP 1i
 203 Specifies the number of elements of the specified data format.
 204 .IP \fInitems_return\fP 1i
 205 Returns the actual number of 8-bit, 16-bit, or 32-bit items
 206 stored in the prop_return data.
 207 .IP \fInum_prop\fP 1i
 208 Specifies the length of the properties array.
 209 .IP \fInum_prop_return\fP 1i
 210 Returns the length of the properties array.
 211 .IP \fInpositions\fP 1i
 212 Specifies the rotation amount.
 213 .IP \fIprop_return\fP 1i
 214 Returns the data in the specified format.
 215 If the returned format is 8, the returned data is represented as a
 216 char array. If the returned format is 16, the returned data is
 217 represented as a array of short int type and should be cast to that
 218 type to obtain the elements. If the returned format is 32, the
 219 property data will be stored as an array of longs (which in a 64-bit
 220 application will be 64-bit values that are padded in the upper 4 bytes).
 221 .IP \fIproperty\fP 1i
 222 Specifies the property name.
 223 .IP \fIproperties\fP 1i
 224 Specifies the array of properties that are to be rotated.
 225 .IP \fIreq_type\fP 1i
 226 Specifies the atom identifier associated with the property type or
 227 .ZN AnyPropertyType .
 228 .IP \fItype\fP 1i
 229 Specifies the type of the property.
 230 The X server does not interpret the type but simply
 231 passes it back to an application that later calls
 232 .ZN XGetWindowProperty .
 233 .ds Wi whose property you want to obtain, change, rotate or delete
 234 .IP \fIw\fP 1i
 235 Specifies the window \*(Wi.
 236 .SH DESCRIPTION
 237 The
 238 .ZN XGetWindowProperty
 239 function returns the actual type of the property; the actual format of the property;
 240 the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining
 241 to be read in the property; and a pointer to the data actually returned.
 242 .ZN XGetWindowProperty
 243 sets the return arguments as follows:
 244 .IP \(bu 5
 245 If the specified property does not exist for the specified window,
 246 .ZN XGetWindowProperty
 247 returns
 248 .ZN None
 249 to actual_type_return and the value zero to
 250 actual_format_return and bytes_after_return.
 251 The nitems_return argument is empty.
 252 In this case, the delete argument is ignored.
 253 .IP \(bu 5
 254 If the specified property exists
 255 but its type does not match the specified type,
 256 .ZN XGetWindowProperty
 257 returns the actual property type to actual_type_return,
 258 the actual property format (never zero) to actual_format_return,
 259 and the property length in bytes
 260 (even if the actual_format_return is 16 or 32)
 261 to bytes_after_return.
 262 It also ignores the delete argument.
 263 The nitems_return argument is empty.
 264 .IP \(bu 5
 265 If the specified property exists and either you assign
 266 .ZN AnyPropertyType
 267 to the req_type argument or the specified type matches the actual property type,
 268 .ZN XGetWindowProperty
 269 returns the actual property type to actual_type_return and the actual
 270 property format (never zero) to actual_format_return.
 271 It also returns a value to bytes_after_return and nitems_return, by
 272 defining the following
 273 values:
 274 .IP
 275 .nf
 276         N = actual length of the stored property in bytes
 277              (even if the format is 16 or 32)
 278         I = 4 * long_offset
 279         T = N - I
 280         L = MINIMUM(T, 4 * long_length)
 281         A = N - (I + L)
 282 .fi
 283 .IP
 284 The returned value starts at byte index I in the property (indexing
 285 from zero), and its length in bytes is L.
 286 If the value for long_offset causes L to be negative,
 287 a
 288 .ZN BadValue
 289 error results.
 290 The value of bytes_after_return is A,
 291 giving the number of trailing unread bytes in the stored property.
 292 .LP
 293 If the returned format is 8, the returned data is represented as a
 294 .ZN char
 295 array.
 296 If the returned format is 16, the returned data is represented as a
 297 .ZN short
 298 array and should be cast to that type to obtain the elements.
 299 If the returned format is 32, the returned data is represented as a
 300 .ZN long
 301 array and should be cast to that type to obtain the elements.
 302 .LP
 303 .ZN XGetWindowProperty
 304 always allocates one extra byte in prop_return
 305 (even if the property is zero length)
 306 and sets it to zero so that simple properties consisting of characters
 307 do not have to be copied into yet another string before use.
 308 .LP
 309 If delete is
 310 .ZN True
 311 and bytes_after_return is zero,
 312 .ZN XGetWindowProperty
 313 deletes the property
 314 from the window and generates a
 315 .ZN PropertyNotify
 316 event on the window.
 317 .LP
 318 The function returns
 319 .ZN Success
 320 if it executes successfully.
 321 To free the resulting data,
 322 use
 323 .ZN XFree .
 324 .LP
 325 .ZN XGetWindowProperty
 326 can generate
 327 .ZN BadAtom ,
 328 .ZN BadValue ,
 329 and
 330 .ZN BadWindow
 331 errors.
 332 .LP
 333 The
 334 .ZN XListProperties
 335 function returns a pointer to an array of atom properties that are defined for
 336 the specified window or returns NULL if no properties were found.
 337 To free the memory allocated by this function, use
 338 .ZN XFree .
 339 .LP
 340 .ZN XListProperties
 341 can generate a
 342 .ZN BadWindow
 343 error.
 344 .LP
 345 The
 346 .ZN XChangeProperty
 347 function alters the property for the specified window and
 348 causes the X server to generate a
 349 .ZN PropertyNotify
 350 event on that window.
 351 .ZN XChangeProperty
 352 performs the following:
 353 .IP \(bu 5
 354 If mode is
 355 .ZN PropModeReplace ,
 356 .ZN XChangeProperty
 357 discards the previous property value and stores the new data.
 358 .IP \(bu 5
 359 If mode is
 360 .ZN PropModePrepend
 361 or
 362 .ZN PropModeAppend ,
 363 .ZN XChangeProperty
 364 inserts the specified data before the beginning of the existing data
 365 or onto the end of the existing data, respectively.
 366 The type and format must match the existing property value,
 367 or a
 368 .ZN BadMatch
 369 error results.
 370 If the property is undefined,
 371 it is treated as defined with the correct type and
 372 format with zero-length data.
 373 .LP
 374 If the specified format is 8, the property data must be a
 375 .ZN char
 376 array.
 377 If the specified format is 16, the property data must be a
 378 .ZN short
 379 array.
 380 If the specified format is 32, the property data must be a
 381 .ZN long
 382 array.
 383 .LP
 384 The lifetime of a property is not tied to the storing client.
 385 Properties remain until explicitly deleted, until the window is destroyed,
 386 or until the server resets.
 387 For a discussion of what happens when the connection to the X server is closed,
 388 see section 2.6.
 389 The maximum size of a property is server dependent and can vary dynamically
 390 depending on the amount of memory the server has available.
 391 (If there is insufficient space, a
 392 .ZN BadAlloc
 393 error results.)
 394 .LP
 395 .ZN XChangeProperty
 396 can generate
 397 .ZN BadAlloc ,
 398 .ZN BadAtom ,
 399 .ZN BadMatch ,
 400 .ZN BadValue ,
 401 and
 402 .ZN BadWindow
 403 errors.
 404 .LP
 405 The
 406 .ZN XRotateWindowProperties
 407 function allows you to rotate properties on a window and causes
 408 the X server to generate
 409 .ZN PropertyNotify
 410 events.
 411 If the property names in the properties array are viewed as being numbered
 412 starting from zero and if there are num_prop property names in the list,
 413 then the value associated with property name I becomes the value associated
 414 with property name (I + npositions) mod N for all I from zero to N \- 1.
 415 The effect is to rotate the states by npositions places around the virtual ring
 416 of property names (right for positive npositions,
 417 left for negative npositions).
 418 If npositions mod N is nonzero,
 419 the X server generates a
 420 .ZN PropertyNotify
 421 event for each property in the order that they are listed in the array.
 422 If an atom occurs more than once in the list or no property with that
 423 name is defined for the window,
 424 a
 425 .ZN BadMatch
 426 error results.
 427 If a
 428 .ZN BadAtom
 429 or
 430 .ZN BadMatch
 431 error results,
 432 no properties are changed.
 433 .LP
 434 .ZN XRotateWindowProperties
 435 can generate
 436 .ZN BadAtom ,
 437 .ZN BadMatch ,
 438 and
 439 .ZN BadWindow
 440 errors.
 441 .LP
 442 The
 443 .ZN XDeleteProperty
 444 function deletes the specified property only if the
 445 property was defined on the specified window
 446 and causes the X server to generate a
 447 .ZN PropertyNotify
 448 event on the window unless the property does not exist.
 449 .LP
 450 .ZN XDeleteProperty
 451 can generate
 452 .ZN BadAtom
 453 and
 454 .ZN BadWindow
 455 errors.
 456 .SH DIAGNOSTICS
 457 .TP 1i
 458 .ZN BadAlloc
 459 The server failed to allocate the requested resource or server memory.
 460 .TP 1i
 461 .ZN BadAtom
 462 A value for an Atom argument does not name a defined Atom.
 463 .TP 1i
 464 .ZN BadValue
 465 Some numeric value falls outside the range of values accepted by the request.
 466 Unless a specific range is specified for an argument, the full range defined
 467 by the argument's type is accepted.  Any argument defined as a set of
 468 alternatives can generate this error.
 469 .TP 1i
 470 .ZN BadWindow
 471 A value for a Window argument does not name a defined Window.
 472 .SH "SEE ALSO"
 473 XFree(__libmansuffix__),
 474 XInternAtom(__libmansuffix__)
 475 .br
 476 \fI\*(xL\fP