Commit | Line | Data |
---|---|---|
01a2fe8e MW |
1 | .\" -*-nroff-*- |
2 | .TH xatom 1 "13 September 2007" "Straylight/Edgeware" "xtoys" | |
3 | .SH NAME | |
4 | xatom \- manipulate properties on X windows | |
5 | .SH SYNOPSIS | |
6 | .B xatom | |
7 | .RB [ \- d | |
8 | .IR display ] | |
9 | .RB [ \- w | |
10 | .IR window ] | |
11 | .I command | |
12 | .PP | |
13 | where | |
14 | .I command | |
15 | is one of: | |
16 | .PP | |
17 | .B help | |
18 | .RI [ command ...] | |
19 | .br | |
20 | .B get | |
21 | .I property | |
22 | .br | |
23 | .B set | |
24 | .I property | |
25 | .I value | |
26 | .br | |
27 | .B delete | |
28 | .I property | |
29 | .br | |
30 | .B wait | |
31 | .I property | |
32 | .RI [ value ...] | |
33 | .SH DESCRIPTION | |
34 | The | |
35 | .B xatom | |
36 | program manipulates properties of a simple kind on X windows. It deals | |
37 | only with those properties whose value is a single X atom. It is | |
38 | capable of setting, reading, and deleting properties, and also waiting | |
39 | until a particular property is set, maybe to one of a number of given | |
40 | values. | |
41 | .PP | |
42 | The program provides a number of subcommands, by which the various | |
43 | operations may be carried out. | |
44 | .SS "Global options" | |
45 | Before the command name, | |
46 | .I "global options" | |
47 | may be given. The following global options are supported. | |
48 | .TP | |
49 | .BR "\-h, \-\-help " [\fIcommand\fP...] | |
50 | Writes a brief summary of | |
51 | .BR xatom 's | |
52 | various operations to standard output, and returns a successful exit | |
53 | status. With command names, gives help on those commands. | |
54 | .TP | |
55 | .B "\-v, \-\-version" | |
56 | Writes the program's version number to standard output, and returns a | |
57 | successful exit status. | |
58 | .TP | |
59 | .B "\-u, \-\-usage" | |
60 | Writes a very terse command line summary to standard output, and returns | |
61 | a successful exit status. | |
62 | .TP | |
63 | .BI "\-d, \-\-display=" display | |
64 | Connect to the X server named by | |
65 | .I display | |
66 | rather than the default, which is to consult the | |
67 | .B DISPLAY | |
68 | environment variable. | |
69 | .TP | |
70 | .BI "\-w, \-\-window=" window | |
71 | Manipulate properties on the window whose ID is | |
72 | .I window | |
73 | rather than the default, which is to use the root window of the screen | |
74 | named by | |
75 | .IR display . | |
76 | If | |
77 | .I window | |
78 | is the string | |
79 | .B choose | |
80 | then the window can be chosen interactively: the | |
81 | .B xatom | |
82 | program will grab the pointer and wait for a button-1 click over a | |
83 | window. A button-3 click causes | |
84 | .B xatom | |
85 | to quit (and return an unsuccessful exit status). | |
86 | .SH "COMMAND REFERENCE" | |
87 | .SS "help" | |
88 | The | |
89 | .B help | |
90 | command behaves exactly as the | |
91 | .B \-\-help | |
92 | option. With no arguments, it shows an overview of | |
93 | .BR xatom 's | |
94 | options; with arguments, it described the named subcommands. | |
95 | .SS "get" | |
96 | The | |
97 | .B get | |
98 | command retrieves the named | |
99 | .I property | |
100 | from the specified window, and reports its value on standard output. | |
101 | .PP | |
102 | If the property wasn't found, or its value wasn't a single atom, nothing | |
103 | is written, but a successful exit status is still returned. If a value | |
104 | was found, it is written and followed by a newline: therefore a client | |
105 | can distinguish an empty value from no value at all. | |
106 | .SS "set" | |
107 | The | |
108 | .B set | |
109 | command sets the named | |
110 | .I property | |
111 | to have the specified | |
112 | .IR value , | |
113 | overwriting any existing value. | |
114 | .SS "delete" | |
115 | The | |
116 | .B delete | |
117 | command removes the named | |
118 | .I property | |
119 | from the window. If no such property exists, nothing happens. | |
120 | .SS "wait" | |
121 | The | |
122 | .B wait | |
123 | command waits on a particular | |
124 | .IR property . | |
125 | If any | |
126 | .IR value s | |
127 | are specified, then the command waits until the property's value matches | |
128 | one of the specified | |
129 | .IR value s: | |
130 | if it already matches one of them then the command won't wait. | |
131 | If no | |
132 | .IR value s | |
133 | are specified, then the command waits until the property is set to any | |
134 | value; again, if it is already set, the command returns immediately. | |
135 | .PP | |
136 | If exactly one | |
137 | .I value | |
138 | is given, the command produces no output; otherwise, it writes the new | |
139 | value of the property, as for the | |
140 | .B get | |
141 | command. | |
142 | .SH EXAMPLE | |
143 | The author uses this command at the end of his | |
144 | .BR .xinitrc | |
145 | file, to control the duration of his X session. Specifically, he uses | |
146 | the code | |
147 | .PP | |
148 | .RS | |
149 | .ft B | |
150 | .nf | |
151 | xatom set MDW_SHUTDOWN READY | |
152 | xatom wait MDW_SHUTDOWN SHUTDOWN | |
153 | xatom delete MDW_SHUTDOWN | |
154 | .fi | |
155 | .RE | |
0f5dc4fa | 156 | .PP |
01a2fe8e MW |
157 | The script |
158 | .B xshutdown | |
159 | looks like this. | |
160 | .PP | |
161 | .RS | |
162 | .ft B | |
163 | .nf | |
164 | #! /bin/sh | |
165 | set -e | |
166 | me=$(basename $0) | |
167 | case "$(xatom get MDW_SHUTDOWN)" in | |
168 | READY) ;; | |
169 | *) xmsg -e -t $me "Nobody's waiting for my signal."; exit 1;; | |
170 | esac | |
171 | case "$(xmsg -q -t $me \ | |
172 | "Really shut down this session?" :_Shutdown \~gtk-cancel)" in | |
173 | _Shutdown) | |
174 | xatom set MDW_SHUTDOWN SHUTDOWN | |
175 | ;; | |
176 | esac | |
177 | .fi | |
178 | .RE | |
179 | .SH BUGS | |
180 | None currently known. | |
181 | .SH SEE ALSO | |
182 | .BR xmsg (1), | |
183 | .BR XChangeProperty (3x), | |
184 | .BR XGetWindowProperty (3x), | |
185 | .BR XDeleteProperty (3x). | |
186 | .SH AUTHOR | |
187 | Mark Wooding (mdw@distorted.org.uk). |