mdw@git.distorted.org.uk Git - xtoys/blob - xatom.1

   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
 156 The script
 157 .B xshutdown
 158 looks like this.
 159 .PP
 160 .RS
 161 .ft B
 162 .nf
 163 #! /bin/sh
 164 set -e
 165 me=$(basename $0)
 166 case "$(xatom get MDW_SHUTDOWN)" in
 167   READY) ;;
 168   *) xmsg -e -t $me "Nobody's waiting for my signal."; exit 1;;
 169 esac
 170 case "$(xmsg -q -t $me \
 171   "Really shut down this session?" :_Shutdown \~gtk-cancel)" in
 172   _Shutdown)
 173     xatom set MDW_SHUTDOWN SHUTDOWN
 174     ;;
 175 esac
 176 .fi
 177 .RE
 178 .SH BUGS
 179 None currently known.
 180 .SH SEE ALSO
 181 .BR xmsg (1),
 182 .BR XChangeProperty (3x),
 183 .BR XGetWindowProperty (3x),
 184 .BR XDeleteProperty (3x).
 185 .SH AUTHOR
 186 Mark Wooding (mdw@distorted.org.uk).