man/XAllocSizeHints.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, \fRO'Reilly and Associates,
  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 XAllocSizeHints __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 145 .SH NAME
 146 XAllocSizeHints, XSetWMNormalHints, XGetWMNormalHints, XSetWMSizeHints, XGetWMSizeHints, XSizeHints \- allocate size hints structure and set or read a window's WM_NORMAL_HINTS property
 147 .SH SYNTAX
 148 .HP
 149 XSizeHints *XAllocSizeHints\^(void\^);
 150 .HP
 151 void XSetWMNormalHints\^(\^Display *\fIdisplay\fP, Window \fIw\fP, XSizeHints *\fIhints\fP\^);
 152 .HP
 153 Status XGetWMNormalHints\^(\^Display *\fIdisplay\fP, Window \fIw\fP,
 154 XSizeHints *\fIhints_return\fP, long *\fIsupplied_return\fP\^);
 155 .HP
 156 void XSetWMSizeHints\^(\^Display *\fIdisplay\fP, Window \fIw\fP, XSizeHints
 157 *\fIhints\fP, Atom \fIproperty\fP\^);
 158 .HP
 159 Status XGetWMSizeHints\^(\^Display *\fIdisplay\fP, Window \fIw\fP, XSizeHints
 160 *\fIhints_return\fP, long *\fIsupplied_return\fP, Atom \fIproperty\fP\^);
 161 .SH ARGUMENTS
 162 .IP \fIdisplay\fP 1i
 163 Specifies the connection to the X server.
 164 .IP \fIhints\fP 1i
 165 Specifies the size hints for the window in its normal state.
 166 .IP \fIhints\fP 1i
 167 Specifies the
 168 .ZN XSizeHints
 169 structure to be used.
 170 .IP \fIhints_return\fP 1i
 171 Returns the size hints for the window in its normal state.
 172 .IP \fIproperty\fP 1i
 173 Specifies the property name.
 174 .IP \fIsupplied_return\fP 1i
 175 Returns the hints that were supplied by the user.
 176 .IP \fIw\fP 1i
 177 Specifies the window.
 178 .SH DESCRIPTION
 179 The
 180 .ZN XAllocSizeHints
 181 function allocates and returns a pointer to a
 182 .ZN XSizeHints
 183 structure.
 184 Note that all fields in the
 185 .ZN XSizeHints
 186 structure are initially set to zero.
 187 If insufficient memory is available,
 188 .ZN XAllocSizeHints
 189 returns NULL.
 190 To free the memory allocated to this structure,
 191 use
 192 .ZN XFree .
 193 .LP
 194 The
 195 .ZN XSetWMNormalHints
 196 function replaces the size hints for the WM_NORMAL_HINTS property
 197 on the specified window.
 198 If the property does not already exist,
 199 .ZN XSetWMNormalHints
 200 sets the size hints for the WM_NORMAL_HINTS property on the specified window.
 201 The property is stored with a type of WM_SIZE_HINTS and a format of 32.
 202 .LP
 203 .ZN XSetWMNormalHints
 204 can generate
 205 .ZN BadAlloc
 206 and
 207 .ZN BadWindow
 208 errors.
 209 .LP
 210 The
 211 .ZN XGetWMNormalHints
 212 function returns the size hints stored in the WM_NORMAL_HINTS property
 213 on the specified window.
 214 If the property is of type WM_SIZE_HINTS, is of format 32,
 215 and is long enough to contain either an old (pre-ICCCM)
 216 or new size hints structure,
 217 .ZN XGetWMNormalHints
 218 sets the various fields of the
 219 .ZN XSizeHints
 220 structure, sets the supplied_return argument to the list of fields
 221 that were supplied by the user (whether or not they contained defined values),
 222 and returns a nonzero status.
 223 Otherwise, it returns a zero status.
 224 .LP
 225 If
 226 .ZN XGetWMNormalHints
 227 returns successfully and a pre-ICCCM size hints property is read,
 228 the supplied_return argument will contain the following bits:
 229 .LP
 230 .Ds
 231 (USPosition|USSize|PPosition|PSize|PMinSize|
 232  PMaxSize|PResizeInc|PAspect)
 233 .De
 234 .LP
 235 If the property is large enough to contain the base size
 236 and window gravity fields as well,
 237 the supplied_return argument will also contain the following bits:
 238 .LP
 239 .Ds
 240 PBaseSize|PWinGravity
 241 .De
 242 .LP
 243 .ZN XGetWMNormalHints
 244 can generate a
 245 PN BadWindow
 246 error.
 247 .LP
 248 The
 249 .ZN XSetWMSizeHints
 250 function replaces the size hints for the specified property
 251 on the named window.
 252 If the specified property does not already exist,
 253 .ZN XSetWMSizeHints
 254 sets the size hints for the specified property
 255 on the named window.
 256 The property is stored with a type of WM_SIZE_HINTS and a format of 32.
 257 To set a window's normal size hints,
 258 you can use the
 259 .ZN XSetWMNormalHints
 260 function.
 261 .LP
 262 .ZN XSetWMSizeHints
 263 can generate
 264 .ZN BadAlloc ,
 265 .ZN BadAtom ,
 266 and
 267 .ZN BadWindow
 268 errors.
 269 .LP
 270 The
 271 .ZN XGetWMSizeHints
 272 function returns the size hints stored in the specified property
 273 on the named window.
 274 If the property is of type WM_SIZE_HINTS, is of format 32,
 275 and is long enough to contain either an old (pre-ICCCM)
 276 or new size hints structure,
 277 .ZN XGetWMSizeHints
 278 sets the various fields of the
 279 .ZN XSizeHints
 280 structure, sets the supplied_return argument to the
 281 list of fields that were supplied by the user
 282 (whether or not they contained defined values),
 283 and returns a nonzero status.
 284 Otherwise, it returns a zero status.
 285 To get a window's normal size hints,
 286 you can use the
 287 .ZN XGetWMNormalHints
 288 function.
 289 .LP
 290 If
 291 .ZN XGetWMSizeHints
 292 returns successfully and a pre-ICCCM size hints property is read,
 293 the supplied_return argument will contain the following bits:
 294 .LP
 295 .Ds
 296 (USPosition|USSize|PPosition|PSize|PMinSize|
 297  PMaxSize|PResizeInc|PAspect)
 298 .De
 299 .LP
 300 If the property is large enough to contain the base size
 301 and window gravity fields as well,
 302 the supplied_return argument will also contain the following bits:
 303 .LP
 304 .Ds
 305 PBaseSize|PWinGravity
 306 .De
 307 .LP
 308 .ZN XGetWMSizeHints
 309 can generate
 310 .ZN BadAtom
 311 and
 312 .ZN BadWindow
 313 errors.
 314 .SH PROPERTIES
 315 .TP 1i
 316 \s-1WM_NORMAL_HINTS\s+1
 317 Size hints for a window in its normal state.
 318 The C type of this property is
 319 .ZN XSizeHints .
 320 .SH STRUCTURES
 321 The
 322 .ZN XSizeHints
 323 structure contains:
 324 .LP
 325 /\&* Size hints mask bits */
 326 .TS
 327 lw(.5i) lw(1.1i) lw(1.5i) lw(3.1i).
 328 T{
 329 \&#define
 330 T}      T{
 331 .ZN USPosition
 332 T}      T{
 333 (1L << 0)
 334 T}      T{
 335 /\&* user specified x, y */
 336 T}
 337 T{
 338 \&#define
 339 T}      T{
 340 .ZN USSize
 341 T}      T{
 342 (1L << 1)
 343 T}      T{
 344 /\&* user specified width, height */
 345 T}
 346 T{
 347 \&#define
 348 T}      T{
 349 .ZN PPosition
 350 T}      T{
 351 (1L << 2)
 352 T}      T{
 353 /\&* program specified position */
 354 T}
 355 T{
 356 \&#define
 357 T}      T{
 358 .ZN PSize
 359 T}      T{
 360 (1L << 3)
 361 T}      T{
 362 /\&* program specified size */
 363 T}
 364 T{
 365 \&#define
 366 T}      T{
 367 .ZN PMinSize
 368 T}      T{
 369 (1L << 4)
 370 T}      T{
 371 /\&* program specified minimum size */
 372 T}
 373 T{
 374 \&#define
 375 T}      T{
 376 .ZN PMaxSize
 377 T}      T{
 378 (1L << 5)
 379 T}      T{
 380 /\&* program specified maximum size */
 381 T}
 382 T{
 383 \&#define
 384 T}      T{
 385 .ZN PResizeInc
 386 T}      T{
 387 (1L << 6)
 388 T}      T{
 389 /\&* program specified resize increments */
 390 T}
 391 T{
 392 \&#define
 393 T}      T{
 394 .ZN PAspect
 395 T}      T{
 396 (1L << 7)
 397 T}      T{
 398 /\&* program specified min and max aspect ratios */
 399 T}
 400 T{
 401 \&#define
 402 T}      T{
 403 .ZN PBaseSize
 404 T}      T{
 405 (1L << 8)
 406 T}
 407 T{
 408 \&#define
 409 T}      T{
 410 .ZN PWinGravity
 411 T}      T{
 412 (1L << 9)
 413 T}
 414 T{
 415 \&#define
 416 T}      T{
 417 .ZN PAllHints
 418 T}      T{
 419 (PPosition|PSize|
 420 .br
 421 PMinSize|PMaxSize|
 422 .br
 423 PResizeInc|PAspect)
 424 T}      T{
 425 T}
 426 .TE
 427 .IN "XSizeHints" "" "@DEF@"
 428 .Ds 0
 429 .TA .5i 2.5i
 430 .ta .5i 2.5i
 431 /\&* Values */
 432
 433 typedef struct {
 434         long flags;     /\&* marks which fields in this structure are defined */
 435         int x, y;       /\&* Obsolete */
 436         int width, height;      /\&* Obsolete */
 437         int min_width, min_height;
 438         int max_width, max_height;
 439         int width_inc, height_inc;
 440         struct {
 441                int x;   /\&* numerator */
 442                int y;   /\&* denominator */
 443         } min_aspect, max_aspect;
 444         int base_width, base_height;
 445         int win_gravity;
 446         /\&* this structure may be extended in the future */
 447 } XSizeHints;
 448 .De
 449 .LP
 450 The x, y, width, and height members are now obsolete
 451 and are left solely for compatibility reasons.
 452 The min_width and min_height members specify the
 453 minimum window size that still allows the application to be useful.
 454 The max_width and max_height members specify the maximum window size.
 455 The width_inc and height_inc members define an arithmetic progression of
 456 sizes (minimum to maximum) into which the window prefers to be resized.
 457 The min_aspect and max_aspect members are expressed
 458 as ratios of x and y,
 459 and they allow an application to specify the range of aspect
 460 ratios it prefers.
 461 The base_width and base_height members define the desired size of the window.
 462 The window manager will interpret the position of the window
 463 and its border width to position the point of the outer rectangle
 464 of the overall window specified by the win_gravity member.
 465 The outer rectangle of the window includes any borders or decorations
 466 supplied by the window manager.
 467 In other words,
 468 if the window manager decides to place the window where the client asked,
 469 the position on the parent window's border named by the win_gravity
 470 will be placed where the client window would have been placed
 471 in the absence of a window manager.
 472 .LP
 473 Note that use of the
 474 .ZN PAllHints
 475 macro is highly discouraged.
 476 .SH DIAGNOSTICS
 477 .TP 1i
 478 .ZN BadAlloc
 479 The server failed to allocate the requested resource or server memory.
 480 .TP 1i
 481 .ZN BadAtom
 482 A value for an Atom argument does not name a defined Atom.
 483 .TP 1i
 484 .ZN BadWindow
 485 A value for a Window argument does not name a defined Window.
 486 .SH "SEE ALSO"
 487 XAllocClassHint(__libmansuffix__),
 488 XAllocIconSize(__libmansuffix__),
 489 XAllocWMHints(__libmansuffix__),
 490 XFree(__libmansuffix__),
 491 XSetCommand(__libmansuffix__),
 492 XSetTransientForHint(__libmansuffix__),
 493 XSetTextProperty(__libmansuffix__),
 494 XSetWMClientMachine(__libmansuffix__),
 495 XSetWMColormapWindows(__libmansuffix__),
 496 XSetWMIconName(__libmansuffix__),
 497 XSetWMName(__libmansuffix__),
 498 XSetWMProperties(__libmansuffix__),
 499 XSetWMProtocols(__libmansuffix__),
 500 XStringListToTextProperty(__libmansuffix__)
 501 .br
 502 \fI\*(xL\fP