modules/FvwmCommand/FvwmCommand.1.in

   1 .\" t
   2 .\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
   3 .de EX          \"Begin example
   4 .ne 5
   5 .if n .sp 1
   6 .if t .sp .5
   7 .nf
   8 .in +.25i
   9 ..
  10 .de EE
  11 .fi
  12 .in -.25i
  13 .if n .sp 1
  14 .if t .sp .5
  15 ..
  16 .ta .2i .4i .6i .8i
  17 .TH FvwmCommand 1 "@RELDATELONG@ (@VERSION@)" Fvwm "Fvwm Modules"
  18 .UC
  19 .SH NAME
  20 FvwmCommand \- fvwm command external interface
  21
  22 .SH SYNOPSIS
  23 FvwmCommand [-cmrvw] [-S name] [-i level] [-f name] [-F level] [command...]
  24
  25 .SH DESCRIPTION
  26
  27 FvwmCommand lets you monitor fvwm transaction and issue fvwm command
  28 from a shell command line or scripts.
  29 FvwmCommand takes each argument as a fvwm command. Quotes can be
  30 used to send commands including spaces.
  31 .EX
  32 FvwmCommand 'FvwmPager 0 1'
  33 .EE
  34 .br
  35 .SH INVOCATION
  36 FvwmCommandS should be spawned once by fvwm, either in .fvwm2rc file,
  37 from menu, or from FvwmConsole.
  38 From then on, FvwmCommand
  39 can be called from a shell or script to execute fvwm commands.
  40
  41 From within .fvwm2rc file:
  42 .EX
  43 Module FvwmCommandS
  44
  45     or
  46
  47 AddToFunc StartFunction "I" Module FvwmCommandS
  48 .EE
  49
  50 Then, in script file or from shell:
  51
  52 .EX
  53 FvwmCommand  'popup Utilities'
  54 .EE
  55
  56 .SH OPTIONS
  57 .IP "\fI-c\fR" 0.4i
  58 Informs FvwmCommand to read multiple commands from the standard input
  59 instead of the one command specified in the command line arguments.
  60 This disables \fI-m\fR or \fI-i\fR.
  61 .sp
  62 .EX
  63 (echo "Exec xload"; echo "Beep") | FvwmCommand -c
  64 .EE
  65
  66 .IP "\fI-F <level>\fR" 0.4i
  67 Specifies the level of fvwm window flags FvwmCommand outputs.
  68 .sp
  69 .RS
  70 .IP 0 0.4i
  71 No window flags will be printed.
  72 .RE
  73 .RS
  74 .IP 2 0.4i
  75 Full window flags will be printed if information level, -i
  76 option, is 2 or 3.
  77 .sp
  78 .RE
  79
  80 .IP "\fI-f <name>\fR" 0.4i
  81 Specifies an alternative FIFO set to communicate with a server.
  82 The default FIFO set is /var/tmp/FvwmCommand-${DISPLAY}C, in which
  83 FvwmCommand..C is used to send commands and FvwmCommand..M is to receive
  84 messages. If that path is unusable ${FVWM_USERDIR}/FvwmCommand-${DISPLAY}
  85 will be used instead.
  86 FvwmCommandS must have been invoked with the same <name> as its first argument
  87 prior to FvwmCommand invocation.
  88 Alternatively, option -S can be used. Refer option -S.
  89 This option -f is useful when a dedicated connection is necessary
  90 to run a background job while another connection is kept for
  91 interactive use.
  92
  93 .IP "\fI-i <level>\fR"
  94 Specifies the level of information that FvwmCommand outputs.
  95 .sp
  96 .RS
  97 .IP 0 0.4i
  98 Error messages only.
  99 .EX
 100 FvwmCommand -i0 FvwmBanner
 101 .EE
 102 will show a banner without any output. On the other hand,
 103 .EX
 104 FvwmCommand -i 0 foobar
 105 .EE
 106 will return,
 107 .EX
 108 [fvwm][executeModule]: <<ERROR>> No such module
 109 \'foobar\' in ModulePath '/usr/lib/X11/fvwm'
 110 .EE
 111
 112 Note that Fvwm doesn't return any error messages in
 113 cases like below since 'windowid' itself is a valid command.
 114 .sp
 115 .EX
 116 FvwmCommand -i 0 'windowid foo bar'
 117 .EE
 118 .IP 1
 119 Errors, replies and window configuration information. This is the default.
 120 .EX
 121 FvwmCommand send_windowlist
 122 .EE
 123 Information like below will show up.
 124 .EX
 125
 126 0x02000014 window               FvwmConsole
 127 0x02000014 icon                 FvwmConsole
 128 0x02000014 class                XTerm
 129 0x02000014 resource             FvwmConsole
 130 0x01c00014 window               console
 131 0x01c00014 icon                 console
 132 0x01c00014 class                XTerm
 133 0x01c00014 resource             console
 134 0x01000003 window               Fvwm Pager
 135 0x01000003 icon
 136 0x01000003 class                FvwmModule
 137 0x01000003 resource             FvwmPager
 138 0x00c0002c window               emacs: FvwmCommand.man
 139 0x00c0002c icon                 FvwmCommand.man
 140 0x00c0002c icon file            xemacs.xpm
 141 0x00c0002c class                Emacs
 142 0x00c0002c resource             emacs
 143 end windowlist
 144 .EE
 145 The first column shows the window ID number, which can be used in 'windowid' command.
 146 The second column shows the information types.
 147 The last column shows the information contents.
 148 If no information is returned, add -w <time> or -r option.
 149 This might be needed in heavily loaded systems.
 150 .IP 2
 151 Above and static window information.
 152 .EX
 153 FvwmCommand -i2 'FvwmPager 0 1'
 154 .EE
 155 The below is its output.
 156 .EX
 157
 158 0x03c00003 frame                x 962, y 743, width 187, height 114
 159 0x03c00003 desktop              0
 160 0x03c00003 StartIconic          no
 161 0x03c00003 OnTop                yes
 162 0x03c00003 Sticky               yes
 163 0x03c00003 WindowListSkip       yes
 164 0x03c00003 SuppressIcon         no
 165 0x03c00003 NoiconTitle          no
 166 0x03c00003 Lenience             no
 167 0x03c00003 StickyIcon           no
 168 0x03c00003 CirculateSkipIcon    no
 169 0x03c00003 CirculateSkip        no
 170 0x03c00003 ClickToFocus         no
 171 0x03c00003 SloppyFocus          no
 172 0x03c00003 SkipMapping          no
 173 0x03c00003 Handles              no
 174 0x03c00003 Title                no
 175 0x03c00003 Mapped               no
 176 0x03c00003 Iconified            no
 177 0x03c00003 Transient            no
 178 0x03c00003 Raised               no
 179 0x03c00003 Visible              no
 180 0x03c00003 IconOurs             no
 181 0x03c00003 PixmapOurs           no
 182 0x03c00003 ShapedIcon           no
 183 0x03c00003 Maximized            no
 184 0x03c00003 WmTakeFocus          no
 185 0x03c00003 WmDeleteWindow       yes
 186 0x03c00003 IconMoved            no
 187 0x03c00003 IconUnmapped         no
 188 0x03c00003 MapPending           no
 189 0x03c00003 HintOverride         yes
 190 0x03c00003 MWMButtons           no
 191 0x03c00003 MWMBorders           no
 192 0x03c00003 title height         0
 193 0x03c00003 border width         4
 194 0x03c00003 base size            width 8, height 7
 195 0x03c00003 size increment       width 9, height 9
 196 0x03c00003 min size             width 8, height 7
 197 0x03c00003 max size             width 32767, height 32767
 198 0x03c00003 gravity              SouthEast
 199 0x03c00003 pixel                text 0xffffff, back 0x7f7f7f
 200 0x03c00003 window               Fvwm Pager
 201 0x03c00003 icon                 Fvwm Pager
 202 0x03c00003 class                FvwmModule
 203 0x03c00003 resource             FvwmPager
 204 .EE
 205 .IP 3
 206 All information available.
 207 .EX
 208 FvwmCommand -i3 'Killmodule Fvwm*'
 209 .EE
 210 This will report which windows are closed.
 211 .EX
 212 0x03400003 destroy
 213 0x02400002 destroy
 214 .EE
 215 .RE
 216
 217 .IP "\fI-m\fR"
 218 Monitors fvwm window information transaction. FvwmCommand continuously outputs
 219 information that it receives without exiting.
 220 This option can be used in a
 221 background job often combined with -i3 option in order to control windows
 222 dynamically.
 223 .EX
 224 FvwmCommand -mi3 | grep 'iconify'
 225 .EE
 226 It will report when windows are iconified or de-iconified.
 227 .sp
 228 Note: FvwmCommand does not block buffer its output but many utilities such as
 229 grep or sed use block buffer. The output of the next example will not show up
 230 until either FvwmCommand is terminated or stdout buffer from
 231 grep is filled.
 232 .EX
 233 FvwmCommand -mi3 | grep ' map' |
 234 sed 's/\\(0x[0-9a-f]*\\).*/windowid \\1 move 0 0/'
 235 .EE
 236 Instead, use tools with buffer control such as pty or perl.
 237 The below will iconify new windows when opened.
 238 .EX
 239 Fvwm -mi3 | perl -ne '
 240 $|=1;
 241 print "windowid $1 iconify\\n" if /^(0x\\S+) add/;
 242 \' > ~/\.FvwmCommandC
 243 .EE
 244 .IP "\fI-r\fR"
 245 Waits for a reply before it exits.
 246 FvwmCommand exits if no information or error is returned in a fixed amount of
 247 time period. (Refer option -w.)
 248 The option -r overrides this time limit and wait for at least one message
 249 back.
 250 After the initial message, it will wait for another message for the time
 251 limit.
 252 This option is useful when the system is too loaded to make any prediction
 253 when the system is responding AND the command causes some
 254 message to be sent back.
 255
 256 .IP "\fI-S <name>\fR" 0.4i
 257 Invokes another server, FvwmCommandS, with FIFO set <name>.
 258 .br
 259 If -f option is not used with this option,
 260 the invoking FvwmCommand uses the default FIFO to communicate
 261 the default server to invoke a new server.
 262 .br
 263 If -f option is used with this option,
 264 the invoking FvwmCommand uses the default FIFO to communicate
 265 the default server to invoke a new server. Then, switch the FIFO
 266 set and start communicating the new server.
 267 .br
 268 This option -S is useful when a dedicated connection is necessary
 269 to run a background
 270 job while another connection is kept for interactive use.
 271
 272 If the <name> is a relative path name, that is relative from where
 273 fvwm is running, not from where FvwmCommand is invoked.
 274
 275 .IP "\fI-v\fR"
 276 Returns FvwmCommand version number and exits.
 277
 278 .IP "\fI-w <time>\fR"
 279 Waits for <time> micro seconds for a message.
 280 FvwmCommand exits if no information or error is returned in a fixed amount of
 281 time period unless option -m is used.
 282 The default is 500 ms. This option overrides this default value.
 283
 284 .SH WRAPPER
 285 .sp
 286 .sp
 287 FvwmCommand.sh has bourne shell function definitions
 288 to keep the syntax similar to fvwm configuration file.
 289 This file is to be sourced:
 290 .EX
 291 \&. FvwmCommand.sh
 292 .br
 293 DesktopSize 5x5
 294 .EE
 295 .br
 296 FvwmCommand.pm is for perl in order
 297 to keep the syntax similar to fvwm configuration file.
 298 Commas can be used to separate fvwm commands' arguments.
 299 .EX
 300 use FvwmCommand;
 301 if( $ARGV[0] eq 'home' ) {
 302     Desk 0,0; GotoPage '1 1';
 303 }elsif( $ARGV[0] eq 'jump' ) {
 304     Desk "0 2"; GotoPage 0, 1;
 305 }
 306 .EE
 307 Although arguments in FvwmCommand are not case sensitive as fvwm,
 308 the functions defined in FvwmCommand.sh and FvwmCommand.pl are case sensitive.
 309
 310
 311 .SH ERRORS
 312 If the following error message show up, it is most likely that FvwmCommandS
 313 is not running.
 314 .EX
 315 FvwmCommand error in opening message fifo
 316 --No such file or directory--
 317 .EE
 318 Fvwm modules don't return error messages to fvwm but output on
 319 stderr. These error messages will not be shown as FvwmCommand messages.
 320
 321 FvwmCommand is an interface to send commands to and receive
 322 information from Fvwm2 from processes which are not Fvwm modules.
 323
 324
 325 .SH EXAMPLES
 326   test1.pl      - takes 1 argument  't' to invoke FvwmTalk
 327                                     'td'  to kill FvwmTalk
 328                                     ''  to move windows
 329   test2.sh      - takes 1 argument  'b'  to invoke FvwmButtons
 330                                     'kb' to kill FvwmButtons
 331                                     'r'  to change # of button rows
 332                                     'c'  to change # of button columns
 333   ex-auto.pl    - auto raise small windows. It will keep them visible.
 334   ex-cascade.pl - cascade windows, then move them back.
 335   ex-grpmv.pl   - choose a group of windows to move together.
 336
 337   Above examples are not meant to be practical but to show how it can
 338   be done.
 339
 340
 341
 342   focus-link.pl
 343      This is a user programmable window focus script.
 344      Default behavior is:
 345       1. When a window is opened up, focus the window and move the pointer
 346          to it. The parent window regains focus when a window is closed.
 347          Parenthood is determined when a window is opened. It is the last
 348          focused window with the same X class.
 349       2. #1 would not occur to AcroRead opening window.
 350       3. #1 would not occur when SkipMapping is set and the window is the
 351          only window of its class.
 352       4. For Netscape find dialog window, addition to #1, resize the window
 353          to 300x150 pixels and move it to East edge of the screen.
 354          Download/upload windows will not be focused nor be in focus link
 355          list.
 356       5. Move appletviewer to NorthWest corner.
 357       6. Xterm won't focus back to its parent after closed.
 358       7. When a window is de-iconified, focus it and move the pointer.
 359
 360   focus-Netscape.pl
 361       Focuses pop-up windows, such as 'open URL' or 'find' whenever
 362       opened up. This let the user to type in immediately without
 363       moving mouse. This script also moves 'download' window to the
 364       right edge to keep it visible. If this is invoked from
 365       .fvwm2rc, use as:
 366
 367           AddToFunc "StartFunction" "I" Module  FvwmCommandS
 368           + "I" Exec $HOME/scripts/focus-Netscape.pl
 369
 370   push-away.pl <direction> <window name>
 371       Pushes windows away to avoid overlapping. use as:
 372
 373           push-away.pl up 'Fvwm Pager'
 374
 375
 376
 377
 378
 379
 380 .SH SEE ALSO
 381 fvwm
 382
 383 .SH AUTHOR
 384 FvwmCommand is the original work of Toshi Isogai.
 385
 386