1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
4 <chapter id='Inter_Client_Communication_Functions'>
5 <title>Inter-Client Communication Functions</title>
7 The <citetitle>Inter-Client Communication Conventions Manual</citetitle>,
8 hereafter referred to as the <acronym>ICCCM</acronym>,
9 details the X Consortium approved conventions that govern inter-client communications. These
10 conventions ensure peer-to-peer client cooperation in the use of selections, cut buffers, and shared
11 resources as well as client cooperation with window and session managers. For further information,
12 see the <olink targetdoc='icccm' targetptr='icccm'><citetitle>Inter-Client Communication Conventions Manual</citetitle></olink>.
15 Xlib provides a number of standard properties and programming interfaces that are <acronym>ICCCM</acronym>
16 compliant. The predefined atoms for some of these properties are defined in the <X11/Xatom.h>
17 header file, where to avoid name conflicts with user symbols their #define name has an XA_ prefix.
18 For further information about atoms and properties,
19 see <link linkend="Properties_and_Atoms">section 4.3</link>.
22 Xlib’s selection and cut buffer mechanisms provide the primary programming interfaces by which
23 peer client applications communicate with each other
24 (see sections <link linkend="Selections">4.5</link> and
25 <link linkend="Using_Cut_Buffers">16.6</link>). The functions
26 discussed in this chapter provide the primary programming interfaces by which client applications
27 communicate with their window and session managers as well as share standard colormaps.
30 The standard properties that are of special interest for communicating with window and session
34 <informaltable frame='topbot'>
35 <?dbfo keep-together="always" ?>
36 <tgroup cols='4' align='left' colsep='0' rowsep='0'>
37 <colspec colname='c1' colwidth='3.0*'/>
38 <colspec colname='c2' colwidth='2.3*'/>
39 <colspec colname='c3' colwidth='0.9*'/>
40 <colspec colname='c4' colwidth='2.7*'/>
46 <entry>Description</entry>
51 <entry><property>WM_CLASS</property></entry>
54 <entry>Set by application programs to allow
55 window and session managers to
56 obtain the application’s resources
57 from the resource database.
61 <entry><property>WM_CLIENT_MACHINE</property></entry>
64 <entry>The string name of the machine on
65 which the client application is running.
69 <entry><property>WM_COLORMAP_WINDOWS</property></entry>
70 <entry>WINDOWS</entry>
72 <entry>The list of window IDs that may
73 need a different colormap from that
74 of their top-level window.
78 <entry><property>WM_COMMAND</property></entry>
81 <entry>The command and arguments, null
82 separated, used to invoke the application.
86 <entry><property>WM_HINTS</property></entry>
87 <entry><property>WM_HINTS</property></entry>
89 <entry>Additional hints set by the client for
90 use by the window manager. The C
91 type of this property is XWMHints.
95 <entry><property>WM_ICON_NAME</property></entry>
98 <entry>The name to be used in an icon.</entry>
101 <entry><property>WM_ICON_SIZE</property></entry>
102 <entry><property>WM_ICON_SIZE</property></entry>
104 <entry>The window manager may set this
105 property on the root window to
106 specify the icon sizes it supports.
107 The C type of this property is
112 <entry><property>WM_NAME</property></entry>
115 <entry>The name of the application.</entry>
118 <entry><property>WM_NORMAL_HINTS</property></entry>
119 <entry><property>WM_NORMAL_HINTS</property></entry>
121 <entry>Size hints for a window in its
122 normal state. The C type of this
123 property is XSizeHints.
127 <entry><property>WM_PROTOCOLS</property></entry>
130 <entry>List of atoms that identify the
131 communications protocols between the
132 client and window manager in
133 which the client is willing to participate.
137 <entry><property>WM_STATE</property></entry>
138 <entry><property>WM_STATE</property></entry>
140 <entry>Intended for communication
141 between window and session managers only.
145 <entry><property>WM_TRANSIENT_FOR</property></entry>
146 <entry>WINDOW</entry>
148 <entry>Set by application programs to
149 indicate to the window manager that a
150 transient top-level window, such as a
159 The remainder of this chapter discusses:
163 <listitem><para>Client to window manager communication</para></listitem>
164 <listitem><para>Client to session manager communication</para></listitem>
165 <listitem><para>Standard colormaps</para></listitem>
168 <sect1 id="Client_to_Window_Manager_Communication">
169 <title>Client to Window Manager Communication</title>
171 <!-- (SN Client to Window Manager Communication -->
175 This section discusses how to:
180 Manipulate top-level windows
190 Set and read text properties
195 Set and read the <property>WM_NAME</property> property
200 Set and read the <property>WM_ICON_NAME</property> property
205 Set and read the <property>WM_HINTS</property> property
210 Set and read the <property>WM_NORMAL_HINTS</property> property
215 Set and read the <property>WM_CLASS</property> property
220 Set and read the <property>WM_TRANSIENT_FOR</property> property
225 Set and read the <property>WM_PROTOCOLS</property> property
230 Set and read the <property>WM_COLORMAP_WINDOWS</property> property
235 Set and read the <property>WM_ICON_SIZE</property> property
240 Use window manager convenience functions
244 <sect2 id="Manipulating_Top_Level_Windows">
245 <title>Manipulating Top-Level Windows</title>
247 <!-- (SN Manipulating Top-Level Windows -->
251 Xlib provides functions that you can use to change the visibility or size
252 of top-level windows (that is, those that were created as children
254 Note that the subwindows that you create are ignored by window managers.
256 you should use the basic window functions described in
257 <link linkend='Window_Functions'>chapter 3</link>
258 to manipulate your application's subwindows.
262 To request that a top-level window be iconified, use
263 <xref linkend='XIconifyWindow' xrefstyle='select: title'/>.
265 <indexterm significance="preferred"><primary>XIconifyWindow</primary></indexterm>
267 <funcsynopsis id='XIconifyWindow'>
269 <funcdef>Status <function>XIconifyWindow</function></funcdef>
270 <paramdef>Display<parameter> *display</parameter></paramdef>
271 <paramdef>Window<parameter> w</parameter></paramdef>
272 <paramdef>int<parameter> screen_number</parameter></paramdef>
279 <emphasis remap='I'>display</emphasis>
283 Specifies the connection to the X server.
289 <emphasis remap='I'>w</emphasis>
293 Specifies the window.
299 <emphasis remap='I'>screen_number</emphasis>
303 Specifies the appropriate screen number on the host server.
312 <xref linkend='XIconifyWindow' xrefstyle='select: title'/>
313 function sends a <property>WM_CHANGE_STATE</property>
314 <symbol>ClientMessage</symbol>
315 event with a format of 32 and a first data element of
316 <symbol>IconicState</symbol>
317 (as described in <olink targetdoc='icccm' targetptr='Changing_Window_State'
318 >section 4.1.4 of the
319 <citetitle>Inter-Client Communication Conventions Manual</citetitle></olink>)
321 to the root window of the specified screen
322 with an event mask set to
323 <symbol>SubstructureNotifyMask</symbol> |
324 <symbol>SubstructureRedirectMask</symbol>.
325 Window managers may elect to receive this message and
326 if the window is in its normal state,
327 may treat it as a request to change the window's state from normal to iconic.
328 If the <property>WM_CHANGE_STATE</property> property cannot be interned,
329 <xref linkend='XIconifyWindow' xrefstyle='select: title'/>
330 does not send a message and returns a zero status.
331 It returns a nonzero status if the client message is sent successfully;
332 otherwise, it returns a zero status.
337 To request that a top-level window be withdrawn, use
338 <xref linkend='XWithdrawWindow' xrefstyle='select: title'/>.
340 <indexterm significance="preferred"><primary>XWithdrawWindow</primary></indexterm>
342 <funcsynopsis id='XWithdrawWindow'>
344 <funcdef>Status <function>XWithdrawWindow</function></funcdef>
345 <paramdef>Display<parameter> *display</parameter></paramdef>
346 <paramdef>Window<parameter> w</parameter></paramdef>
347 <paramdef>int<parameter> screen_number</parameter></paramdef>
354 <emphasis remap='I'>display</emphasis>
358 Specifies the connection to the X server.
364 <emphasis remap='I'>w</emphasis>
368 Specifies the window.
374 <emphasis remap='I'>screen_number</emphasis>
378 Specifies the appropriate screen number on the host server.
387 <xref linkend='XWithdrawWindow' xrefstyle='select: title'/>
388 function unmaps the specified window
389 and sends a synthetic
390 <symbol>UnmapNotify</symbol>
391 event to the root window of the specified screen.
392 Window managers may elect to receive this message
393 and may treat it as a request to change the window's state to withdrawn.
394 When a window is in the withdrawn state,
395 neither its normal nor its iconic representations is visible.
396 It returns a nonzero status if the
397 <symbol>UnmapNotify</symbol>
398 event is successfully sent;
399 otherwise, it returns a zero status.
403 <xref linkend='XWithdrawWindow' xrefstyle='select: title'/>
405 <errorname>BadWindow</errorname>
411 To request that a top-level window be reconfigured, use
412 <xref linkend='XReconfigureWMWindow' xrefstyle='select: title'/>.
414 <indexterm significance="preferred"><primary>XReconfigureWMWindow</primary></indexterm>
416 <funcsynopsis id='XReconfigureWMWindow'>
418 <funcdef>Status <function>XReconfigureWMWindow</function></funcdef>
419 <paramdef>Display<parameter> *display</parameter></paramdef>
420 <paramdef>Window<parameter> w</parameter></paramdef>
421 <paramdef>int<parameter> screen_number</parameter></paramdef>
422 <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>
423 <paramdef>XWindowChanges<parameter> *values</parameter></paramdef>
430 <emphasis remap='I'>display</emphasis>
434 Specifies the connection to the X server.
440 <emphasis remap='I'>w</emphasis>
444 Specifies the window.
450 <emphasis remap='I'>screen_number</emphasis>
454 Specifies the appropriate screen number on the host server.
460 <emphasis remap='I'>value_mask</emphasis>
464 Specifies which values are to be set using information in
465 the values structure.
466 This mask is the bitwise inclusive OR of the valid configure window values bits.
472 <emphasis remap='I'>values</emphasis>
477 <structname>XWindowChanges</structname>
487 <xref linkend='XReconfigureWMWindow' xrefstyle='select: title'/>
489 <systemitem>ConfigureWindow</systemitem>
490 request on the specified top-level window.
491 If the stacking mode is changed and the request fails with a
492 <errorname>BadMatch</errorname>
494 the error is trapped by Xlib and a synthetic
495 <systemitem class="event">ConfigureRequestEvent</systemitem>
496 containing the same configuration parameters is sent to the root
497 of the specified window.
498 Window managers may elect to receive this event
499 and treat it as a request to reconfigure the indicated window.
500 It returns a nonzero status if the request or event is successfully sent;
501 otherwise, it returns a zero status.
505 <xref linkend='XReconfigureWMWindow' xrefstyle='select: title'/>
507 <errorname>BadValue</errorname>
509 <errorname>BadWindow</errorname>
513 <sect2 id="Converting_String_Lists">
514 <title>Converting String Lists</title>
516 <!-- (SN Converting String Lists -->
520 Many of the text properties allow a variety of types and formats.
521 Because the data stored in these properties are not
522 simple null-terminated strings, an
523 <structname>XTextProperty</structname>
524 structure is used to describe the encoding, type, and length of the text
525 as well as its value.
527 <structname>XTextProperty</structname>
529 <indexterm significance="preferred"><primary>XTextProperty</primary></indexterm>
531 <literallayout class="monospaced">
532 <!-- .TA .5i 2.5i -->
533 <!-- .ta .5i 2.5i -->
535 unsigned char *value; /* property data */
536 Atom encoding; /* type of property */
537 int format; /* 8, 16, or 32 */
538 unsigned long nitems; /* number of items in value */
545 Xlib provides functions to convert localized text to or from encodings
546 that support the inter-client communication conventions for text.
547 In addition, functions are provided for converting between lists of pointers
548 to character strings and text properties in the STRING encoding.
552 The functions for localized text return a signed integer error status
554 <symbol>Success</symbol>
555 as zero, specific error conditions as negative numbers, and partial conversion
556 as a count of unconvertible characters.
559 <literallayout class="monospaced">
561 #define #XNoMemory -1
562 #define #XLocaleNotSupported -2
563 #define #XConverterNotFound -3
566 XStringStyle, /* STRING */
567 XCompoundTextStyle, /* COMPOUND_TEXT */
568 XTextStyle, /* text in owner's encoding (current locale) */
569 XStdICCTextStyle /* STRING, else COMPOUND_TEXT */
580 To convert a list of text strings to an
581 <structname>XTextProperty</structname>
583 <xref linkend='XmbTextListToTextProperty' xrefstyle='select: title'/>
585 <xref linkend='XwcTextListToTextProperty' xrefstyle='select: title'/>.
587 <indexterm significance="preferred"><primary>XmbTextListToTextProperty</primary></indexterm>
588 <indexterm significance="preferred"><primary>XwcTextListToTextProperty</primary></indexterm>
590 <funcsynopsis id='XmbTextListToTextProperty'>
592 <funcdef>int <function>XmbTextListToTextProperty</function></funcdef>
593 <paramdef>Display<parameter> *display</parameter></paramdef>
594 <paramdef>char<parameter> **list</parameter></paramdef>
595 <paramdef>int<parameter> count</parameter></paramdef>
596 <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>
597 <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
601 <funcsynopsis id='XwcTextListToTextProperty'>
603 <funcdef>int <function>XwcTextListToTextProperty</function></funcdef>
604 <paramdef>Display<parameter> *display</parameter></paramdef>
605 <paramdef>wchar_t<parameter> **list</parameter></paramdef>
606 <paramdef>int<parameter> count</parameter></paramdef>
607 <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>
608 <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
615 <emphasis remap='I'>display</emphasis>
619 Specifies the connection to the X server.
625 <emphasis remap='I'>list</emphasis>
629 Specifies a list of null-terminated character strings.
635 <emphasis remap='I'>count</emphasis>
639 Specifies the number of strings specified.
645 <emphasis remap='I'>style</emphasis>
649 Specifies the manner in which the property is encoded.
655 <emphasis remap='I'>text_prop_return</emphasis>
660 <structname>XTextProperty</structname>
670 <xref linkend='XmbTextListToTextProperty' xrefstyle='select: title'/>
672 <xref linkend='XwcTextListToTextProperty' xrefstyle='select: title'/>
673 functions set the specified
674 <structname>XTextProperty</structname>
675 value to a set of null-separated elements representing the concatenation
676 of the specified list of null-terminated text strings.
677 A final terminating null is stored at the end of the value field
678 of text_prop_return but is not included in the nitems member.
682 The functions set the encoding field of text_prop_return to an
684 for the specified display
685 naming the encoding determined by the specified style
686 and convert the specified text list to this encoding for storage in
687 the text_prop_return value field.
689 <constant>XStringStyle</constant>
691 <constant>XCompoundTextStyle</constant>
693 this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
695 <constant>XTextStyle</constant>
697 this encoding is the encoding of the current locale.
699 <constant>XStdICCTextStyle</constant>
701 this encoding is ``STRING'' if the text is fully convertible to STRING,
702 else ``COMPOUND_TEXT''.
706 If insufficient memory is available for the new value string,
708 <symbol>XNoMemory</symbol>.
709 If the current locale is not supported,
711 <symbol>XLocaleNotSupported</symbol>.
712 In both of these error cases,
713 the functions do not set text_prop_return.
717 To determine if the functions are guaranteed not to return
718 <symbol>XLocaleNotSupported</symbol>,
720 <function>XSupportsLocale</function>.
724 If the supplied text is not fully convertible to the specified encoding,
725 the functions return the number of unconvertible characters.
726 Each unconvertible character is converted to an implementation-defined and
727 encoding-specific default string.
728 Otherwise, the functions return
729 <symbol>Success</symbol>.
730 Note that full convertibility to all styles except
731 <constant>XStringStyle</constant>
736 To free the storage for the value field, use
737 <xref linkend='XFree' xrefstyle='select: title'/>.
742 To obtain a list of text strings from an
743 <structname>XTextProperty</structname>
745 <xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
747 <xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>.
749 <indexterm significance="preferred"><primary>XmbTextPropertyToTextList</primary></indexterm>
750 <indexterm significance="preferred"><primary>XwcTextPropertyToTextList</primary></indexterm>
752 <funcsynopsis id='XmbTextPropertyToTextList'>
754 <funcdef>int <function>XmbTextPropertyToTextList</function></funcdef>
755 <paramdef>Display<parameter> *display</parameter></paramdef>
756 <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
757 <paramdef>char<parameter> ***list_return</parameter></paramdef>
758 <paramdef>int<parameter> *count_return</parameter></paramdef>
762 <funcsynopsis id='XwcTextPropertyToTextList'>
764 <funcdef>int <function>XwcTextPropertyToTextList</function></funcdef>
765 <paramdef>Display<parameter> *display</parameter></paramdef>
766 <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
767 <paramdef>wchar_t<parameter> ***list_return</parameter></paramdef>
768 <paramdef>int<parameter> *count_return</parameter></paramdef>
775 <emphasis remap='I'>display</emphasis>
779 Specifies the connection to the X server.
785 <emphasis remap='I'>text_prop</emphasis>
790 <structname>XTextProperty</structname>
791 structure to be used.
797 <emphasis remap='I'>list_return</emphasis>
801 Returns a list of null-terminated character strings.
802 <!-- .ds Cn strings -->
808 <emphasis remap='I'>count_return</emphasis>
812 Returns the number of (Cn.
821 <xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
823 <xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>
824 functions return a list of text strings in the current locale representing the
825 null-separated elements of the specified
826 <structname>XTextProperty</structname>
828 The data in text_prop must be format 8.
832 Multiple elements of the property (for example, the strings in a disjoint
833 text selection) are separated by a null byte.
834 The contents of the property are not required to be null-terminated;
835 any terminating null should not be included in text_prop.nitems.
839 If insufficient memory is available for the list and its elements,
840 <xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
842 <xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>
844 <symbol>XNoMemory</symbol>.
845 If the current locale is not supported,
847 <symbol>XLocaleNotSupported</symbol>.
848 Otherwise, if the encoding field of text_prop is not convertible
849 to the encoding of the current locale,
851 <symbol>XConverterNotFound</symbol>.
852 For supported locales,
853 existence of a converter from COMPOUND_TEXT, STRING
854 or the encoding of the current locale is guaranteed if
855 <function>XSupportsLocale</function>
857 <symbol>True</symbol>
858 for the current locale (but the actual text
859 may contain unconvertible characters).
860 Conversion of other encodings is implementation-dependent.
861 In all of these error cases,
862 the functions do not set any return values.
867 <xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
869 <xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>
870 return the list of null-terminated text strings to list_return
871 and the number of text strings to count_return.
875 If the value field of text_prop is not fully convertible to the encoding of
877 the functions return the number of unconvertible characters.
878 Each unconvertible character is converted to a string in the
879 current locale that is specific to the current locale.
880 To obtain the value of this string,
882 <function>XDefaultString</function>.
884 <xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
886 <xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>
888 <symbol>Success</symbol>.
892 To free the storage for the list and its contents returned by
893 <xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>,
895 <xref linkend='XFreeStringList' xrefstyle='select: title'/>.
896 To free the storage for the list and its contents returned by
897 <xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>,
899 <xref linkend='XwcFreeStringList' xrefstyle='select: title'/>.
904 To free the in-memory data associated with the specified
905 wide character string list, use
906 <xref linkend='XwcFreeStringList' xrefstyle='select: title'/>.
908 <indexterm significance="preferred"><primary>XwcFreeStringList</primary></indexterm>
910 <funcsynopsis id='XwcFreeStringList'>
912 <funcdef>void <function>XwcFreeStringList</function></funcdef>
913 <paramdef>wchar_t<parameter> **list</parameter></paramdef>
920 <emphasis remap='I'>list</emphasis>
924 Specifies the list of strings to be freed.
933 <xref linkend='XwcFreeStringList' xrefstyle='select: title'/>
934 function frees memory allocated by
935 <xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>.
940 To obtain the default string for text conversion in the current locale,
943 <para>char *XDefaultString()</para>
949 <function>XDefaultString</function>
950 function returns the default string used by Xlib for text conversion
952 <xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>).
953 The default string is the string in the current locale that is output
954 when an unconvertible character is found during text conversion.
955 If the string returned by
956 <function>XDefaultString</function>
957 is the empty string (""),
958 no character is output in the converted text.
959 <function>XDefaultString</function>
960 does not return NULL.
964 The string returned by
965 <function>XDefaultString</function>
966 is independent of the default string for text drawing;
968 <xref linkend='XCreateFontSet' xrefstyle='select: title'/>
969 to obtain the default string for an
970 <type>XFontSet</type>.
974 The behavior when an invalid codepoint is supplied to any Xlib function is
979 The returned string is null-terminated.
980 It is owned by Xlib and should not be modified or freed by the client.
981 It may be freed after the current locale is changed.
982 Until freed, it will not be modified by Xlib.
987 To set the specified list of strings in the STRING encoding to a
988 <structname>XTextProperty</structname>
990 <xref linkend='XStringListToTextProperty' xrefstyle='select: title'/>.
992 <indexterm significance="preferred"><primary>XStringListToTextProperty</primary></indexterm>
994 <funcsynopsis id='XStringListToTextProperty'>
996 <funcdef>Status <function>XStringListToTextProperty</function></funcdef>
997 <paramdef>char<parameter> **list</parameter></paramdef>
998 <paramdef>int<parameter> count</parameter></paramdef>
999 <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
1006 <emphasis remap='I'>list</emphasis>
1010 Specifies a list of null-terminated character strings.
1011 <!-- .ds Cn strings -->
1017 <emphasis remap='I'>count</emphasis>
1021 Specifies the number of (Cn.
1027 <emphasis remap='I'>text_prop_return</emphasis>
1032 <structname>XTextProperty</structname>
1042 <xref linkend='XStringListToTextProperty' xrefstyle='select: title'/>
1043 function sets the specified
1044 <structname>XTextProperty</structname>
1045 to be of type STRING (format 8) with a value representing the
1046 concatenation of the specified list of null-separated character strings.
1047 An extra null byte (which is not included in the nitems member)
1048 is stored at the end of the value field of text_prop_return.
1049 The strings are assumed (without verification) to be in the STRING encoding.
1050 If insufficient memory is available for the new value string,
1051 <xref linkend='XStringListToTextProperty' xrefstyle='select: title'/>
1052 does not set any fields in the
1053 <structname>XTextProperty</structname>
1054 structure and returns a zero status.
1055 Otherwise, it returns a nonzero status.
1056 To free the storage for the value field, use
1057 <xref linkend='XFree' xrefstyle='select: title'/>.
1062 To obtain a list of strings from a specified
1063 <structname>XTextProperty</structname>
1064 structure in the STRING encoding, use
1065 <xref linkend='XTextPropertyToStringList' xrefstyle='select: title'/>.
1067 <indexterm significance="preferred"><primary>XTextPropertyToStringList</primary></indexterm>
1069 <funcsynopsis id='XTextPropertyToStringList'>
1071 <funcdef>Status <function>XTextPropertyToStringList</function></funcdef>
1072 <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
1073 <paramdef>char<parameter> ***list_return</parameter></paramdef>
1074 <paramdef>int<parameter> *count_return</parameter></paramdef>
1081 <emphasis remap='I'>text_prop</emphasis>
1086 <structname>XTextProperty</structname>
1087 structure to be used.
1093 <emphasis remap='I'>list_return</emphasis>
1097 Returns a list of null-terminated character strings.
1098 <!-- .ds Cn strings -->
1104 <emphasis remap='I'>count_return</emphasis>
1108 Returns the number of (Cn.
1117 <xref linkend='XTextPropertyToStringList' xrefstyle='select: title'/>
1118 function returns a list of strings representing the null-separated elements
1120 <structname>XTextProperty</structname>
1122 The data in text_prop must be of type STRING and format 8.
1123 Multiple elements of the property
1124 (for example, the strings in a disjoint text selection)
1125 are separated by NULL (encoding 0).
1126 The contents of the property are not null-terminated.
1127 If insufficient memory is available for the list and its elements,
1128 <xref linkend='XTextPropertyToStringList' xrefstyle='select: title'/>
1129 sets no return values and returns a zero status.
1130 Otherwise, it returns a nonzero status.
1131 To free the storage for the list and its contents, use
1132 <xref linkend='XFreeStringList' xrefstyle='select: title'/>.
1137 To free the in-memory data associated with the specified string list, use
1138 <xref linkend='XFreeStringList' xrefstyle='select: title'/>.
1140 <indexterm significance="preferred"><primary>XFreeStringList</primary></indexterm>
1142 <funcsynopsis id='XFreeStringList'>
1144 <funcdef>void <function>XFreeStringList</function></funcdef>
1145 <paramdef>char<parameter> **list</parameter></paramdef>
1152 <emphasis remap='I'>list</emphasis>
1156 Specifies the list of strings to be freed.
1165 <xref linkend='XFreeStringList' xrefstyle='select: title'/>
1166 function releases memory allocated by
1167 <xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
1169 <xref linkend='XTextPropertyToStringList' xrefstyle='select: title'/>
1170 and the missing charset list allocated by
1171 <xref linkend='XCreateFontSet' xrefstyle='select: title'/>.
1174 <sect2 id="Setting_and_Reading_Text_Properties">
1175 <title>Setting and Reading Text Properties</title>
1177 <!-- (SN Setting and Reading Text Properties -->
1181 Xlib provides two functions that you can use to set and read
1182 the text properties for a given window.
1183 You can use these functions to set and read those properties of type TEXT
1184 (<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property>).
1186 Xlib provides separate convenience functions that you can use to set each
1187 of these properties.
1188 For further information about these convenience functions,
1190 <link linkend="Setting_and_Reading_the_WM_NAME_Property">14.1.4</link>,
1191 <link linkend="Setting_and_Reading_the_WM_ICON_NAME_Property">14.1.5</link>,
1192 <link linkend="Setting_and_Reading_the_WM_COMMAND_Property">14.2.1</link>, and
1193 <link linkend="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">14.2.2</link>,
1199 To set one of a window's text properties, use
1200 <xref linkend='XSetTextProperty' xrefstyle='select: title'/>.
1202 <indexterm significance="preferred"><primary>XSetTextProperty</primary></indexterm>
1204 <funcsynopsis id='XSetTextProperty'>
1206 <funcdef>void <function>XSetTextProperty</function></funcdef>
1207 <paramdef>Display<parameter> *display</parameter></paramdef>
1208 <paramdef>Window<parameter> w</parameter></paramdef>
1209 <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
1210 <paramdef>Atom<parameter> property</parameter></paramdef>
1217 <emphasis remap='I'>display</emphasis>
1221 Specifies the connection to the X server.
1227 <emphasis remap='I'>w</emphasis>
1231 Specifies the window.
1237 <emphasis remap='I'>text_prop</emphasis>
1242 <structname>XTextProperty</structname>
1243 structure to be used.
1249 <emphasis remap='I'>property</emphasis>
1253 Specifies the property name.
1262 <xref linkend='XSetTextProperty' xrefstyle='select: title'/>
1263 function replaces the existing specified property for the named window
1264 with the data, type, format, and number of items determined
1265 by the value field, the encoding field, the format field,
1266 and the nitems field, respectively, of the specified
1267 <structname>XTextProperty</structname>
1269 If the property does not already exist,
1270 <xref linkend='XSetTextProperty' xrefstyle='select: title'/>
1271 sets it for the specified window.
1275 <xref linkend='XSetTextProperty' xrefstyle='select: title'/>
1277 <errorname>BadAlloc</errorname>,
1278 <errorname>BadAtom</errorname>,
1279 <errorname>BadValue</errorname>,
1281 <errorname>BadWindow</errorname>
1287 To read one of a window's text properties, use
1288 <xref linkend='XGetTextProperty' xrefstyle='select: title'/>.
1290 <indexterm significance="preferred"><primary>XGetTextProperty</primary></indexterm>
1292 <funcsynopsis id='XGetTextProperty'>
1294 <funcdef>Status <function>XGetTextProperty</function></funcdef>
1295 <paramdef>Display<parameter> *display</parameter></paramdef>
1296 <paramdef>Window<parameter> w</parameter></paramdef>
1297 <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
1298 <paramdef>Atom<parameter> property</parameter></paramdef>
1305 <emphasis remap='I'>display</emphasis>
1309 Specifies the connection to the X server.
1315 <emphasis remap='I'>w</emphasis>
1319 Specifies the window.
1325 <emphasis remap='I'>text_prop_return</emphasis>
1330 <structname>XTextProperty</structname>
1337 <emphasis remap='I'>property</emphasis>
1341 Specifies the property name.
1350 <xref linkend='XGetTextProperty' xrefstyle='select: title'/>
1351 function reads the specified property from the window
1352 and stores the data in the returned
1353 <structname>XTextProperty</structname>
1355 It stores the data in the value field,
1356 the type of the data in the encoding field,
1357 the format of the data in the format field,
1358 and the number of items of data in the nitems field.
1359 An extra byte containing null (which is not included in the nitems member)
1360 is stored at the end of the value field of text_prop_return.
1361 The particular interpretation of the property's encoding
1362 and data as text is left to the calling application.
1363 If the specified property does not exist on the window,
1364 <xref linkend='XGetTextProperty' xrefstyle='select: title'/>
1365 sets the value field to NULL,
1366 the encoding field to
1367 <symbol>None</symbol>,
1368 the format field to zero,
1369 and the nitems field to zero.
1373 If it was able to read and store the data in the
1374 <structname>XTextProperty</structname>
1376 <xref linkend='XGetTextProperty' xrefstyle='select: title'/>
1377 returns a nonzero status;
1378 otherwise, it returns a zero status.
1382 <xref linkend='XGetTextProperty' xrefstyle='select: title'/>
1384 <errorname>BadAtom</errorname>
1386 <errorname>BadWindow</errorname>
1390 <sect2 id="Setting_and_Reading_the_WM_NAME_Property">
1391 <title>Setting and Reading the WM_NAME Property</title>
1393 <!-- (SN Setting and Reading the WM_NAME Property -->
1397 Xlib provides convenience functions that you can use to set and read
1398 the <property>WM_NAME</property> property for a given window.
1403 To set a window's <property>WM_NAME</property> property with the supplied convenience function, use
1404 <xref linkend='XSetWMName' xrefstyle='select: title'/>.
1406 <indexterm significance="preferred"><primary>XSetWMName</primary></indexterm>
1408 <funcsynopsis id='XSetWMName'>
1410 <funcdef>void <function>XSetWMName</function></funcdef>
1411 <paramdef>Display<parameter> *display</parameter></paramdef>
1412 <paramdef>Window<parameter> w</parameter></paramdef>
1413 <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
1420 <emphasis remap='I'>display</emphasis>
1424 Specifies the connection to the X server.
1430 <emphasis remap='I'>w</emphasis>
1434 Specifies the window.
1440 <emphasis remap='I'>text_prop</emphasis>
1445 <structname>XTextProperty</structname>
1446 structure to be used.
1455 <xref linkend='XSetWMName' xrefstyle='select: title'/>
1456 convenience function calls
1457 <xref linkend='XSetTextProperty' xrefstyle='select: title'/>
1458 to set the <property>WM_NAME</property> property.
1463 To read a window's <property>WM_NAME</property> property with the supplied convenience function, use
1464 <xref linkend='XGetWMName' xrefstyle='select: title'/>.
1466 <indexterm significance="preferred"><primary>XGetWMName</primary></indexterm>
1468 <funcsynopsis id='XGetWMName'>
1470 <funcdef>Status <function>XGetWMName</function></funcdef>
1471 <paramdef>Display<parameter> *display</parameter></paramdef>
1472 <paramdef>Window<parameter> w</parameter></paramdef>
1473 <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
1480 <emphasis remap='I'>display</emphasis>
1484 Specifies the connection to the X server.
1490 <emphasis remap='I'>w</emphasis>
1494 Specifies the window.
1500 <emphasis remap='I'>text_prop_return</emphasis>
1505 <structname>XTextProperty</structname>
1515 <xref linkend='XGetWMName' xrefstyle='select: title'/>
1516 convenience function calls
1517 <xref linkend='XGetTextProperty' xrefstyle='select: title'/>
1518 to obtain the <property>WM_NAME</property> property.
1519 It returns a nonzero status on success;
1520 otherwise, it returns a zero status.
1524 The following two functions have been superseded by
1525 <xref linkend='XSetWMName' xrefstyle='select: title'/>
1527 <xref linkend='XGetWMName' xrefstyle='select: title'/>,
1529 You can use these additional convenience functions
1530 for window names that are encoded as STRING properties.
1535 To assign a name to a window, use
1536 <xref linkend='XStoreName' xrefstyle='select: title'/>.
1538 <indexterm><primary>Window</primary><secondary>name</secondary></indexterm>
1539 <indexterm significance="preferred"><primary>XStoreName</primary></indexterm>
1541 <funcsynopsis id='XStoreName'>
1543 <funcdef><function>XStoreName</function></funcdef>
1544 <paramdef>Display<parameter> *display</parameter></paramdef>
1545 <paramdef>Window<parameter> w</parameter></paramdef>
1546 <paramdef>char<parameter> *window_name</parameter></paramdef>
1553 <emphasis remap='I'>display</emphasis>
1557 Specifies the connection to the X server.
1563 <emphasis remap='I'>w</emphasis>
1567 Specifies the window.
1573 <emphasis remap='I'>window_name</emphasis>
1577 Specifies the window name,
1578 which should be a null-terminated string.
1587 <xref linkend='XStoreName' xrefstyle='select: title'/>
1588 function assigns the name passed to window_name to the specified window.
1589 A window manager can display the window name in some prominent
1590 place, such as the title bar, to allow users to identify windows easily.
1591 Some window managers may display a window's name in the window's icon,
1592 although they are encouraged to use the window's icon name
1593 if one is provided by the application.
1594 If the string is not in the Host Portable Character Encoding,
1595 the result is implementation-dependent.
1599 <xref linkend='XStoreName' xrefstyle='select: title'/>
1601 <errorname>BadAlloc</errorname>
1603 <errorname>BadWindow</errorname>
1609 To get the name of a window, use
1610 <xref linkend='XFetchName' xrefstyle='select: title'/>.
1612 <indexterm significance="preferred"><primary>XFetchName</primary></indexterm>
1614 <funcsynopsis id='XFetchName'>
1616 <funcdef>Status <function>XFetchName</function></funcdef>
1617 <paramdef>Display<parameter> *display</parameter></paramdef>
1618 <paramdef>Window<parameter> w</parameter></paramdef>
1619 <paramdef>char<parameter> **window_name_return</parameter></paramdef>
1626 <emphasis remap='I'>display</emphasis>
1630 Specifies the connection to the X server.
1636 <emphasis remap='I'>w</emphasis>
1640 Specifies the window.
1646 <emphasis remap='I'>window_name_return</emphasis>
1650 Returns the window name, which is a null-terminated string.
1659 <xref linkend='XFetchName' xrefstyle='select: title'/>
1660 function returns the name of the specified window.
1662 it returns a nonzero status;
1663 otherwise, no name has been set for the window,
1664 and it returns zero.
1665 If the <property>WM_NAME</property> property has not been set for this window,
1666 <xref linkend='XFetchName' xrefstyle='select: title'/>
1667 sets window_name_return to NULL.
1668 If the data returned by the server is in the Latin Portable Character Encoding,
1669 then the returned string is in the Host Portable Character Encoding.
1670 Otherwise, the result is implementation-dependent.
1671 When finished with it, a client must free
1672 the window name string using
1673 <xref linkend='XFree' xrefstyle='select: title'/>.
1677 <xref linkend='XFetchName' xrefstyle='select: title'/>
1679 <errorname>BadWindow</errorname>
1683 <sect2 id="Setting_and_Reading_the_WM_ICON_NAME_Property">
1684 <title>Setting and Reading the WM_ICON_NAME Property</title>
1686 <!-- (SN Setting and Reading the WM_ICON_NAME Property -->
1690 Xlib provides convenience functions that you can use to set and read
1691 the <property>WM_ICON_NAME</property> property for a given window.
1696 To set a window's <property>WM_ICON_NAME</property> property,
1698 <xref linkend='XSetWMIconName' xrefstyle='select: title'/>.
1700 <indexterm significance="preferred"><primary>XSetWMIconName</primary></indexterm>
1702 <funcsynopsis id='XSetWMIconName'>
1704 <funcdef>void <function>XSetWMIconName</function></funcdef>
1705 <paramdef>Display<parameter> *display</parameter></paramdef>
1706 <paramdef>Window<parameter> w</parameter></paramdef>
1707 <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
1714 <emphasis remap='I'>display</emphasis>
1718 Specifies the connection to the X server.
1724 <emphasis remap='I'>w</emphasis>
1728 Specifies the window.
1734 <emphasis remap='I'>text_prop</emphasis>
1739 <structname>XTextProperty</structname>
1740 structure to be used.
1749 <xref linkend='XSetWMIconName' xrefstyle='select: title'/>
1750 convenience function calls
1751 <xref linkend='XSetTextProperty' xrefstyle='select: title'/>
1752 to set the <property>WM_ICON_NAME</property> property.
1757 To read a window's <property>WM_ICON_NAME</property> property,
1759 <xref linkend='XGetWMIconName' xrefstyle='select: title'/>.
1761 <indexterm significance="preferred"><primary>XGetWMIconName</primary></indexterm>
1763 <funcsynopsis id='XGetWMIconName'>
1765 <funcdef>Status <function>XGetWMIconName</function></funcdef>
1766 <paramdef>Display<parameter> *display</parameter></paramdef>
1767 <paramdef>Window<parameter> w</parameter></paramdef>
1768 <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
1775 <emphasis remap='I'>display</emphasis>
1779 Specifies the connection to the X server.
1785 <emphasis remap='I'>w</emphasis>
1789 Specifies the window.
1795 <emphasis remap='I'>text_prop_return</emphasis>
1800 <structname>XTextProperty</structname>
1810 <xref linkend='XGetWMIconName' xrefstyle='select: title'/>
1811 convenience function calls
1812 <xref linkend='XGetTextProperty' xrefstyle='select: title'/>
1813 to obtain the <property>WM_ICON_NAME</property> property.
1814 It returns a nonzero status on success;
1815 otherwise, it returns a zero status.
1819 The next two functions have been superseded by
1820 <xref linkend='XSetWMIconName' xrefstyle='select: title'/>
1822 <xref linkend='XGetWMIconName' xrefstyle='select: title'/>,
1824 You can use these additional convenience functions
1825 for window names that are encoded as STRING properties.
1831 To set the name to be displayed in a window's icon, use
1832 <xref linkend='XSetIconName' xrefstyle='select: title'/>.
1834 <indexterm><primary>Window</primary><secondary>icon name</secondary></indexterm>
1835 <indexterm significance="preferred"><primary>XSetIconName</primary></indexterm>
1837 <funcsynopsis id='XSetIconName'>
1839 <funcdef><function>XSetIconName</function></funcdef>
1840 <paramdef>Display<parameter> *display</parameter></paramdef>
1841 <paramdef>Window<parameter> w</parameter></paramdef>
1842 <paramdef>char<parameter> *icon_name</parameter></paramdef>
1849 <emphasis remap='I'>display</emphasis>
1853 Specifies the connection to the X server.
1859 <emphasis remap='I'>w</emphasis>
1863 Specifies the window.
1869 <emphasis remap='I'>icon_name</emphasis>
1873 Specifies the icon name,
1874 which should be a null-terminated string.
1882 If the string is not in the Host Portable Character Encoding,
1883 the result is implementation-dependent.
1884 <xref linkend='XSetIconName' xrefstyle='select: title'/>
1886 <errorname>BadAlloc</errorname>
1888 <errorname>BadWindow</errorname>
1894 To get the name a window wants displayed in its icon, use
1895 <xref linkend='XGetIconName' xrefstyle='select: title'/>.
1897 <indexterm significance="preferred"><primary>XGetIconName</primary></indexterm>
1899 <funcsynopsis id='XGetIconName'>
1901 <funcdef>Status <function>XGetIconName</function></funcdef>
1902 <paramdef>Display<parameter> *display</parameter></paramdef>
1903 <paramdef>Window<parameter> w</parameter></paramdef>
1904 <paramdef>char<parameter> **icon_name_return</parameter></paramdef>
1911 <emphasis remap='I'>display</emphasis>
1915 Specifies the connection to the X server.
1921 <emphasis remap='I'>w</emphasis>
1925 Specifies the window.
1931 <emphasis remap='I'>icon_name_return</emphasis>
1935 Returns the window's icon name,
1936 which is a null-terminated string.
1945 <xref linkend='XGetIconName' xrefstyle='select: title'/>
1946 function returns the name to be displayed in the specified window's icon.
1947 If it succeeds, it returns a nonzero status; otherwise,
1948 if no icon name has been set for the window,
1950 If you never assigned a name to the window,
1951 <xref linkend='XGetIconName' xrefstyle='select: title'/>
1952 sets icon_name_return to NULL.
1953 If the data returned by the server is in the Latin Portable Character Encoding,
1954 then the returned string is in the Host Portable Character Encoding.
1955 Otherwise, the result is implementation-dependent.
1956 When finished with it, a client must free
1957 the icon name string using
1958 <xref linkend='XFree' xrefstyle='select: title'/>.
1962 <xref linkend='XGetIconName' xrefstyle='select: title'/>
1964 <errorname>BadWindow</errorname>
1968 <sect2 id="Setting_and_Reading_the_WM_HINTS_Property">
1969 <title>Setting and Reading the WM_HINTS Property</title>
1971 <!-- (SN Setting and Reading the WM_HINTS Property -->
1975 Xlib provides functions that you can use to set and read
1976 the <property>WM_HINTS</property> property for a given window.
1977 These functions use the flags and the
1978 <structname>XWMHints</structname>
1979 structure, as defined in the
1980 <filename class="headerfile"><X11/Xutil.h></filename>
1981 <indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
1982 <indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
1983 <indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
1990 <structname>XWMHints</structname>
1992 <function>XAllocWMHints</function>.
1996 XWMHints *XAllocWMHints()
2003 <function>XAllocWMHints</function>
2004 function allocates and returns a pointer to an
2005 <structname>XWMHints</structname>
2007 Note that all fields in the
2008 <structname>XWMHints</structname>
2009 structure are initially set to zero.
2010 If insufficient memory is available,
2011 <function>XAllocWMHints</function>
2013 To free the memory allocated to this structure,
2015 <xref linkend='XFree' xrefstyle='select: title'/>.
2020 <structname>XWMHints</structname>
2024 <literallayout class="monospaced">
2025 /* Window manager hints mask bits */
2027 #define InputHint (1L<<0)
2028 #define StateHint (1L<<1)
2029 #define IconPixmapHint (1L<<2)
2030 #define IconWindowHint (1L<<3)
2031 #define IconPositionHint (1L<<4)
2032 #define IconMaskHint (1L<<5)
2033 #define WindowGroupHint (1L<<6)
2034 #define UrgencyHint (1L<<8)
2035 #define AllHints (InputHint|StateHint|IconPixmapHint|
2036 IconWIndowHint|IconPositionHint|
2037 IconMaskHint|WindowGroupHint)
2043 long flags; /* marks which fields in this structure are defined */
2044 Bool input; /* does this application rely on the window manager to
2045 get keyboard input? */
2046 int initial_state; /* see below */
2047 Pixmap icon_pixmap; /* pixmap to be used as icon */
2048 Window icon_window; /* window to be used as icon */
2049 int icon_x, icon_y; /* initial position of icon */
2050 Pixmap icon_mask; /* pixmap to be used as mask for icon_pixmap */
2051 XID window_group; /* id of related window group */
2052 /* this structure may be extended in the future */
2058 The input member is used to communicate to the window manager the input focus
2059 model used by the application.
2060 Applications that expect input but never explicitly set focus to any
2061 of their subwindows (that is, use the push model of focus management),
2062 such as X Version 10 style applications that use real-estate
2063 driven focus, should set this member to
2064 <symbol>True</symbol>.
2065 Similarly, applications
2066 that set input focus to their subwindows only when it is given to their
2067 top-level window by a window manager should also set this member to
2068 <symbol>True</symbol>.
2069 Applications that manage their own input focus by explicitly setting
2070 focus to one of their subwindows whenever they want keyboard input
2071 (that is, use the pull model of focus management) should set this member to
2072 <symbol>False</symbol>.
2073 Applications that never expect any keyboard input also should set this member
2075 <symbol>False</symbol>.
2079 Pull model window managers should make it possible for push model
2080 applications to get input by setting input focus to the top-level windows of
2081 applications whose input member is
2082 <symbol>True</symbol>.
2083 Push model window managers should
2084 make sure that pull model applications do not break them
2085 by resetting input focus to
2086 <symbol>PointerRoot</symbol>
2087 when it is appropriate (for example, whenever an application whose
2089 <symbol>False</symbol>
2090 sets input focus to one of its subwindows).
2094 The definitions for the initial_state flag are:
2097 <literallayout class="monospaced">
2098 #define WithdrawnState 0
2099 #define NormalState 1 /* most applications start this way */
2100 #define IconicState 2 /* application wants to start as an icon */
2104 The icon_mask specifies which pixels of the icon_pixmap should be used as the
2106 This allows for nonrectangular icons.
2107 Both icon_pixmap and icon_mask must be bitmaps.
2108 The icon_window lets an application provide a window for use as an icon
2109 for window managers that support such use.
2110 The window_group lets you specify that this window belongs to a group
2112 For example, if a single application manipulates multiple
2113 top-level windows, this allows you to provide enough
2114 information that a window manager can iconify all of the windows
2115 rather than just the one window.
2120 <symbol>UrgencyHint</symbol>
2121 flag, if set in the flags field, indicates that the client deems the window
2122 contents to be urgent, requiring the timely response of the user. The
2123 window manager will make some effort to draw the user's attention to this
2124 window while this flag is set. The client must provide some means by which the
2125 user can cause the urgency flag to be cleared (either mitigating
2126 the condition that made the window urgent or merely shutting off the alarm)
2127 or the window to be withdrawn.
2132 To set a window's <property>WM_HINTS</property> property, use
2133 <xref linkend='XSetWMHints' xrefstyle='select: title'/>.
2135 <indexterm significance="preferred"><primary>XSetWMHints</primary></indexterm>
2137 <funcsynopsis id='XSetWMHints'>
2139 <funcdef><function>XSetWMHints</function></funcdef>
2140 <paramdef>Display<parameter> *display</parameter></paramdef>
2141 <paramdef>Window<parameter> w</parameter></paramdef>
2142 <paramdef>XWMHints<parameter> *wmhints</parameter></paramdef>
2149 <emphasis remap='I'>display</emphasis>
2153 Specifies the connection to the X server.
2159 <emphasis remap='I'>w</emphasis>
2163 Specifies the window.
2169 <emphasis remap='I'>wmhints</emphasis>
2174 <structname>XWMHints</structname>
2175 structure to be used.
2184 <xref linkend='XSetWMHints' xrefstyle='select: title'/>
2185 function sets the window manager hints that include icon information and location,
2186 the initial state of the window, and whether the application relies on the
2187 window manager to get keyboard input.
2191 <xref linkend='XSetWMHints' xrefstyle='select: title'/>
2193 <errorname>BadAlloc</errorname>
2195 <errorname>BadWindow</errorname>
2201 To read a window's <property>WM_HINTS</property> property, use
2202 <xref linkend='XGetWMHints' xrefstyle='select: title'/>.
2204 <indexterm significance="preferred"><primary>XGetWMHints</primary></indexterm>
2206 <funcsynopsis id='XGetWMHints'>
2208 <funcdef>XWMHints *<function>XGetWMHints</function></funcdef>
2209 <paramdef>Display<parameter> *display</parameter></paramdef>
2210 <paramdef>Window<parameter> w</parameter></paramdef>
2217 <emphasis remap='I'>display</emphasis>
2221 Specifies the connection to the X server.
2227 <emphasis remap='I'>w</emphasis>
2231 Specifies the window.
2240 <xref linkend='XGetWMHints' xrefstyle='select: title'/>
2241 function reads the window manager hints and
2242 returns NULL if no <property>WM_HINTS</property> property was set on the window
2243 or returns a pointer to an
2244 <structname>XWMHints</structname>
2245 structure if it succeeds.
2246 When finished with the data,
2247 free the space used for it by calling
2248 <xref linkend='XFree' xrefstyle='select: title'/>.
2252 <xref linkend='XGetWMHints' xrefstyle='select: title'/>
2254 <errorname>BadWindow</errorname>
2258 <sect2 id="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">
2259 <title>Setting and Reading the WM_NORMAL_HINTS Property</title>
2261 <!-- (SN Setting and Reading the WM_NORMAL_HINTS Property -->
2265 Xlib provides functions that you can use to set or read
2266 the <property>WM_NORMAL_HINTS</property> property for a given window.
2267 The functions use the flags and the
2268 <structname>XSizeHints</structname>
2269 structure, as defined in the
2270 <filename class="headerfile"><X11/Xutil.h></filename>
2271 <indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
2272 <indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
2273 <indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
2279 <structname>XSizeHints</structname>
2280 structure may grow in future releases, as new components are
2281 added to support new <acronym>ICCCM</acronym> features.
2282 Passing statically allocated instances of this structure into
2283 Xlib may result in memory corruption when running against a
2284 future release of the library.
2285 As such, it is recommended that only dynamically allocated
2286 instances of the structure be used.
2292 <structname>XSizeHints</structname>
2294 <function>XAllocSizeHints</function>.
2298 XSizeHints *XAllocSizeHints()
2304 <function>XAllocSizeHints</function>
2305 function allocates and returns a pointer to an
2306 <structname>XSizeHints</structname>
2308 Note that all fields in the
2309 <structname>XSizeHints</structname>
2310 structure are initially set to zero.
2311 If insufficient memory is available,
2312 <function>XAllocSizeHints</function>
2314 To free the memory allocated to this structure,
2316 <xref linkend='XFree' xrefstyle='select: title'/>.
2321 <structname>XSizeHints</structname>
2326 <literallayout class="monospaced">
2327 /* Size hints mask bits */
2329 #define USPosition (1L<<0) /* user specified x,y */
2330 #define USSize (1L<<1) /* user specified width,height */
2331 #define PPosition (1L<<2) /* program specified posistion */
2332 #define PSize (1L<<3) /* program specified size */
2333 #define PMinSize (1L<<4) /* program specified minimum size */
2334 #define PMaxSize (1L<<5) /* program specified maximum size */
2335 #define PResizeInc (1L<<5) /* program specified resize increments */
2336 #define PAspect (1L<<6) /* program specified min and max aspect ratios */
2337 #define PBaseSize (1L<<8)
2338 #define PWinGravity (1L<<9)
2339 #define PAllHints (PPosition|Psize|
2347 long flags; /* marks which fields in this structure are defined */
2348 int x, y; /* Obsolete */
2349 int width, height; /* Obsolete */
2350 int min_width, min_height;
2351 int max_width, max_height;
2352 int width_inc, height_inc;
2354 int x; /* numerator */
2355 int y; /* denominator */
2356 } min_aspect, max_aspect;
2357 int base_width, base_height;
2359 /* this structure may be extended in the future */
2366 The x, y, width, and height members are now obsolete
2367 and are left solely for compatibility reasons.
2368 The min_width and min_height members specify the
2369 minimum window size that still allows the application to be useful.
2370 The max_width and max_height members specify the maximum window size.
2371 The width_inc and height_inc members define an arithmetic progression of
2372 sizes (minimum to maximum) into which the window prefers to be resized.
2373 The min_aspect and max_aspect members are expressed
2374 as ratios of x and y,
2375 and they allow an application to specify the range of aspect
2377 The base_width and base_height members define the desired size of the window.
2378 The window manager will interpret the position of the window
2379 and its border width to position the point of the outer rectangle
2380 of the overall window specified by the win_gravity member.
2381 The outer rectangle of the window includes any borders or decorations
2382 supplied by the window manager.
2384 if the window manager decides to place the window where the client asked,
2385 the position on the parent window's border named by the win_gravity
2386 will be placed where the client window would have been placed
2387 in the absence of a window manager.
2391 Note that use of the
2392 <symbol>PAllHints</symbol>
2393 macro is highly discouraged.
2398 To set a window's <property>WM_NORMAL_HINTS</property> property, use
2399 <xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>.
2401 <indexterm significance="preferred"><primary>XSetWMNormalHints</primary></indexterm>
2403 <funcsynopsis id='XSetWMNormalHints'>
2405 <funcdef>void <function>XSetWMNormalHints</function></funcdef>
2406 <paramdef>Display<parameter> *display</parameter></paramdef>
2407 <paramdef>Window<parameter> w</parameter></paramdef>
2408 <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
2415 <emphasis remap='I'>display</emphasis>
2419 Specifies the connection to the X server.
2425 <emphasis remap='I'>w</emphasis>
2429 Specifies the window.
2435 <emphasis remap='I'>hints</emphasis>
2439 Specifies the size hints for the window in its normal state.
2448 <xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>
2449 function replaces the size hints for the <property>WM_NORMAL_HINTS</property> property
2450 on the specified window.
2451 If the property does not already exist,
2452 <xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>
2453 sets the size hints for the <property>WM_NORMAL_HINTS</property> property on the specified window.
2454 The property is stored with a type of <property>WM_SIZE_HINTS</property> and a format of 32.
2458 <xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>
2460 <errorname>BadAlloc</errorname>
2462 <errorname>BadWindow</errorname>
2468 To read a window's <property>WM_NORMAL_HINTS</property> property, use
2469 <xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>.
2471 <indexterm significance="preferred"><primary>XGetWMNormalHints</primary></indexterm>
2473 <funcsynopsis id='XGetWMNormalHints'>
2475 <funcdef>Status <function>XGetWMNormalHints</function></funcdef>
2476 <paramdef>Display<parameter> *display</parameter></paramdef>
2477 <paramdef>Window<parameter> w</parameter></paramdef>
2478 <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
2479 <paramdef>long<parameter> *supplied_return</parameter></paramdef>
2486 <emphasis remap='I'>display</emphasis>
2490 Specifies the connection to the X server.
2496 <emphasis remap='I'>w</emphasis>
2500 Specifies the window.
2506 <emphasis remap='I'>hints_return</emphasis>
2510 Returns the size hints for the window in its normal state.
2516 <emphasis remap='I'>supplied_return</emphasis>
2520 Returns the hints that were supplied by the user.
2529 <xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
2530 function returns the size hints stored in the <property>WM_NORMAL_HINTS</property> property
2531 on the specified window.
2532 If the property is of type <property>WM_SIZE_HINTS</property>, is of format 32,
2533 and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>)
2534 or new size hints structure,
2535 <xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
2536 sets the various fields of the
2537 <structname>XSizeHints</structname>
2538 structure, sets the supplied_return argument to the list of fields
2539 that were supplied by the user (whether or not they contained defined values),
2540 and returns a nonzero status.
2541 Otherwise, it returns a zero status.
2546 <xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
2547 returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read,
2548 the supplied_return argument will contain the following bits:
2552 <literallayout class="monospaced">
2553 (USPosition|USSize|PPosition|PSize|PMinSize|
2554 PMaxSize|PResizeInc|PAspect)
2559 If the property is large enough to contain the base size
2560 and window gravity fields as well,
2561 the supplied_return argument will also contain the following bits:
2565 <literallayout class="monospaced">
2566 PBaseSize|PWinGravity
2571 <xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
2573 <errorname>BadWindow</errorname>
2579 To set a window's <property>WM_SIZE_HINTS</property> property, use
2580 <xref linkend='XSetWMSizeHints' xrefstyle='select: title'/>.
2582 <indexterm significance="preferred"><primary>XSetWMSizeHints</primary></indexterm>
2584 <funcsynopsis id='XSetWMSizeHints'>
2586 <funcdef>void <function>XSetWMSizeHints</function></funcdef>
2587 <paramdef>Display<parameter> *display</parameter></paramdef>
2588 <paramdef>Window<parameter> w</parameter></paramdef>
2589 <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
2590 <paramdef>Atom<parameter> property</parameter></paramdef>
2597 <emphasis remap='I'>display</emphasis>
2601 Specifies the connection to the X server.
2607 <emphasis remap='I'>w</emphasis>
2611 Specifies the window.
2617 <emphasis remap='I'>hints</emphasis>
2622 <structname>XSizeHints</structname>
2623 structure to be used.
2629 <emphasis remap='I'>property</emphasis>
2633 Specifies the property name.
2642 <xref linkend='XSetWMSizeHints' xrefstyle='select: title'/>
2643 function replaces the size hints for the specified property
2644 on the named window.
2645 If the specified property does not already exist,
2646 <xref linkend='XSetWMSizeHints' xrefstyle='select: title'/>
2647 sets the size hints for the specified property
2648 on the named window.
2649 The property is stored with a type of <property>WM_SIZE_HINTS</property> and a format of 32.
2650 To set a window's normal size hints,
2652 <xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>
2657 <xref linkend='XSetWMSizeHints' xrefstyle='select: title'/>
2659 <errorname>BadAlloc</errorname>,
2660 <errorname>BadAtom</errorname>,
2662 <errorname>BadWindow</errorname>
2668 To read a window's <property>WM_SIZE_HINTS</property> property, use
2669 <xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>.
2671 <indexterm significance="preferred"><primary>XGetWMSizeHints</primary></indexterm>
2673 <funcsynopsis id='XGetWMSizeHints'>
2675 <funcdef>Status <function>XGetWMSizeHints</function></funcdef>
2676 <paramdef>Display<parameter> *display</parameter></paramdef>
2677 <paramdef>Window<parameter> w</parameter></paramdef>
2678 <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
2679 <paramdef>long<parameter> *supplied_return</parameter></paramdef>
2680 <paramdef>Atom<parameter> property</parameter></paramdef>
2687 <emphasis remap='I'>display</emphasis>
2691 Specifies the connection to the X server.
2697 <emphasis remap='I'>w</emphasis>
2701 Specifies the window.
2707 <emphasis remap='I'>hints_return</emphasis>
2712 <structname>XSizeHints</structname>
2719 <emphasis remap='I'>supplied_return</emphasis>
2723 Returns the hints that were supplied by the user.
2729 <emphasis remap='I'>property</emphasis>
2733 Specifies the property name.
2742 <xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>
2743 function returns the size hints stored in the specified property
2744 on the named window.
2745 If the property is of type <property>WM_SIZE_HINTS</property>, is of format 32,
2746 and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>)
2747 or new size hints structure,
2748 <xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>
2749 sets the various fields of the
2750 <structname>XSizeHints</structname>
2751 structure, sets the supplied_return argument to the
2752 list of fields that were supplied by the user
2753 (whether or not they contained defined values),
2754 and returns a nonzero status.
2755 Otherwise, it returns a zero status.
2756 To get a window's normal size hints,
2758 <xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
2764 <xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>
2765 returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read,
2766 the supplied_return argument will contain the following bits:
2770 <literallayout class="monospaced">
2771 (USPosition|USSize|PPosition|PSize|PMinSize|
2772 PMaxSize|PResizeInc|PAspect)
2777 If the property is large enough to contain the base size
2778 and window gravity fields as well,
2779 the supplied_return argument will also contain the following bits:
2783 <literallayout class="monospaced">
2784 PBaseSize|PWinGravity
2789 <xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>
2791 <errorname>BadAtom</errorname>
2793 <errorname>BadWindow</errorname>
2797 <sect2 id="Setting_and_Reading_the_WM_CLASS_Property">
2798 <title>Setting and Reading the WM_CLASS Property</title>
2800 <!-- (SN Setting and Reading the WM_CLASS Property -->
2804 Xlib provides functions that you can use to set and get
2805 the <property>WM_CLASS</property> property for a given window.
2806 These functions use the
2807 <structname>XClassHint</structname>
2808 structure, which is defined in the
2809 <filename class="headerfile"><X11/Xutil.h></filename>
2810 <indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
2811 <indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
2812 <indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
2819 <structname>XClassHint</structname>
2821 <function>XAllocClassHint</function>.
2822 <indexterm significance="preferred"><primary>XAllocClassHint</primary></indexterm>
2827 XClassHint *XAllocClassHint()
2834 <function>XAllocClassHint</function>
2835 function allocates and returns a pointer to an
2836 <structname>XClassHint</structname>
2838 Note that the pointer fields in the
2839 <structname>XClassHint</structname>
2840 structure are initially set to NULL.
2841 If insufficient memory is available,
2842 <function>XAllocClassHint</function>
2844 To free the memory allocated to this structure,
2846 <xref linkend='XFree' xrefstyle='select: title'/>.
2851 <structname>XClassHint</structname>
2857 <indexterm significance="preferred"><primary>XClassHint</primary></indexterm>
2858 <literallayout class="monospaced">
2870 The res_name member contains the application name,
2871 and the res_class member contains the application class.
2872 Note that the name set in this property may differ from the name set as <property>WM_NAME</property>.
2873 That is, <property>WM_NAME</property> specifies what should be displayed in the title bar and,
2874 therefore, can contain temporal information (for example, the name of
2875 a file currently in an editor's buffer).
2877 the name specified as part of <property>WM_CLASS</property> is the formal name of the application
2878 that should be used when retrieving the application's resources from the
2884 To set a window's <property>WM_CLASS</property> property, use
2885 <xref linkend='XSetClassHint' xrefstyle='select: title'/>.
2887 <indexterm significance="preferred"><primary>XSetClassHint</primary></indexterm>
2889 <funcsynopsis id='XSetClassHint'>
2891 <funcdef><function>XSetClassHint</function></funcdef>
2892 <paramdef>Display<parameter> *display</parameter></paramdef>
2893 <paramdef>Window<parameter> w</parameter></paramdef>
2894 <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>
2901 <emphasis remap='I'>display</emphasis>
2905 Specifies the connection to the X server.
2911 <emphasis remap='I'>w</emphasis>
2915 Specifies the window.
2921 <emphasis remap='I'>class_hints</emphasis>
2926 <structname>XClassHint</structname>
2927 structure that is to be used.
2936 <xref linkend='XSetClassHint' xrefstyle='select: title'/>
2937 function sets the class hint for the specified window.
2938 If the strings are not in the Host Portable Character Encoding,
2939 the result is implementation-dependent.
2943 <xref linkend='XSetClassHint' xrefstyle='select: title'/>
2945 <errorname>BadAlloc</errorname>
2947 <errorname>BadWindow</errorname>
2953 To read a window's <property>WM_CLASS</property> property, use
2954 <xref linkend='XGetClassHint' xrefstyle='select: title'/>.
2956 <indexterm significance="preferred"><primary>XGetClassHint</primary></indexterm>
2958 <funcsynopsis id='XGetClassHint'>
2960 <funcdef>Status <function>XGetClassHint</function></funcdef>
2961 <paramdef>Display<parameter> *display</parameter></paramdef>
2962 <paramdef>Window<parameter> w</parameter></paramdef>
2963 <paramdef>XClassHint<parameter> *class_hints_return</parameter></paramdef>
2970 <emphasis remap='I'>display</emphasis>
2974 Specifies the connection to the X server.
2980 <emphasis remap='I'>w</emphasis>
2984 Specifies the window.
2990 <emphasis remap='I'>class_hints_return</emphasis>
2995 <structname>XClassHint</structname>
3005 <xref linkend='XGetClassHint' xrefstyle='select: title'/>
3006 function returns the class hint of the specified window to the members
3007 of the supplied structure.
3008 If the data returned by the server is in the Latin Portable Character Encoding,
3009 then the returned strings are in the Host Portable Character Encoding.
3010 Otherwise, the result is implementation-dependent.
3011 It returns a nonzero status on success;
3012 otherwise, it returns a zero status.
3013 To free res_name and res_class when finished with the strings,
3015 <xref linkend='XFree' xrefstyle='select: title'/>
3016 on each individually.
3020 <xref linkend='XGetClassHint' xrefstyle='select: title'/>
3022 <errorname>BadWindow</errorname>
3026 <sect2 id="Setting_and_Reading_the_WM_TRANSIENT_FOR_Property">
3027 <title>Setting and Reading the WM_TRANSIENT_FOR Property</title>
3029 <!-- (SN Setting and Reading the WM_TRANSIENT_FOR Property -->
3033 Xlib provides functions that you can use to set and read
3034 the <property>WM_TRANSIENT_FOR</property> property for a given window.
3039 To set a window's <property>WM_TRANSIENT_FOR</property> property, use
3040 <xref linkend='XSetTransientForHint' xrefstyle='select: title'/>.
3042 <indexterm significance="preferred"><primary>XSetTransientForHint</primary></indexterm>
3044 <funcsynopsis id='XSetTransientForHint'>
3046 <funcdef><function>XSetTransientForHint</function></funcdef>
3047 <paramdef>Display<parameter> *display</parameter></paramdef>
3048 <paramdef>Window<parameter> w</parameter></paramdef>
3049 <paramdef>Window<parameter> prop_window</parameter></paramdef>
3056 <emphasis remap='I'>display</emphasis>
3060 Specifies the connection to the X server.
3066 <emphasis remap='I'>w</emphasis>
3070 Specifies the window.
3076 <emphasis remap='I'>prop_window</emphasis>
3080 Specifies the window that the <property>WM_TRANSIENT_FOR</property> property is to be set to.
3089 <xref linkend='XSetTransientForHint' xrefstyle='select: title'/>
3090 function sets the <property>WM_TRANSIENT_FOR</property> property of the specified window to the
3091 specified prop_window.
3095 <xref linkend='XSetTransientForHint' xrefstyle='select: title'/>
3097 <errorname>BadAlloc</errorname>
3099 <errorname>BadWindow</errorname>
3105 To read a window's <property>WM_TRANSIENT_FOR</property> property, use
3106 <xref linkend='XGetTransientForHint' xrefstyle='select: title'/>.
3108 <indexterm significance="preferred"><primary>XGetTransientForHint</primary></indexterm>
3110 <funcsynopsis id='XGetTransientForHint'>
3112 <funcdef>Status <function>XGetTransientForHint</function></funcdef>
3113 <paramdef>Display<parameter> *display</parameter></paramdef>
3114 <paramdef>Window<parameter> w</parameter></paramdef>
3115 <paramdef>Window<parameter> *prop_window_return</parameter></paramdef>
3122 <emphasis remap='I'>display</emphasis>
3126 Specifies the connection to the X server.
3132 <emphasis remap='I'>w</emphasis>
3136 Specifies the window.
3142 <emphasis remap='I'>prop_window_return</emphasis>
3146 Returns the <property>WM_TRANSIENT_FOR</property> property of the specified window.
3155 <xref linkend='XGetTransientForHint' xrefstyle='select: title'/>
3156 function returns the <property>WM_TRANSIENT_FOR</property> property for the specified window.
3157 It returns a nonzero status on success;
3158 otherwise, it returns a zero status.
3162 <xref linkend='XGetTransientForHint' xrefstyle='select: title'/>
3164 <errorname>BadWindow</errorname>
3168 <sect2 id="Setting_and_Reading_the_WM_PROTOCOLS_Property">
3169 <title>Setting and Reading the WM_PROTOCOLS Property</title>
3171 <!-- (SN Setting and Reading the WM_PROTOCOLS Property -->
3175 Xlib provides functions that you can use to set and read
3176 the <property>WM_PROTOCOLS</property> property for a given window.
3181 To set a window's <property>WM_PROTOCOLS</property> property, use
3182 <xref linkend='XSetWMProtocols' xrefstyle='select: title'/>.
3184 <indexterm significance="preferred"><primary>XSetWMProtocols</primary></indexterm>
3186 <funcsynopsis id='XSetWMProtocols'>
3188 <funcdef>Status <function>XSetWMProtocols</function></funcdef>
3189 <paramdef>Display<parameter> *display</parameter></paramdef>
3190 <paramdef>Window<parameter> w</parameter></paramdef>
3191 <paramdef>Atom<parameter> *protocols</parameter></paramdef>
3192 <paramdef>int<parameter> count</parameter></paramdef>
3199 <emphasis remap='I'>display</emphasis>
3203 Specifies the connection to the X server.
3209 <emphasis remap='I'>w</emphasis>
3213 Specifies the window.
3219 <emphasis remap='I'>protocols</emphasis>
3223 Specifies the list of protocols.
3224 <!-- .ds Cn protocols in the list -->
3230 <emphasis remap='I'>count</emphasis>
3234 Specifies the number of (Cn.
3243 <xref linkend='XSetWMProtocols' xrefstyle='select: title'/>
3244 function replaces the <property>WM_PROTOCOLS</property> property on the specified window
3245 with the list of atoms specified by the protocols argument.
3246 If the property does not already exist,
3247 <xref linkend='XSetWMProtocols' xrefstyle='select: title'/>
3248 sets the <property>WM_PROTOCOLS</property> property on the specified window
3249 to the list of atoms specified by the protocols argument.
3250 The property is stored with a type of ATOM and a format of 32.
3251 If it cannot intern the <property>WM_PROTOCOLS</property> atom,
3252 <xref linkend='XSetWMProtocols' xrefstyle='select: title'/>
3253 returns a zero status.
3254 Otherwise, it returns a nonzero status.
3258 <xref linkend='XSetWMProtocols' xrefstyle='select: title'/>
3260 <errorname>BadAlloc</errorname>
3262 <errorname>BadWindow</errorname>
3268 To read a window's <property>WM_PROTOCOLS</property> property, use
3269 <xref linkend='XGetWMProtocols' xrefstyle='select: title'/>.
3271 <indexterm significance="preferred"><primary>XGetWMProtocols</primary></indexterm>
3273 <funcsynopsis id='XGetWMProtocols'>
3275 <funcdef>Status <function>XGetWMProtocols</function></funcdef>
3276 <paramdef>Display<parameter> *display</parameter></paramdef>
3277 <paramdef>Window<parameter> w</parameter></paramdef>
3278 <paramdef>Atom<parameter> **protocols_return</parameter></paramdef>
3279 <paramdef>int<parameter> *count_return</parameter></paramdef>
3286 <emphasis remap='I'>display</emphasis>
3290 Specifies the connection to the X server.
3296 <emphasis remap='I'>w</emphasis>
3300 Specifies the window.
3306 <emphasis remap='I'>protocols_return</emphasis>
3310 Returns the list of protocols.
3311 <!-- .ds Cn protocols in the list -->
3317 <emphasis remap='I'>count_return</emphasis>
3321 Returns the number of (Cn.
3330 <xref linkend='XGetWMProtocols' xrefstyle='select: title'/>
3331 function returns the list of atoms stored in the <property>WM_PROTOCOLS</property> property
3332 on the specified window.
3333 These atoms describe window manager protocols in which the owner
3334 of this window is willing to participate.
3335 If the property exists, is of type ATOM, is of format 32,
3336 and the atom <property>WM_PROTOCOLS</property> can be interned,
3337 <xref linkend='XGetWMProtocols' xrefstyle='select: title'/>
3338 sets the protocols_return argument to a list of atoms,
3339 sets the count_return argument to the number of elements in the list,
3340 and returns a nonzero status.
3341 Otherwise, it sets neither of the return arguments
3342 and returns a zero status.
3343 To release the list of atoms, use
3344 <xref linkend='XFree' xrefstyle='select: title'/>.
3348 <xref linkend='XGetWMProtocols' xrefstyle='select: title'/>
3350 <errorname>BadWindow</errorname>
3354 <sect2 id="Setting_and_Reading_the_WM_COLORMAP_WINDOWS_Property">
3355 <title>Setting and Reading the WM_COLORMAP_WINDOWS Property</title>
3357 <!-- (SN Setting and Reading the WM_COLORMAP_WINDOWS Property -->
3361 Xlib provides functions that you can use to set and read
3362 the <property>WM_COLORMAP_WINDOWS</property> property for a given window.
3367 To set a window's <property>WM_COLORMAP_WINDOWS</property> property, use
3368 <xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>.
3370 <indexterm significance="preferred"><primary>XSetWMColormapWindows</primary></indexterm>
3372 <funcsynopsis id='XSetWMColormapWindows'>
3374 <funcdef>Status <function>XSetWMColormapWindows</function></funcdef>
3375 <paramdef>Display<parameter> *display</parameter></paramdef>
3376 <paramdef>Window<parameter> w</parameter></paramdef>
3377 <paramdef>Window<parameter> *colormap_windows</parameter></paramdef>
3378 <paramdef>int<parameter> count</parameter></paramdef>
3385 <emphasis remap='I'>display</emphasis>
3389 Specifies the connection to the X server.
3395 <emphasis remap='I'>w</emphasis>
3399 Specifies the window.
3405 <emphasis remap='I'>colormap_windows</emphasis>
3409 Specifies the list of windows.
3410 <!-- .ds Cn windows in the list -->
3416 <emphasis remap='I'>count</emphasis>
3420 Specifies the number of (Cn.
3429 <xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>
3430 function replaces the <property>WM_COLORMAP_WINDOWS</property> property on the specified
3431 window with the list of windows specified by the colormap_windows argument.
3432 If the property does not already exist,
3433 <xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>
3434 sets the <property>WM_COLORMAP_WINDOWS</property> property on the specified
3435 window to the list of windows specified by the colormap_windows argument.
3436 The property is stored with a type of WINDOW and a format of 32.
3437 If it cannot intern the <property>WM_COLORMAP_WINDOWS</property> atom,
3438 <xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>
3439 returns a zero status.
3440 Otherwise, it returns a nonzero status.
3444 <xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>
3446 <errorname>BadAlloc</errorname>
3448 <errorname>BadWindow</errorname>
3454 To read a window's <property>WM_COLORMAP_WINDOWS</property> property, use
3455 <xref linkend='XGetWMColormapWindows' xrefstyle='select: title'/>.
3457 <indexterm significance="preferred"><primary>XGetWMColormapWindows</primary></indexterm>
3459 <funcsynopsis id='XGetWMColormapWindows'>
3461 <funcdef>Status <function>XGetWMColormapWindows</function></funcdef>
3462 <paramdef>Display<parameter> *display</parameter></paramdef>
3463 <paramdef>Window<parameter> w</parameter></paramdef>
3464 <paramdef>Window<parameter> **colormap_windows_return</parameter></paramdef>
3465 <paramdef>int<parameter> *count_return</parameter></paramdef>
3472 <emphasis remap='I'>display</emphasis>
3476 Specifies the connection to the X server.
3482 <emphasis remap='I'>w</emphasis>
3486 Specifies the window.
3492 <emphasis remap='I'>colormap_windows_return</emphasis>
3496 Returns the list of windows.
3497 <!-- .ds Cn windows in the list -->
3503 <emphasis remap='I'>count_return</emphasis>
3507 Returns the number of (Cn.
3516 <xref linkend='XGetWMColormapWindows' xrefstyle='select: title'/>
3517 function returns the list of window identifiers stored
3518 in the <property>WM_COLORMAP_WINDOWS</property> property on the specified window.
3519 These identifiers indicate the colormaps that the window manager
3520 may need to install for this window.
3521 If the property exists, is of type WINDOW, is of format 32,
3522 and the atom <property>WM_COLORMAP_WINDOWS</property> can be interned,
3523 <xref linkend='XGetWMColormapWindows' xrefstyle='select: title'/>
3524 sets the windows_return argument to a list of window identifiers,
3525 sets the count_return argument to the number of elements in the list,
3526 and returns a nonzero status.
3527 Otherwise, it sets neither of the return arguments
3528 and returns a zero status.
3529 To release the list of window identifiers, use
3530 <xref linkend='XFree' xrefstyle='select: title'/>.
3534 <xref linkend='XGetWMColormapWindows' xrefstyle='select: title'/>
3536 <errorname>BadWindow</errorname>
3540 <sect2 id="Setting_and_Reading_the_WM_ICON_SIZE_Property">
3541 <title>Setting and Reading the WM_ICON_SIZE Property</title>
3543 <!-- (SN Setting and Reading the WM_ICON_SIZE Property -->
3547 Xlib provides functions that you can use to set and read
3548 the <property>WM_ICON_SIZE</property> property for a given window.
3549 These functions use the
3550 <structname>XIconSize</structname>
3551 <indexterm><primary>XIconSize</primary></indexterm>
3552 structure, which is defined in the
3553 <filename class="headerfile"><X11/Xutil.h></filename>
3554 <indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
3555 <indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
3556 <indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
3563 <structname>XIconSize</structname>
3565 <function>XAllocIconSize</function>.
3569 XIconSize *XAllocIconSize()
3576 <function>XAllocIconSize</function>
3577 function allocates and returns a pointer to an
3578 <structname>XIconSize</structname>
3580 Note that all fields in the
3581 <structname>XIconSize</structname>
3582 structure are initially set to zero.
3583 If insufficient memory is available,
3584 <function>XAllocIconSize</function>
3586 To free the memory allocated to this structure,
3588 <xref linkend='XFree' xrefstyle='select: title'/>.
3593 <structname>XIconSize</structname>
3599 <indexterm significance="preferred"><primary>XIconSize</primary></indexterm>
3600 <literallayout class="monospaced">
3601 <!-- .TA .5i 2.5i -->
3602 <!-- .ta .5i 2.5i -->
3604 int min_width, min_height;
3605 int max_width, max_height;
3606 int width_inc, height_inc;
3613 The width_inc and height_inc members define an arithmetic progression of
3614 sizes (minimum to maximum) that represent the supported icon sizes.
3619 To set a window's <property>WM_ICON_SIZE</property> property, use
3620 <xref linkend='XSetIconSizes' xrefstyle='select: title'/>.
3622 <indexterm significance="preferred"><primary>XSetIconSizes</primary></indexterm>
3624 <funcsynopsis id='XSetIconSizes'>
3626 <funcdef><function>XSetIconSizes</function></funcdef>
3627 <paramdef>Display<parameter> *display</parameter></paramdef>
3628 <paramdef>Window<parameter> w</parameter></paramdef>
3629 <paramdef>XIconSize<parameter> *size_list</parameter></paramdef>
3630 <paramdef>int<parameter> count</parameter></paramdef>
3637 <emphasis remap='I'>display</emphasis>
3641 Specifies the connection to the X server.
3647 <emphasis remap='I'>w</emphasis>
3651 Specifies the window.
3657 <emphasis remap='I'>size_list</emphasis>
3661 Specifies the size list.
3667 <emphasis remap='I'>count</emphasis>
3671 Specifies the number of items in the size list.
3680 <xref linkend='XSetIconSizes' xrefstyle='select: title'/>
3681 function is used only by window managers to set the supported icon sizes.
3685 <xref linkend='XSetIconSizes' xrefstyle='select: title'/>
3687 <errorname>BadAlloc</errorname>
3689 <errorname>BadWindow</errorname>
3695 To read a window's <property>WM_ICON_SIZE</property> property, use
3696 <xref linkend='XGetIconSizes' xrefstyle='select: title'/>.
3698 <indexterm significance="preferred"><primary>XGetIconSizes</primary></indexterm>
3700 <funcsynopsis id='XGetIconSizes'>
3702 <funcdef>Status <function>XGetIconSizes</function></funcdef>
3703 <paramdef>Display<parameter> *display</parameter></paramdef>
3704 <paramdef>Window<parameter> w</parameter></paramdef>
3705 <paramdef>XIconSize<parameter> **size_list_return</parameter></paramdef>
3706 <paramdef>int<parameter> *count_return</parameter></paramdef>
3713 <emphasis remap='I'>display</emphasis>
3717 Specifies the connection to the X server.
3723 <emphasis remap='I'>w</emphasis>
3727 Specifies the window.
3733 <emphasis remap='I'>size_list_return</emphasis>
3737 Returns the size list.
3743 <emphasis remap='I'>count_return</emphasis>
3747 Returns the number of items in the size list.
3756 <xref linkend='XGetIconSizes' xrefstyle='select: title'/>
3757 function returns zero if a window manager has not set icon sizes;
3758 otherwise, it returns nonzero.
3759 <xref linkend='XGetIconSizes' xrefstyle='select: title'/>
3760 should be called by an application that
3761 wants to find out what icon sizes would be most appreciated by the
3762 window manager under which the application is running.
3765 <xref linkend='XSetWMHints' xrefstyle='select: title'/>
3766 to supply the window manager with an icon pixmap or window in one of the
3768 To free the data allocated in size_list_return, use
3769 <xref linkend='XFree' xrefstyle='select: title'/>.
3773 <xref linkend='XGetIconSizes' xrefstyle='select: title'/>
3775 <errorname>BadWindow</errorname>
3779 <sect2 id="Using_Window_Manager_Convenience_Functions">
3780 <title>Using Window Manager Convenience Functions</title>
3782 <!-- (SN Using Window Manager Convenience Functions -->
3787 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
3788 function stores the standard set of window manager properties,
3789 with text properties in standard encodings
3790 for internationalized text communication.
3791 The standard window manager properties for a given window are
3792 <property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_NORMAL_HINTS</property>, <property>WM_CLASS</property>,
3793 <property>WM_COMMAND</property>, <property>WM_CLIENT_MACHINE</property>, and <property>WM_LOCALE_NAME</property>.
3795 <indexterm significance="preferred"><primary>XmbSetWMProperties</primary></indexterm>
3797 <funcsynopsis id='XmbSetWMProperties'>
3799 <funcdef>void <function>XmbSetWMProperties</function></funcdef>
3800 <paramdef>Display<parameter> *display</parameter></paramdef>
3801 <paramdef>Window<parameter> w</parameter></paramdef>
3802 <paramdef>char<parameter> *window_name</parameter></paramdef>
3803 <paramdef>char<parameter> *icon_name</parameter></paramdef>
3804 <paramdef>char<parameter> *argv[]</parameter></paramdef>
3805 <paramdef>int<parameter> argc</parameter></paramdef>
3806 <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>
3807 <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>
3808 <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>
3815 <emphasis remap='I'>display</emphasis>
3819 Specifies the connection to the X server.
3825 <emphasis remap='I'>w</emphasis>
3829 Specifies the window.
3835 <emphasis remap='I'>window_name</emphasis>
3839 Specifies the window name,
3840 which should be a null-terminated string.
3846 <emphasis remap='I'>icon_name</emphasis>
3850 Specifies the icon name,
3851 which should be a null-terminated string.
3857 <emphasis remap='I'>argv</emphasis>
3861 Specifies the application's argument list.
3867 <emphasis remap='I'>argc</emphasis>
3871 Specifies the number of arguments.
3877 <emphasis remap='I'>hints</emphasis>
3881 Specifies the size hints for the window in its normal state.
3887 <emphasis remap='I'>wm_hints</emphasis>
3892 <structname>XWMHints</structname>
3893 structure to be used.
3899 <emphasis remap='I'>class_hints</emphasis>
3904 <structname>XClassHint</structname>
3905 structure to be used.
3914 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
3915 convenience function provides a simple programming interface
3916 for setting those essential window properties that are used
3917 for communicating with other clients
3918 (particularly window and session managers).
3922 If the window_name argument is non-NULL,
3923 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
3924 sets the <property>WM_NAME</property> property.
3925 If the icon_name argument is non-NULL,
3926 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
3927 sets the <property>WM_ICON_NAME</property> property.
3928 The window_name and icon_name arguments are null-terminated strings
3929 in the encoding of the current locale.
3930 If the arguments can be fully converted to the STRING encoding,
3931 the properties are created with type ``STRING'';
3932 otherwise, the arguments are converted to Compound Text,
3933 and the properties are created with type ``COMPOUND_TEXT''.
3937 If the normal_hints argument is non-NULL,
3938 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
3940 <xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>,
3941 which sets the <property>WM_NORMAL_HINTS</property> property
3942 (see <link linkend="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">section 14.1.7</link>).
3943 If the wm_hints argument is non-NULL,
3944 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
3946 <xref linkend='XSetWMHints' xrefstyle='select: title'/>,
3947 which sets the <property>WM_HINTS</property> property
3948 (see <link linkend="Setting_and_Reading_the_WM_HINTS_Property">section 14.1.6</link>).
3952 If the argv argument is non-NULL,
3953 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
3954 sets the <property>WM_COMMAND</property> property from argv and argc.
3955 An argc of zero indicates a zero-length command.
3959 The hostname of the machine is stored using
3960 <xref linkend='XSetWMClientMachine' xrefstyle='select: title'/>
3961 (see <link linkend="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">section 14.2.2</link>).
3965 If the class_hints argument is non-NULL,
3966 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
3967 sets the <property>WM_CLASS</property> property.
3968 If the res_name member in the
3969 <structname>XClassHint</structname>
3970 structure is set to the NULL pointer and the RESOURCE_NAME
3971 environment variable is set,
3972 the value of the environment variable is substituted for res_name.
3973 If the res_name member is NULL,
3974 the environment variable is not set, and argv and argv[0] are set,
3975 then the value of argv[0], stripped of any directory prefixes,
3976 is substituted for res_name.
3980 It is assumed that the supplied class_hints.res_name and argv,
3981 the RESOURCE_NAME environment variable, and the hostname of the machine
3982 are in the encoding of the locale announced for the LC_CTYPE category
3983 (on <acronym>POSIX</acronym>-compliant systems, the LC_CTYPE, else LANG environment variable).
3984 The corresponding <property>WM_CLASS</property>, <property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property> properties
3985 are typed according to the local host locale announcer.
3986 No encoding conversion is performed prior to storage in the properties.
3990 For clients that need to process the property text in a locale,
3991 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
3992 sets the <property>WM_LOCALE_NAME</property> property to be the name of the current locale.
3993 The name is assumed to be in the Host Portable Character Encoding
3994 and is converted to STRING for storage in the property.
3998 <xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
4000 <errorname>BadAlloc</errorname>
4002 <errorname>BadWindow</errorname>
4008 To set a window's standard window manager properties
4009 with strings in client-specified encodings, use
4010 <xref linkend='XSetWMProperties' xrefstyle='select: title'/>.
4011 The standard window manager properties for a given window are
4012 <property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_NORMAL_HINTS</property>, <property>WM_CLASS</property>,
4013 <property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property>.
4015 <indexterm significance="preferred"><primary>XSetWMProperties</primary></indexterm>
4017 <funcsynopsis id='XSetWMProperties'>
4019 <funcdef>void <function>XSetWMProperties</function></funcdef>
4020 <paramdef>Display<parameter> *display</parameter></paramdef>
4021 <paramdef>Window<parameter> w</parameter></paramdef>
4022 <paramdef>XTextProperty<parameter> *window_name</parameter></paramdef>
4023 <paramdef>XTextProperty<parameter> *icon_name</parameter></paramdef>
4024 <paramdef>char<parameter> **argv</parameter></paramdef>
4025 <paramdef>int<parameter> argc</parameter></paramdef>
4026 <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>
4027 <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>
4028 <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>
4035 <emphasis remap='I'>display</emphasis>
4039 Specifies the connection to the X server.
4045 <emphasis remap='I'>w</emphasis>
4049 Specifies the window.
4055 <emphasis remap='I'>window_name</emphasis>
4059 Specifies the window name,
4060 which should be a null-terminated string.
4066 <emphasis remap='I'>icon_name</emphasis>
4070 Specifies the icon name,
4071 which should be a null-terminated string.
4077 <emphasis remap='I'>argv</emphasis>
4081 Specifies the application's argument list.
4087 <emphasis remap='I'>argc</emphasis>
4091 Specifies the number of arguments.
4097 <emphasis remap='I'>normal_hints</emphasis>
4101 Specifies the size hints for the window in its normal state.
4107 <emphasis remap='I'>wm_hints</emphasis>
4112 <structname>XWMHints</structname>
4113 structure to be used.
4119 <emphasis remap='I'>class_hints</emphasis>
4124 <structname>XClassHint</structname>
4125 structure to be used.
4134 <xref linkend='XSetWMProperties' xrefstyle='select: title'/>
4135 convenience function provides a single programming interface
4136 for setting those essential window properties that are used
4137 for communicating with other clients (particularly window and session
4142 If the window_name argument is non-NULL,
4143 <xref linkend='XSetWMProperties' xrefstyle='select: title'/>
4145 <xref linkend='XSetWMName' xrefstyle='select: title'/>,
4146 which, in turn, sets the <property>WM_NAME</property> property
4147 (see <link linkend="Setting_and_Reading_the_WM_NAME_Property">section 14.1.4</link>).
4148 If the icon_name argument is non-NULL,
4149 <xref linkend='XSetWMProperties' xrefstyle='select: title'/>
4151 <xref linkend='XSetWMIconName' xrefstyle='select: title'/>,
4152 which sets the <property>WM_ICON_NAME</property> property
4153 (see <link linkend="Setting_and_Reading_the_WM_ICON_NAME_Property">section 14.1.5</link>).
4154 If the argv argument is non-NULL,
4155 <xref linkend='XSetWMProperties' xrefstyle='select: title'/>
4157 <xref linkend='XSetCommand' xrefstyle='select: title'/>,
4158 which sets the <property>WM_COMMAND</property> property
4159 (see <link linkend="Setting_and_Reading_the_WM_COMMAND_Property">section 14.2.1</link>).
4160 Note that an argc of zero is allowed to indicate a zero-length command.
4161 Note also that the hostname of this machine is stored using
4162 <xref linkend='XSetWMClientMachine' xrefstyle='select: title'/>
4163 (see <link linkend="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">section 14.2.2</link>).
4167 If the normal_hints argument is non-NULL,
4168 <xref linkend='XSetWMProperties' xrefstyle='select: title'/>
4170 <xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>,
4171 which sets the <property>WM_NORMAL_HINTS</property> property
4172 (see <link linkend="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">section 14.1.7</link>).
4173 If the wm_hints argument is non-NULL,
4174 <xref linkend='XSetWMProperties' xrefstyle='select: title'/>
4176 <xref linkend='XSetWMHints' xrefstyle='select: title'/>,
4177 which sets the <property>WM_HINTS</property> property
4178 (see <link linkend="Setting_and_Reading_the_WM_HINTS_Property">section 14.1.6</link>).
4182 If the class_hints argument is non-NULL,
4183 <xref linkend='XSetWMProperties' xrefstyle='select: title'/>
4185 <xref linkend='XSetClassHint' xrefstyle='select: title'/>,
4186 which sets the <property>WM_CLASS</property> property
4187 (see <link linkend="Setting_and_Reading_the_WM_CLASS_Property">section 14.1.8</link>).
4188 If the res_name member in the
4189 <structname>XClassHint</structname>
4190 structure is set to the NULL pointer and the RESOURCE_NAME environment
4192 then the value of the environment variable is substituted for res_name.
4193 If the res_name member is NULL,
4194 the environment variable is not set,
4195 and argv and argv[0] are set,
4196 then the value of argv[0], stripped of
4197 any directory prefixes, is substituted for res_name.
4201 <xref linkend='XSetWMProperties' xrefstyle='select: title'/>
4203 <errorname>BadAlloc</errorname>
4205 <errorname>BadWindow</errorname>
4210 <sect1 id="Client_to_Session_Manager_Communication">
4211 <title>Client to Session Manager Communication</title>
4213 <!-- (SN Client to Session Manager Communication -->
4217 This section discusses how to:
4222 Set and read the <property>WM_COMMAND</property> property
4227 Set and read the <property>WM_CLIENT_MACHINE</property> property
4231 <sect2 id="Setting_and_Reading_the_WM_COMMAND_Property">
4232 <title>Setting and Reading the WM_COMMAND Property</title>
4234 <!-- (SN Setting and Reading the WM_COMMAND Property -->
4238 Xlib provides functions that you can use to set and read
4239 the <property>WM_COMMAND</property> property for a given window.
4244 To set a window's <property>WM_COMMAND</property> property, use
4245 <xref linkend='XSetCommand' xrefstyle='select: title'/>.
4247 <indexterm significance="preferred"><primary>XSetCommand</primary></indexterm>
4249 <funcsynopsis id='XSetCommand'>
4251 <funcdef><function>XSetCommand</function></funcdef>
4252 <paramdef>Display<parameter> *display</parameter></paramdef>
4253 <paramdef>Window<parameter> w</parameter></paramdef>
4254 <paramdef>char<parameter> **argv</parameter></paramdef>
4255 <paramdef>int<parameter> argc</parameter></paramdef>
4262 <emphasis remap='I'>display</emphasis>
4266 Specifies the connection to the X server.
4272 <emphasis remap='I'>w</emphasis>
4276 Specifies the window.
4282 <emphasis remap='I'>argv</emphasis>
4286 Specifies the application's argument list.
4292 <emphasis remap='I'>argc</emphasis>
4296 Specifies the number of arguments.
4305 <xref linkend='XSetCommand' xrefstyle='select: title'/>
4306 function sets the command and arguments used to invoke the
4308 (Typically, argv is the argv array of your main program.)
4309 If the strings are not in the Host Portable Character Encoding,
4310 the result is implementation-dependent.
4314 <xref linkend='XSetCommand' xrefstyle='select: title'/>
4316 <errorname>BadAlloc</errorname>
4318 <errorname>BadWindow</errorname>
4324 To read a window's <property>WM_COMMAND</property> property, use
4325 <xref linkend='XGetCommand' xrefstyle='select: title'/>.
4327 <indexterm significance="preferred"><primary>XGetCommand</primary></indexterm>
4329 <funcsynopsis id='XGetCommand'>
4331 <funcdef>Status <function>XGetCommand</function></funcdef>
4332 <paramdef>Display<parameter> *display</parameter></paramdef>
4333 <paramdef>Window<parameter> w</parameter></paramdef>
4334 <paramdef>char<parameter> ***argv_return</parameter></paramdef>
4335 <paramdef>int<parameter> *argc_return</parameter></paramdef>
4342 <emphasis remap='I'>display</emphasis>
4346 Specifies the connection to the X server.
4352 <emphasis remap='I'>w</emphasis>
4356 Specifies the window.
4362 <emphasis remap='I'>argv_return</emphasis>
4366 Returns the application's argument list.
4372 <emphasis remap='I'>argc_return</emphasis>
4376 Returns the number of arguments returned.
4385 <xref linkend='XGetCommand' xrefstyle='select: title'/>
4386 function reads the <property>WM_COMMAND</property> property from the specified window
4387 and returns a string list.
4388 If the <property>WM_COMMAND</property> property exists,
4389 it is of type STRING and format 8.
4390 If sufficient memory can be allocated to contain the string list,
4391 <xref linkend='XGetCommand' xrefstyle='select: title'/>
4392 fills in the argv_return and argc_return arguments
4393 and returns a nonzero status.
4394 Otherwise, it returns a zero status.
4395 If the data returned by the server is in the Latin Portable Character Encoding,
4396 then the returned strings are in the Host Portable Character Encoding.
4397 Otherwise, the result is implementation-dependent.
4398 To free the memory allocated to the string list, use
4399 <xref linkend='XFreeStringList' xrefstyle='select: title'/>.
4402 <sect2 id="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">
4403 <title>Setting and Reading the WM_CLIENT_MACHINE Property</title>
4405 <!-- (SN Setting and Reading the WM_CLIENT_MACHINE Property -->
4409 Xlib provides functions that you can use to set and read
4410 the <property>WM_CLIENT_MACHINE</property> property for a given window.
4415 To set a window's <property>WM_CLIENT_MACHINE</property> property, use
4416 <xref linkend='XSetWMClientMachine' xrefstyle='select: title'/>.
4418 <indexterm significance="preferred"><primary>XSetWMClientMachine</primary></indexterm>
4420 <funcsynopsis id='XSetWMClientMachine'>
4422 <funcdef>void <function>XSetWMClientMachine</function></funcdef>
4423 <paramdef>Display<parameter> *display</parameter></paramdef>
4424 <paramdef>Window<parameter> w</parameter></paramdef>
4425 <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
4432 <emphasis remap='I'>display</emphasis>
4436 Specifies the connection to the X server.
4442 <emphasis remap='I'>w</emphasis>
4446 Specifies the window.
4452 <emphasis remap='I'>text_prop</emphasis>
4457 <structname>XTextProperty</structname>
4458 structure to be used.
4467 <xref linkend='XSetWMClientMachine' xrefstyle='select: title'/>
4468 convenience function calls
4469 <xref linkend='XSetTextProperty' xrefstyle='select: title'/>
4470 to set the <property>WM_CLIENT_MACHINE</property> property.
4475 To read a window's <property>WM_CLIENT_MACHINE</property> property, use
4476 <xref linkend='XGetWMClientMachine' xrefstyle='select: title'/>.
4478 <indexterm significance="preferred"><primary>XGetWMClientMachine</primary></indexterm>
4480 <funcsynopsis id='XGetWMClientMachine'>
4482 <funcdef>Status <function>XGetWMClientMachine</function></funcdef>
4483 <paramdef>Display<parameter> *display</parameter></paramdef>
4484 <paramdef>Window<parameter> w</parameter></paramdef>
4485 <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
4492 <emphasis remap='I'>display</emphasis>
4496 Specifies the connection to the X server.
4502 <emphasis remap='I'>w</emphasis>
4506 Specifies the window.
4512 <emphasis remap='I'>text_prop_return</emphasis>
4517 <structname>XTextProperty</structname>
4527 <xref linkend='XGetWMClientMachine' xrefstyle='select: title'/>
4528 convenience function performs an
4529 <xref linkend='XGetTextProperty' xrefstyle='select: title'/>
4530 on the <property>WM_CLIENT_MACHINE</property> property.
4531 It returns a nonzero status on success;
4532 otherwise, it returns a zero status.
4536 <sect1 id="Standard_Colormaps">
4537 <title>Standard Colormaps</title>
4539 <!-- (SN Standard Colormaps -->
4543 Applications with color palettes, smooth-shaded drawings, or digitized
4544 images demand large numbers of colors.
4545 In addition, these applications often require an efficient mapping
4546 from color triples to pixel values that display the appropriate colors.
4550 As an example, consider a three-dimensional display program that wants
4551 to draw a smoothly shaded sphere.
4552 At each pixel in the image of the sphere,
4553 the program computes the intensity and color of light
4554 reflected back to the viewer.
4555 The result of each computation is a triple of red, green, and blue (<acronym>RGB</acronym>)
4556 coefficients in the range 0.0 to 1.0.
4557 To draw the sphere, the program needs a colormap that provides a
4558 large range of uniformly distributed colors.
4559 The colormap should be arranged so that the program can
4560 convert its <acronym>RGB</acronym> triples into pixel values very quickly,
4561 because drawing the entire sphere requires many such
4566 On many current workstations,
4567 the display is limited to 256 or fewer colors.
4568 Applications must allocate colors carefully,
4569 not only to make sure they cover the entire range they need
4570 but also to make use of as many of the available colors as possible.
4571 On a typical X display,
4572 many applications are active at once.
4573 Most workstations have only one hardware look-up table for colors,
4574 so only one application colormap can be installed at a given time.
4575 The application using the installed colormap is displayed correctly,
4576 and the other applications go technicolor and are
4577 displayed with false colors.
4581 As another example, consider a user who is running an
4582 image processing program to display earth-resources data.
4583 The image processing program needs a colormap set up with 8 reds,
4584 8 greens, and 4 blues, for a total of 256 colors.
4585 Because some colors are already in use in the default colormap,
4586 the image processing program allocates and installs a new colormap.
4590 The user decides to alter some of the colors in the image
4591 by invoking a color palette program to mix and choose colors.
4592 The color palette program also needs a
4593 colormap with eight reds, eight greens, and four blues, so just like
4594 the image processing program, it must allocate and
4595 install a new colormap.
4599 Because only one colormap can be installed at a time,
4600 the color palette may be displayed incorrectly
4601 whenever the image processing program is active.
4602 Conversely, whenever the palette program is active,
4603 the image may be displayed incorrectly.
4604 The user can never match or compare colors in the palette and image.
4605 Contention for colormap resources can be reduced if applications
4606 with similar color needs share colormaps.
4610 The image processing program and the color palette program
4611 could share the same colormap if there existed a convention that described
4612 how the colormap was set up.
4613 Whenever either program was active,
4614 both would be displayed correctly.
4618 The standard colormap properties define a set of commonly used
4620 Applications that share these colormaps and conventions display
4621 true colors more often and provide a better interface to the user.
4625 Standard colormaps allow applications to share commonly used color
4627 This allows many applications to be displayed in true colors
4628 simultaneously, even when each application needs an entirely filled
4633 Several standard colormaps are described in this section.
4634 Usually, a window manager creates these colormaps.
4635 Applications should use the standard colormaps if they already exist.
4641 <structname>XStandardColormap</structname>
4643 <function>XAllocStandardColormap</function>.
4647 XStandardColormap *XAllocStandardColormap()
4653 <function>XAllocStandardColormap</function>
4654 function allocates and returns a pointer to an
4655 <structname>XStandardColormap</structname>
4657 Note that all fields in the
4658 <structname>XStandardColormap</structname>
4659 structure are initially set to zero.
4660 If insufficient memory is available,
4661 <function>XAllocStandardColormap</function>
4663 To free the memory allocated to this structure,
4665 <xref linkend='XFree' xrefstyle='select: title'/>.
4670 <structname>XStandardColormap</structname>
4673 <literallayout class="monospaced">
4676 #define ReeaseByFreeingColormap ((XID)1L)
4682 unsigned long red_max;
4683 unsigned long red_mult;
4684 unsigned long green_max;
4685 unsigned long green_mult;
4686 unsigned long blue_max;
4687 unsigned long blue_mult;
4688 unsigned long base_pixel;
4691 } XStandardColormap;
4697 The colormap member is the colormap created by the
4698 <xref linkend='XCreateColormap' xrefstyle='select: title'/>
4700 The red_max, green_max, and blue_max members give the maximum
4701 red, green, and blue values, respectively.
4702 Each color coefficient ranges from zero to its max, inclusive.
4704 a common colormap allocation is 3/3/2 (3 planes for red, 3
4705 planes for green, and 2 planes for blue).
4706 This colormap would have red_max = 7, green_max = 7,
4708 An alternate allocation that uses only 216 colors is red_max = 5,
4709 green_max = 5, and blue_max = 5.
4713 The red_mult, green_mult, and blue_mult members give the
4714 scale factors used to compose a full pixel value.
4715 (See the discussion of the base_pixel members for further information.)
4716 For a 3/3/2 allocation, red_mult might be 32,
4717 green_mult might be 4, and blue_mult might be 1.
4718 For a 6-colors-each allocation, red_mult might be 36,
4719 green_mult might be 6, and blue_mult might be 1.
4723 The base_pixel member gives the base pixel value used to
4724 compose a full pixel value.
4725 Usually, the base_pixel is obtained from a call to the
4726 <xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
4728 Given integer red, green, and blue coefficients in their appropriate
4729 ranges, one then can compute a corresponding pixel value by
4730 using the following expression:
4734 <literallayout class="monospaced">
4735 <!-- .TA .5i 1.5i -->
4736 <!-- .ta .5i 1.5i -->
4737 (r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF
4743 <symbol>GrayScale</symbol>
4745 only the colormap, red_max, red_mult,
4746 and base_pixel members are defined.
4747 The other members are ignored.
4749 <symbol>GrayScale</symbol>
4750 pixel value, use the following expression:
4754 <literallayout class="monospaced">
4755 <!-- .TA .5i 1.5i -->
4756 <!-- .ta .5i 1.5i -->
4757 (gray * red_mult + base_pixel) & 0xFFFFFFFF
4762 Negative multipliers can be represented by converting the 2's
4763 complement representation of the multiplier into an unsigned long and
4764 storing the result in the appropriate _mult field.
4765 The step of masking by 0xFFFFFFFF effectively converts the resulting
4766 positive multiplier into a negative one.
4767 The masking step will take place automatically on many machine architectures,
4768 depending on the size of the integer type used to do the computation.
4772 The visualid member gives the ID number of the visual from which the
4773 colormap was created.
4774 The killid member gives a resource ID that indicates whether
4775 the cells held by this standard colormap are to be released
4776 by freeing the colormap ID or by calling the
4777 <xref linkend='XKillClient' xrefstyle='select: title'/>
4778 function on the indicated resource.
4779 (Note that this method is necessary for allocating out of an existing colormap.)
4783 The properties containing the
4784 <structname>XStandardColormap</structname>
4786 the type RGB_COLOR_MAP.
4790 The remainder of this section discusses standard colormap properties and atoms
4791 as well as how to manipulate standard colormaps.
4793 <sect2 id="Standard_Colormap_Properties_and_Atoms">
4794 <title>Standard Colormap Properties and Atoms</title>
4796 <!-- (SN Standard Colormap Properties and Atoms -->
4800 <indexterm><primary>Standard Colormaps</primary></indexterm>
4801 <indexterm><primary>Colormaps</primary><secondary>standard</secondary></indexterm>
4802 Several standard colormaps are available.
4803 Each standard colormap is defined by a property,
4804 and each such property is identified by an atom.
4805 The following list names the atoms and describes the colormap
4806 associated with each one.
4808 <filename class="headerfile"><X11/Xatom.h></filename>
4809 <indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
4810 <indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
4811 <indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
4812 header file contains the definitions for each of the following atoms,
4813 which are prefixed with XA_.
4820 <term>RGB_DEFAULT_MAP</term>
4823 This atom names a property.
4824 The value of the property is an array of
4825 <structname>XStandardColormap</structname>
4827 Each entry in the array describes an <acronym>RGB</acronym> subset of the default color
4828 map for the Visual specified by visual_id.
4831 Some applications only need a few <acronym>RGB</acronym> colors and
4832 may be able to allocate them from the system default colormap.
4833 This is the ideal situation because the fewer colormaps that are
4834 active in the system the more applications are displayed
4835 with correct colors at all times.
4838 A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays
4839 is 6 reds, 6 greens, and 6 blues.
4840 This gives 216 uniformly distributed colors
4841 (6 intensities of 36 different hues) and still leaves 40 elements
4842 of a 256-element colormap available for special-purpose colors
4843 for text, borders, and so on.
4848 <term>RGB_BEST_MAP</term>
4851 This atom names a property. The value of the property is an
4852 <structname>XStandardColormap</structname>.
4855 The property defines the best <acronym>RGB</acronym> colormap available on
4857 (Of course, this is a subjective evaluation.)
4858 Many image processing and three-dimensional applications need to
4859 use all available colormap cells and to distribute as many
4860 perceptually distinct colors as possible over those cells.
4861 This implies that there may be more green values available than
4862 red, as well as more green or red than blue.
4866 <symbol>PseudoColor</symbol>
4868 RGB_BEST_MAP is likely to be a 3/3/2 allocation.
4870 <symbol>DirectColor</symbol>
4872 RGB_BEST_MAP is normally an 8/8/8 allocation.
4877 <term>RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP</term>
4880 These atoms name properties.
4881 The value of each property is an
4882 <structname>XStandardColormap</structname>.
4885 The properties define all-red, all-green, and all-blue
4886 colormaps, respectively.
4887 These maps are used by applications that want to make color-separated
4889 For example, a user might generate a full-color image
4890 on an 8-plane display both by rendering an image three times
4891 (once with high color resolution in red, once with green,
4892 and once with blue) and by multiply exposing a single frame in a camera.
4897 <term>RGB_GRAY_MAP</term>
4900 This atom names a property.
4901 The value of the property is an
4902 <structname>XStandardColormap</structname>.
4905 The property describes the best
4906 <symbol>GrayScale</symbol>
4907 colormap available on the screen.
4908 As previously mentioned,
4909 only the colormap, red_max, red_mult, and base_pixel members of the
4910 <structname>XStandardColormap</structname>
4911 structure are used for
4912 <symbol>GrayScale</symbol>
4921 <sect2 id="Setting_and_Obtaining_Standard_Colormaps">
4922 <title>Setting and Obtaining Standard Colormaps</title>
4924 <!-- (SN Setting and Obtaining Standard Colormaps -->
4928 Xlib provides functions that you can use to set and obtain an
4929 <structname>XStandardColormap</structname>
4936 <structname>XStandardColormap</structname>
4938 <xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>.
4940 <indexterm significance="preferred"><primary>XSetRGBColormaps</primary></indexterm>
4942 <funcsynopsis id='XSetRGBColormaps'>
4944 <funcdef>void <function>XSetRGBColormaps</function></funcdef>
4945 <paramdef>Display<parameter> *display</parameter></paramdef>
4946 <paramdef>Window<parameter> w</parameter></paramdef>
4947 <paramdef>XStandardColormap<parameter> *std_colormap</parameter></paramdef>
4948 <paramdef>int<parameter> count</parameter></paramdef>
4949 <paramdef>Atom<parameter> property</parameter></paramdef>
4956 <emphasis remap='I'>display</emphasis>
4960 Specifies the connection to the X server.
4966 <emphasis remap='I'>w</emphasis>
4970 Specifies the window.
4976 <emphasis remap='I'>std_colormap</emphasis>
4981 <structname>XStandardColormap</structname>
4982 structure to be used.
4983 <!-- .ds Cn colormaps -->
4989 <emphasis remap='I'>count</emphasis>
4993 Specifies the number of (Cn.
4999 <emphasis remap='I'>property</emphasis>
5003 Specifies the property name.
5012 <xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>
5013 function replaces the <acronym>RGB</acronym> colormap definition in the specified property
5014 on the named window.
5015 If the property does not already exist,
5016 <xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>
5017 sets the <acronym>RGB</acronym> colormap definition in the specified property
5018 on the named window.
5019 The property is stored with a type of RGB_COLOR_MAP and a format of 32.
5020 Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>
5021 restriction that only RGB_DEFAULT_MAP contain more than one definition.
5026 <xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>
5027 function usually is only used by window or session managers.
5028 To create a standard colormap,
5029 follow this procedure:
5034 Open a new connection to the same server.
5044 See if the property is on the property list of the root window for the screen.
5049 If the desired property is not present:
5055 Create a colormap (unless you are using the default colormap of the screen).
5060 Determine the color characteristics of the visual.
5065 Allocate cells in the colormap (or create it with
5066 <symbol>AllocAll</symbol>).
5072 <xref linkend='XStoreColors' xrefstyle='select: title'/>
5073 to store appropriate color values in the colormap.
5078 Fill in the descriptive members in the
5079 <structname>XStandardColormap</structname>
5085 Attach the property to the root window.
5091 <xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>
5092 to make the resource permanent.
5104 <xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>
5106 <errorname>BadAlloc</errorname>,
5107 <errorname>BadAtom</errorname>,
5109 <errorname>BadWindow</errorname>
5116 <structname>XStandardColormap</structname>
5117 structure associated with the specified property, use
5118 <xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>.
5120 <indexterm significance="preferred"><primary>XGetRGBColormaps</primary></indexterm>
5122 <funcsynopsis id='XGetRGBColormaps'>
5124 <funcdef>Status <function>XGetRGBColormaps</function></funcdef>
5125 <paramdef>Display<parameter> *display</parameter></paramdef>
5126 <paramdef>Window<parameter> w</parameter></paramdef>
5127 <paramdef>XStandardColormap<parameter> **std_colormap_return</parameter></paramdef>
5128 <paramdef>int<parameter> *count_return</parameter></paramdef>
5129 <paramdef>Atom<parameter> property</parameter></paramdef>
5136 <emphasis remap='I'>display</emphasis>
5140 Specifies the connection to the X server.
5146 <emphasis remap='I'>w</emphasis>
5150 Specifies the window.
5156 <emphasis remap='I'>std_colormap_return</emphasis>
5161 <structname>XStandardColormap</structname>
5163 <!-- .ds Cn colormaps -->
5169 <emphasis remap='I'>count_return</emphasis>
5173 Returns the number of (Cn.
5179 <emphasis remap='I'>property</emphasis>
5183 Specifies the property name.
5192 <xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
5193 function returns the <acronym>RGB</acronym> colormap definitions stored
5194 in the specified property on the named window.
5195 If the property exists, is of type RGB_COLOR_MAP, is of format 32,
5196 and is long enough to contain a colormap definition,
5197 <xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
5198 allocates and fills in space for the returned colormaps
5199 and returns a nonzero status.
5200 If the visualid is not present,
5201 <xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
5202 assumes the default visual for the screen on which the window is located;
5203 if the killid is not present,
5204 <symbol>None</symbol>
5205 is assumed, which indicates that the resources cannot be released.
5207 none of the fields are set, and
5208 <xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
5209 returns a zero status.
5210 Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>
5211 restriction that only RGB_DEFAULT_MAP contain more than one definition.
5215 <xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
5217 <errorname>BadAtom</errorname>
5219 <errorname>BadWindow</errorname>