man/XGetWindowAttributes.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 '\" t
 144 .TH XGetWindowAttributes __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 145 .SH NAME
 146 XGetWindowAttributes, XGetGeometry, XWindowAttributes \- get current window attribute or geometry and current window attributes structure
 147 .SH SYNTAX
 148 .HP
 149 Status XGetWindowAttributes\^(\^Display *\fIdisplay\fP\^, Window \fIw\fP\^,
 150 XWindowAttributes *\fIwindow_attributes_return\fP\^);
 151 .HP
 152 Status XGetGeometry\^(\^Display *\fIdisplay\fP\^, Drawable \fId\fP\^, Window
 153 *\fIroot_return\fP\^, int *\fIx_return\fP\^, int *\fIy_return\fP\^, unsigned
 154 int *\fIwidth_return\fP\^, unsigned int *\fIheight_return\fP\^, unsigned int
 155 *\fIborder_width_return\fP\^, unsigned int *\fIdepth_return\fP\^);
 156 .SH ARGUMENTS
 157 .IP \fIborder_width_return\fP 1i
 158 Returns the border width in pixels.
 159 .ds Dr , which can be a window or a pixmap
 160 .IP \fId\fP 1i
 161 Specifies the drawable\*(Dr.
 162 .IP \fIdepth_return\fP 1i
 163 Returns the depth of the drawable (bits per pixel for the object).
 164 .IP \fIdisplay\fP 1i
 165 Specifies the connection to the X server.
 166 .IP \fIroot_return\fP 1i
 167 Returns the root window.
 168 .ds Wi whose current attributes you want to obtain
 169 .IP \fIw\fP 1i
 170 Specifies the window \*(Wi.
 171 .IP \fIwidth_return\fP 1i
 172 .br
 173 .ns
 174 .IP \fIheight_return\fP 1i
 175 Return the drawable's dimensions (width and height).
 176 .IP \fIwindow_attributes_return\fP 1i
 177 Returns the specified window's attributes in the
 178 .ZN XWindowAttributes
 179 structure.
 180 .IP \fIx_return\fP 1i
 181 .br
 182 .ns
 183 .IP \fIy_return\fP 1i
 184 Return the x and y coordinates that define the location of the drawable.
 185 For a window,
 186 these coordinates specify the upper-left outer corner relative to
 187 its parent's origin.
 188 For pixmaps, these coordinates are always zero.
 189 .SH DESCRIPTION
 190 The
 191 .ZN XGetWindowAttributes
 192 function returns the current attributes for the specified window to an
 193 .ZN XWindowAttributes
 194 structure.  It returns a nonzero status on success; otherwise, it returns a
 195 zero status.
 196 .LP
 197 .ZN XGetWindowAttributes
 198 can generate
 199 .ZN BadDrawable
 200 and
 201 .ZN BadWindow
 202 errors.
 203 .LP
 204 The
 205 .ZN XGetGeometry
 206 function returns the root window and the current geometry of the drawable.
 207 The geometry of the drawable includes the x and y coordinates, width and height,
 208 border width, and depth.
 209 These are described in the argument list.
 210 It is legal to pass to this function a window whose class is
 211 .ZN InputOnly .
 212 It returns a nonzero status on success; otherwise, it returns a
 213 zero status.
 214 .SH STRUCTURES
 215 The
 216 .ZN XWindowAttributes
 217 structure contains:
 218 .LP
 219 .Ds 0
 220 .TA .5i 3i
 221 .ta .5i 3i
 222 typedef struct {
 223         int x, y;       /\&* location of window */
 224         int width, height;      /\&* width and height of window */
 225         int border_width;       /\&* border width of window */
 226         int depth;      /\&* depth of window */
 227         Visual *visual; /\&* the associated visual structure */
 228         Window root;    /\&* root of screen containing window */
 229         int class;      /\&* InputOutput, InputOnly*/
 230         int bit_gravity;        /\&* one of the bit gravity values */
 231         int win_gravity;        /\&* one of the window gravity values */
 232         int backing_store;      /\&* NotUseful, WhenMapped, Always */
 233         unsigned long backing_planes;   /\&* planes to be preserved if possible */
 234         unsigned long backing_pixel;    /\&* value to be used when restoring planes */
 235         Bool save_under;        /\&* boolean, should bits under be saved? */
 236         Colormap colormap;      /\&* color map to be associated with window */
 237         Bool map_installed;     /\&* boolean, is color map currently installed*/
 238         int map_state;  /\&* IsUnmapped, IsUnviewable, IsViewable */
 239         long all_event_masks;   /\&* set of events all people have interest in*/
 240         long your_event_mask;   /\&* my event mask */
 241         long do_not_propagate_mask;     /\&* set of events that should not propagate */
 242         Bool override_redirect; /\&* boolean value for override-redirect */
 243         Screen *screen; /\&* back pointer to correct screen */
 244 } XWindowAttributes;
 245 .De
 246 .LP
 247 The x and y members are set to the upper-left outer
 248 corner relative to the parent window's origin.
 249 The width and height members are set to the inside size of the window,
 250 not including the border.
 251 The border_width member is set to the window's border width in pixels.
 252 The depth member is set to the depth of the window
 253 (that is, bits per pixel for the object).
 254 The visual member is a pointer to the screen's associated
 255 .ZN Visual
 256 structure.
 257 The root member is set to the root window of the screen containing the window.
 258 The class member is set to the window's class and can be either
 259 .ZN InputOutput
 260 or
 261 .ZN InputOnly .
 262 .LP
 263 The bit_gravity member is set to the window's bit gravity
 264 and can be one of the following:
 265 .LP
 266 .TS
 267 lw(1.5i) lw(1.5i).
 268 T{
 269 .ZN ForgetGravity
 270 T}      T{
 271 .ZN EastGravity
 272 T}
 273 T{
 274 .ZN NorthWestGravity
 275 T}      T{
 276 .ZN SouthWestGravity
 277 T}
 278 T{
 279 .ZN NorthGravity
 280 T}      T{
 281 .ZN SouthGravity
 282 T}
 283 T{
 284 .ZN NorthEastGravity
 285 T}      T{
 286 .ZN SouthEastGravity
 287 T}
 288 T{
 289 .ZN WestGravity
 290 T}      T{
 291 .ZN StaticGravity
 292 T}
 293 .ZN CenterGravity
 294 .TE
 295 .LP
 296 The win_gravity member is set to the window's window gravity
 297 and can be one of the following:
 298 .LP
 299 .TS
 300 lw(1.5i) lw(1.5i).
 301 T{
 302 .ZN UnmapGravity
 303 T}      T{
 304 .ZN EastGravity
 305 T}
 306 T{
 307 .ZN NorthWestGravity
 308 T}      T{
 309 .ZN SouthWestGravity
 310 T}
 311 T{
 312 .ZN NorthGravity
 313 T}      T{
 314 .ZN SouthGravity
 315 T}
 316 T{
 317 .ZN NorthEastGravity
 318 T}      T{
 319 .ZN SouthEastGravity
 320 T}
 321 T{
 322 .ZN WestGravity
 323 T}      T{
 324 .ZN StaticGravity
 325 T}
 326 .ZN CenterGravity
 327 .TE
 328 .LP
 329 For additional information on gravity,
 330 see section 3.3.
 331 .LP
 332 The backing_store member is set to indicate how the X server should maintain
 333 the contents of a window
 334 and can be
 335 .ZN WhenMapped ,
 336 .ZN Always ,
 337 or
 338 .ZN NotUseful .
 339 The backing_planes member is set to indicate (with bits set to 1) which bit
 340 planes of the window hold dynamic data that must be preserved in backing_stores
 341 and during save_unders.
 342 The backing_pixel member is set to indicate what values to use
 343 for planes not set in backing_planes.
 344 .LP
 345 The save_under member is set to
 346 .ZN True
 347 or
 348 .ZN False .
 349 The colormap member is set to the colormap for the specified window and can be
 350 a colormap ID or
 351 .ZN None .
 352 The map_installed member is set to indicate whether the colormap is
 353 currently installed and can be
 354 .ZN True
 355 or
 356 .ZN False .
 357 The map_state member is set to indicate the state of the window and can be
 358 .ZN IsUnmapped ,
 359 .ZN IsUnviewable ,
 360 or
 361 .ZN IsViewable .
 362 .ZN IsUnviewable
 363 is used if the window is mapped but some ancestor is unmapped.
 364 .LP
 365 The all_event_masks member is set to the bitwise inclusive OR of all event
 366 masks selected on the window by all clients.
 367 The your_event_mask member is set to the bitwise inclusive OR of all event
 368 masks selected by the querying client.
 369 The do_not_propagate_mask member is set to the bitwise inclusive OR of the
 370 set of events that should not propagate.
 371 .LP
 372 The override_redirect member is set to indicate whether this window overrides
 373 structure control facilities and can be
 374 .ZN True
 375 or
 376 .ZN False .
 377 Window manager clients should ignore the window if this member is
 378 .ZN True .
 379 .LP
 380 The screen member is set to a screen pointer that gives you a back pointer
 381 to the correct screen.
 382 This makes it easier to obtain the screen information without
 383 having to loop over the root window fields to see which field matches.
 384 .SH DIAGNOSTICS
 385 .TP 1i
 386 .ZN BadDrawable
 387 A value for a Drawable argument does not name a defined Window or Pixmap.
 388 .TP 1i
 389 .ZN BadWindow
 390 A value for a Window argument does not name a defined Window.
 391 .SH "SEE ALSO"
 392 XQueryPointer(__libmansuffix__),
 393 XQueryTree(__libmansuffix__)
 394 .br
 395 \fI\*(xL\fP