man/XCreateWindow.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 XCreateWindow __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 145 .SH NAME
 146 XCreateWindow, XCreateSimpleWindow, XSetWindowAttributes \- create windows and window attributes structure
 147 .SH SYNTAX
 148 .HP
 149 Window XCreateWindow\^(\^Display *\fIdisplay\fP\^, Window \fIparent\fP\^, int \fIx\fP\^, int \fIy\fP\^, unsigned int \fIwidth\fP\^, unsigned int \fIheight\fP\^, unsigned int \fIborder_width\fP\^, int \fIdepth\fP\^, unsigned int \fIclass\fP\^, Visual *\fIvisual\fP\^, unsigned long \fIvaluemask\fP\^, XSetWindowAttributes *\fIattributes\fP\^);
 150 .HP
 151 Window XCreateSimpleWindow\^(\^Display *\fIdisplay\fP\^, Window \fIparent\fP\^, int \fIx\fP\^, int \fIy\fP\^, unsigned int \fIwidth\fP\^, unsigned int \fIheight\fP\^, unsigned int \fIborder_width\fP\^, unsigned long \fIborder\fP\^, unsigned long \fIbackground\fP\^);
 152 .SH ARGUMENTS
 153 .IP \fIattributes\fP 1i
 154 Specifies the structure from which the values (as specified by the value mask)
 155 are to be taken.
 156 The value mask should have the appropriate bits
 157 set to indicate which attributes have been set in the structure.
 158 .IP \fIbackground\fP 1i
 159 Specifies the background pixel value of the window.
 160
 161 .IP \fIborder\fP 1i
 162 Specifies the border pixel value of the window.
 163 .IP \fIborder_width\fP 1i
 164 Specifies the width of the created window's border in pixels.
 165 .IP \fIclass\fP 1i
 166 Specifies the created window's class.
 167 You can pass
 168 .ZN InputOutput ,
 169 .ZN InputOnly ,
 170 or
 171 .ZN CopyFromParent .
 172 A class of
 173 .ZN CopyFromParent
 174 means the class
 175 is taken from the parent.
 176 .IP \fIdepth\fP 1i
 177 Specifies the window's depth.
 178 A depth of
 179 .ZN CopyFromParent
 180 means the depth is taken from the parent.
 181 .IP \fIdisplay\fP 1i
 182 Specifies the connection to the X server.
 183 .IP \fIparent\fP 1i
 184 Specifies the parent window.
 185 .IP \fIvaluemask\fP 1i
 186 Specifies which window attributes are defined in the attributes
 187 argument.
 188 This mask is the bitwise inclusive OR of the valid attribute mask bits.
 189 If valuemask is zero,
 190 the attributes are ignored and are not referenced.
 191 .IP \fIvisual\fP 1i
 192 Specifies the visual type.
 193 A visual of
 194 .ZN CopyFromParent
 195 means the visual type is taken from the
 196 parent.
 197 .ds Wh , which are the created window's inside dimensions \
 198 and do not include the created window's borders
 199 .IP \fIwidth\fP 1i
 200 .br
 201 .ns
 202 .IP \fIheight\fP 1i
 203 Specify the width and height\*(Wh.
 204 .ds Xy , which are the top-left outside corner of the window's \
 205 borders and are relative to the inside of the parent window's borders
 206 .IP \fIx\fP 1i
 207 .br
 208 .ns
 209 .IP \fIy\fP 1i
 210 Specify the x and y coordinates\*(Xy.
 211 .SH DESCRIPTION
 212 The
 213 .ZN XCreateWindow
 214 function creates an unmapped subwindow for a specified parent window,
 215 returns the window ID of the created window,
 216 and causes the X server to generate a
 217 .ZN CreateNotify
 218 event.
 219 The created window is placed on top in the stacking order
 220 with respect to siblings.
 221 .LP
 222 The coordinate system has the X axis horizontal and the Y axis vertical
 223 with the origin [0, 0] at the upper-left corner.
 224 Coordinates are integral,
 225 in terms of pixels,
 226 and coincide with pixel centers.
 227 Each window and pixmap has its own coordinate system.
 228 For a window,
 229 the origin is inside the border at the inside, upper-left corner.
 230 .LP
 231 The border_width for an
 232 .ZN InputOnly
 233 window must be zero, or a
 234 .ZN BadMatch
 235 error results.
 236 For class
 237 .ZN InputOutput ,
 238 the visual type and depth must be a combination supported for the screen,
 239 or a
 240 .ZN BadMatch
 241 error results.
 242 The depth need not be the same as the parent,
 243 but the parent must not be a window of class
 244 .ZN InputOnly ,
 245 or a
 246 .ZN BadMatch
 247 error results.
 248 For an
 249 .ZN InputOnly
 250 window,
 251 the depth must be zero, and the visual must be one supported by the screen.
 252 If either condition is not met,
 253 a
 254 .ZN BadMatch
 255 error results.
 256 The parent window, however, may have any depth and class.
 257 If you specify any invalid window attribute for a window, a
 258 .ZN BadMatch
 259 error results.
 260 .LP
 261 The created window is not yet displayed (mapped) on the user's display.
 262 To display the window, call
 263 .ZN XMapWindow .
 264 The new window initially uses the same cursor as
 265 its parent.
 266 A new cursor can be defined for the new window by calling
 267 .ZN XDefineCursor .
 268 .IN "Cursor" "Initial State"
 269 .IN "XDefineCursor"
 270 The window will not be visible on the screen unless it and all of its
 271 ancestors are mapped and it is not obscured by any of its ancestors.
 272 .LP
 273 .ZN XCreateWindow
 274 can generate
 275 .ZN BadAlloc
 276 .ZN BadColor ,
 277 .ZN BadCursor ,
 278 .ZN BadMatch ,
 279 .ZN BadPixmap ,
 280 .ZN BadValue ,
 281 and
 282 .ZN BadWindow
 283 errors.
 284 .LP
 285 The
 286 .ZN XCreateSimpleWindow
 287 function creates an unmapped
 288 .ZN InputOutput
 289 subwindow for a specified parent window, returns the
 290 window ID of the created window, and causes the X server to generate a
 291 .ZN CreateNotify
 292 event.
 293 The created window is placed on top in the stacking order with respect to
 294 siblings.
 295 Any part of the window that extends outside its parent window is clipped.
 296 The border_width for an
 297 .ZN InputOnly
 298 window must be zero, or a
 299 .ZN BadMatch
 300 error results.
 301 .ZN XCreateSimpleWindow
 302 inherits its depth, class, and visual from its parent.
 303 All other window attributes, except background and border,
 304 have their default values.
 305 .LP
 306 .ZN XCreateSimpleWindow
 307 can generate
 308 .ZN BadAlloc ,
 309 .ZN BadMatch ,
 310 .ZN BadValue ,
 311 and
 312 .ZN BadWindow
 313 errors.
 314 .SH STRUCTURES
 315 The
 316 .ZN XSetWindow Attributes
 317 structure contains:
 318 .LP
 319 .LP
 320 /\&* Window attribute value mask bits */
 321 .TS
 322 lw(.5i) lw(2.5i) lw(.8i).
 323 T{
 324 \&#define
 325 T}      T{
 326 .ZN CWBackPixmap
 327 T}      T{
 328 (1L<<0)
 329 T}
 330 T{
 331 \&#define
 332 T}      T{
 333 .ZN CWBackPixel
 334 T}      T{
 335 (1L<<1)
 336 T}
 337 T{
 338 \&#define
 339 T}      T{
 340 .ZN CWBorderPixmap
 341 T}      T{
 342 (1L<<2)
 343 T}
 344 T{
 345 \&#define
 346 T}      T{
 347 .ZN CWBorderPixel
 348 T}      T{
 349 (1L<<3)
 350 T}
 351 T{
 352 \&#define
 353 T}      T{
 354 .ZN CWBitGravity
 355 T}      T{
 356 (1L<<4)
 357 T}
 358 T{
 359 \&#define
 360 T}      T{
 361 .ZN CWWinGravity
 362 T}      T{
 363 (1L<<5)
 364 T}
 365 T{
 366 \&#define
 367 T}      T{
 368 .ZN CWBackingStore
 369 T}      T{
 370 (1L<<6)
 371 T}
 372 T{
 373 \&#define
 374 T}      T{
 375 .ZN CWBackingPlanes
 376 T}      T{
 377 (1L<<7)
 378 T}
 379 T{
 380 \&#define
 381 T}      T{
 382 .ZN CWBackingPixel
 383 T}      T{
 384 (1L<<8)
 385 T}
 386 T{
 387 \&#define
 388 T}      T{
 389 .ZN CWOverrideRedirect
 390 T}      T{
 391 (1L<<9)
 392 T}
 393 T{
 394 \&#define
 395 T}      T{
 396 .ZN CWSaveUnder
 397 T}      T{
 398 (1L<<10)
 399 T}
 400 T{
 401 \&#define
 402 T}      T{
 403 .ZN CWEventMask
 404 T}      T{
 405 (1L<<11)
 406 T}
 407 T{
 408 \&#define
 409 T}      T{
 410 .ZN CWDontPropagate
 411 T}      T{
 412 (1L<<12)
 413 T}
 414 T{
 415 \&#define
 416 T}      T{
 417 .ZN CWColormap
 418 T}      T{
 419 (1L<<13)
 420 T}
 421 T{
 422 \&#define
 423 T}      T{
 424 .ZN CWCursor
 425 T}      T{
 426 (1L<<14)
 427 T}
 428 .TE
 429 .IN "XSetWindowAttributes" "" "@DEF@"
 430 .Ds 0
 431 .TA .5i 3i
 432 .ta .5i 3i
 433 /\&* Values */
 434
 435 typedef struct {
 436         Pixmap background_pixmap;       /\&* background, None, or ParentRelative */
 437         unsigned long background_pixel; /\&* background pixel */
 438         Pixmap border_pixmap;           /\&* border of the window or CopyFromParent */
 439         unsigned long border_pixel;     /\&* border pixel value */
 440         int bit_gravity;        /\&* one of bit gravity values */
 441         int win_gravity;        /\&* one of the window gravity values */
 442         int backing_store;      /\&* NotUseful, WhenMapped, Always */
 443         unsigned long backing_planes;   /\&* planes to be preserved if possible */
 444         unsigned long backing_pixel;    /\&* value to use in restoring planes */
 445         Bool save_under;        /\&* should bits under be saved? (popups) */
 446         long event_mask;        /\&* set of events that should be saved */
 447         long do_not_propagate_mask;     /\&* set of events that should not propagate */
 448         Bool override_redirect; /\&* boolean value for override_redirect */
 449         Colormap colormap;      /\&* color map to be associated with window */
 450         Cursor cursor;          /\&* cursor to be displayed (or None) */
 451 } XSetWindowAttributes;
 452 .De
 453 .LP
 454 For a detailed explanation of the members of this structure,
 455 see \fI\*(xL\fP\^.
 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 BadColor
 462 A value for a Colormap argument does not name a defined Colormap.
 463 .TP 1i
 464 .ZN BadCursor
 465 A value for a Cursor argument does not name a defined Cursor.
 466 .TP 1i
 467 .ZN BadMatch
 468 The values do not exist for an
 469 .ZN InputOnly
 470 window.
 471 .TP 1i
 472 .ZN BadMatch
 473 Some argument or pair of arguments has the correct type and range but fails
 474 to match in some other way required by the request.
 475 .TP 1i
 476 .ZN BadPixmap
 477 A value for a Pixmap argument does not name a defined Pixmap.
 478 .TP 1i
 479 .ZN BadValue
 480 Some numeric value falls outside the range of values accepted by the request.
 481 Unless a specific range is specified for an argument, the full range defined
 482 by the argument's type is accepted.  Any argument defined as a set of
 483 alternatives can generate this error.
 484 .TP 1i
 485 .ZN BadWindow
 486 A value for a Window argument does not name a defined Window.
 487 .SH "SEE ALSO"
 488 XChangeWindowAttributes(__libmansuffix__),
 489 XConfigureWindow(__libmansuffix__),
 490 XDefineCursor(__libmansuffix__),
 491 XDestroyWindow(__libmansuffix__),
 492 XMapWindow(__libmansuffix__),
 493 XRaiseWindow(__libmansuffix__),
 494 XUnmapWindow(__libmansuffix__)
 495 .br
 496 \fI\*(xL\fP