man/XSetWMProperties.man

   1 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
   2 .\" Copyright \(co 2000  The XFree86 Project, Inc.
   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 XSetWMProperties __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 144 .SH NAME
 145 XSetWMProperties, XmbSetWMProperties, Xutf8SetWMProperties \- set standard window properties
 146 .SH SYNTAX
 147 .HP
 148 void XSetWMProperties\^(\^Display *\fIdisplay\fP\^, Window \fIw\fP\^,
 149 XTextProperty *\fIwindow_name\fP\^, XTextProperty *\fIicon_name\fP\^, char
 150 **\fIargv\fP\^, int \fIargc\fP\^, XSizeHints *\fInormal_hints\fP\^, XWMHints
 151 *\fIwm_hints\fP\^, XClassHint *\fIclass_hints\fP\^);
 152 .HP
 153 void XmbSetWMProperties\^(\^Display *\fIdisplay\fP\^, Window \fIw\fP\^, char
 154 *\fIwindow_name\fP\^, char *\fIicon_name\fP\^, char *\fIargv\fP\^[], int
 155 \fIargc\fP\^, XSizeHints *\fInormal_hints\fP\^, XWMHints *\fIwm_hints\fP\^,
 156 XClassHint *\fIclass_hints\fP\^);
 157 .HP
 158 void Xutf8SetWMProperties\^(\^Display *\fIdisplay\fP\^, Window \fIw\fP\^, char
 159 *\fIwindow_name\fP\^, char *\fIicon_name\fP\^, char *\fIargv\fP\^[], int
 160 \fIargc\fP\^, XSizeHints *\fInormal_hints\fP\^, XWMHints *\fIwm_hints\fP\^,
 161 XClassHint *\fIclass_hints\fP\^);
 162 .SH ARGUMENTS
 163 .IP \fIargc\fP 1i
 164 Specifies the number of arguments.
 165 .IP \fIargv\fP 1i
 166 Specifies the application's argument list.
 167 .IP \fIclass_hints\fP 1i
 168 Specifies the
 169 .ZN XClassHint
 170 structure to be used.
 171 .IP \fIdisplay\fP 1i
 172 Specifies the connection to the X server.
 173 .IP \fIicon_name\fP 1i
 174 Specifies the icon name,
 175 which should be a null-terminated string.
 176 .IP \fInormal_hints\fP 1i
 177 Specifies the size hints for the window in its normal state.
 178 .IP \fIw\fP 1i
 179 Specifies the window.
 180 .IP \fIwindow_name\fP 1i
 181 Specifies the window name,
 182 which should be a null-terminated string.
 183 .IP \fIwm_hints\fP 1i
 184 Specifies the
 185 .ZN XWMHints
 186 structure to be used.
 187 .SH DESCRIPTION
 188 The
 189 .ZN XSetWMProperties
 190 convenience function provides a single programming interface
 191 for setting those essential window properties that are used
 192 for communicating with other clients (particularly window and session
 193 managers).
 194 .LP
 195 If the window_name argument is non-NULL,
 196 .ZN XSetWMProperties
 197 calls
 198 .ZN XSetWMName ,
 199 which in turn, sets the WM_NAME property (see section 14.1.4).
 200 If the icon_name argument is non-NULL,
 201 .ZN XSetWMProperties
 202 calls
 203 .ZN XSetWMIconName ,
 204 which sets the WM_ICON_NAME property (see section 14.1.5).
 205 If the argv argument is non-NULL,
 206 .ZN XSetWMProperties
 207 calls
 208 .ZN XSetCommand ,
 209 which sets the WM_COMMAND property (see section 14.2.1).
 210 Note that an argc of zero is allowed to indicate a zero-length command.
 211 Note also that the hostname of this machine is stored using
 212 .ZN XSetWMClientMachine
 213 (see section 14.2.2).
 214 .LP
 215 If the normal_hints argument is non-NULL,
 216 .ZN XSetWMProperties
 217 calls
 218 .ZN XSetWMNormalHints ,
 219 which sets the WM_NORMAL_HINTS property (see section 14.1.7).
 220 If the wm_hints argument is non-NULL,
 221 .ZN XSetWMProperties
 222 calls
 223 .ZN XSetWMHints ,
 224 which sets the WM_HINTS property (see section 14.1.6).
 225 .LP
 226 If the class_hints argument is non-NULL,
 227 .ZN XSetWMProperties
 228 calls
 229 .ZN XSetClassHint ,
 230 which sets the WM_CLASS property (see section 14.1.8).
 231 If the res_name member in the
 232 .ZN XClassHint
 233 structure is set to the NULL pointer and the RESOURCE_NAME environment
 234 variable is set,
 235 then the value of the environment variable is substituted for res_name.
 236 If the res_name member is NULL,
 237 the environment variable is not set,
 238 and argv and argv[0] are set,
 239 then the value of argv[0], stripped of
 240 any directory prefixes, is substituted for res_name.
 241 .LP
 242 The
 243 .ZN XmbSetWMProperties
 244 and
 245 .ZN Xutf8SetWMProperties
 246 convenience functions provide a simple programming interface
 247 for setting those essential window properties that are used
 248 for communicating with other clients
 249 (particularly window and session managers).
 250 .LP
 251 If the window_name argument is non-NULL,
 252 they set the WM_NAME property.
 253 If the icon_name argument is non-NULL,
 254 they set the WM_ICON_NAME property.
 255 The window_name and icon_name arguments are null-terminated strings, for
 256 .ZN XmbSetWMProperties
 257 in the encoding of the current locale, for
 258 .ZN Xutf8SetWMProperties
 259 in UTF-8 encoding.
 260 If the arguments can be fully converted to the STRING encoding,
 261 the properties are created with type ``STRING'';
 262 otherwise, the arguments are converted to Compound Text,
 263 and the properties are created with type ``COMPOUND_TEXT''.
 264 .LP
 265 If the normal_hints argument is non-NULL,
 266 .ZN XmbSetWMProperties
 267 and
 268 .ZN Xutf8SetWMProperties
 269 call
 270 .ZN XSetWMNormalHints ,
 271 which sets the WM_NORMAL_HINTS property (see section 14.1.7).
 272 If the wm_hints argument is non-NULL,
 273 .ZN XmbSetWMProperties
 274 and
 275 .ZN Xutf8SetWMProperties
 276 call
 277 .ZN XSetWMHints ,
 278 which sets the WM_HINTS property (see section 14.1.6).
 279 .LP
 280 If the argv argument is non-NULL,
 281 .ZN XmbSetWMProperties
 282 and
 283 .ZN Xutf8SetWMProperties
 284 set the WM_COMMAND property from argv and argc.
 285 An argc of zero indicates a zero-length command.
 286 .LP
 287 The hostname of the machine is stored using
 288 .ZN XSetWMClientMachine
 289 (see section 14.2.2).
 290 .LP
 291 If the class_hints argument is non-NULL,
 292 .ZN XmbSetWMProperties
 293 and
 294 .ZN Xutf8SetWMProperties
 295 set the WM_CLASS property.
 296 If the res_name member in the
 297 .ZN XClassHint
 298 structure is set to the NULL pointer and the RESOURCE_NAME
 299 environment variable is set,
 300 the value of the environment variable is substituted for res_name.
 301 If the res_name member is NULL,
 302 the environment variable is not set, and argv and argv[0] are set,
 303 then the value of argv[0], stripped of any directory prefixes,
 304 is substituted for res_name.
 305 .LP
 306 It is assumed that the supplied class_hints.res_name and argv,
 307 the RESOURCE_NAME environment variable, and the hostname of the machine
 308 are in the encoding of the current locale.
 309 The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties
 310 are typed according to the local host locale announcer.
 311 No encoding conversion is performed for these strings prior to storage
 312 in the properties.
 313 .LP
 314 For clients that need to process the property text in a locale,
 315 .ZN XmbSetWMProperties
 316 and
 317 .ZN Xutf8SetWMProperties
 318 set the WM_LOCALE_NAME property to be the name of the current locale.
 319 The name is assumed to be in the Host Portable Character Encoding
 320 and is converted to STRING for storage in the property.
 321 .LP
 322 .ZN XSetWMProperties ,
 323 .ZN XmbSetWMProperties
 324 and
 325 .ZN Xutf8SetWMProperties
 326 can generate
 327 .ZN BadAlloc
 328 and
 329 .ZN BadWindow
 330 errors.
 331 .LP
 332 The function
 333 .ZN Xutf8SetWMProperties
 334 is an extension introduced by The XFree86 Project, Inc. in their 4.0.2
 335 release. Its presence is
 336 indicated by the macro
 337 .ZN X_HAVE_UTF8_STRING .
 338 .SH PROPERTIES
 339 .TP 1i
 340 \s-1WM_CLASS\s+1
 341 Set by application programs to allow window and session
 342 managers to obtain the application's resources from the resource database.
 343 .TP 1i
 344 \s-1WM_CLIENT_MACHINE\s+1
 345 The string name of the machine on which the client application is running.
 346 .TP 1i
 347 \s-1WM_COMMAND\s+1
 348 The command and arguments, null-separated, used to invoke the
 349 application.
 350 .TP 1i
 351 \s-1WM_HINTS\s+1
 352 Additional hints set by the client for use by the window manager.
 353 The C type of this property is
 354 .ZN XWMHints .
 355 .TP 1i
 356 \s-1WM_ICON_NAME\s+1
 357 The name to be used in an icon.
 358 .TP 1i
 359 \s-1WM_NAME\s+1
 360 The name of the application.
 361 .TP 1i
 362 \s-1WM_NORMAL_HINTS\s+1
 363 Size hints for a window in its normal state.
 364 The C type of this property is
 365 .ZN XSizeHints .
 366 .SH DIAGNOSTICS
 367 .TP 1i
 368 .ZN BadAlloc
 369 The server failed to allocate the requested resource or server memory.
 370 .TP 1i
 371 .ZN BadWindow
 372 A value for a Window argument does not name a defined Window.
 373 .SH "SEE ALSO"
 374 XAllocClassHint(__libmansuffix__),
 375 XAllocIconSize(__libmansuffix__),
 376 XAllocSizeHints(__libmansuffix__),
 377 XAllocWMHints(__libmansuffix__),
 378 XParseGeometry(__libmansuffix__),
 379 XSetCommand(__libmansuffix__),
 380 XSetTransientForHint(__libmansuffix__),
 381 XSetTextProperty(__libmansuffix__),
 382 XSetWMClientMachine(__libmansuffix__),
 383 XSetWMColormapWindows(__libmansuffix__),
 384 XSetWMIconName(__libmansuffix__),
 385 XSetWMName(__libmansuffix__),
 386 XSetWMProtocols(__libmansuffix__),
 387 XStringListToTextProperty(__libmansuffix__),
 388 XTextListToTextProperty(__libmansuffix__)
 389 .br
 390 \fI\*(xL\fP