.\" t
.\" @(#)FvwmCommand.1	4/6/98
.de EX		\"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.25i
..
.de EE
.fi
.in -.25i
.if n .sp 1
.if t .sp .5
..
.ta .2i .4i .6i .8i
.TH FvwmCommand 1x "May 11 1998"
.UC
.SH NAME
FvwmCommand \- FVWM2 command external interface

.SH SYNOPSIS
FvwmCommand [-mrvw] [-S name] [-i level] [-f name] [-F level] [command...]

.SH DESCRIPTION

FvwmCommand lets you monitor fvwm2 transaction and issue fvwm2 command 
from a shell command line or scripts. 
FvwmCommand takes each argument as a fvwm2 command. Quotes can be 
used to send commands including spaces. 
.EX
FvwmCommand 'FvwmPager 0 1' 
.EE
.br
.SH INVOCATION
FvwmCommandS should be spawned once by fvwm2, either in .fvwm2rc file,
from menu, or from FvwmConsole.
From then on, FvwmCommand
can be called from a shell or script to execute fvwm2 commands.

From within .fvwm2rc file:
.EX 
Module FvwmCommandS

    or

AddToFunc "InitFunction" "I" Module FvwmBanner
+   "I" Module	FvwmPager 0 8
+   "I" Module  FvwmCommandS

AddToFunc "RestartFunction" "I" Module  FvwmCommandS
+	"I" Module	FvwmPager 0 8
.EE

Then, in script file or from shell:

.EX
FvwmCommand  'popup "Utilities"' 
.EE

.SH OPTIONS
.IP "\fI-F <level>\fR" 0.4i
Specifies the level of fvwm2 window flags FvwmCommand outputs.
.sp
.RS
.IP 0 0.4i
No window flags will be printed.
.RE
.RS
.IP 2 0.4i
Full window flags will be printed if information level, -i
option, is 2 or 3.
.sp
.RE

.IP "\fI-f <name>\fR" 0.4i
Specifies an alternative FIFO set to communicate with a server.
The default FIFO set is ~/.FvwmCommand, in which
~/.FvwmCommandC is used to send commands and ~/.FvwmCommandM is to receive
messages.
FvwmCommandS must have been invoked with the same <name> as its first argument
prior to FvwmCommand invocation. 
Alternatively, option -S can be used. Refer option -S.
This option -f is useful when a dedicated connection is necessary 
to run a background job while another connection is kept for 
interactive use.

.IP "\fI-i <level>\fR"
Specifies the level of information that FvwmCommand outputs.
.sp
.RS
.IP 0 0.4i
Error messages only. 
.EX
FvwmCommand -i0 FvwmBanner 
.EE
will show a banner without any output. On the other hand,
.EX
FvwmCommand -i 0 foobar
.EE
will return,
.EX
[FVWM][executeModule]: <<ERROR>> No such module 
\'foobar\' in ModulePath '/usr/lib/X11/fvwm2'
.EE

Note that Fvwm2 doesn't return any error messages in
cases like below since 'windowid' itself is a valid command.
.sp
.EX
FvwmCommand -i 0 'windowid foo bar'
.EE
.IP 1
Errors and window configuration information. This is the default.
.EX
FvwmCommand send_windowlist
.EE
Information like below will show up.
.EX

0x02000014 window               FvwmConsole
0x02000014 icon                 FvwmConsole
0x02000014 class                XTerm
0x02000014 resource             FvwmConsole
0x01c00014 window               console
0x01c00014 icon                 console
0x01c00014 class                XTerm
0x01c00014 resource             console
0x01000003 window               Fvwm Pager
0x01000003 icon                 
0x01000003 class                FvwmModule
0x01000003 resource             FvwmPager
0x00c0002c window               emacs: FvwmCommand.man
0x00c0002c icon                 FvwmCommand.man
0x00c0002c icon file            xemacs.xpm
0x00c0002c class                Emacs
0x00c0002c resource             emacs
end windowlist      
.EE
The first column shows the window ID number, which can be used in 'windowid' command.
The second column shows the information types. 
The last column shows the information contents.
If no information is returned, add -w <time> or -r option. 
This might be needed in heavily loaded systems.
.IP 2
Above and static window information.
.EX
FvwmCommand -i2 'FvwmPager 0 1' 
.EE
The below is its output.
.EX

0x03c00003 frame                x 962, y 743, width 187, height 114
0x03c00003 desktop              0
0x03c00003 StartIconic          no
0x03c00003 OnTop                yes
0x03c00003 Sticky               yes
0x03c00003 WindowListSkip       yes
0x03c00003 SuppressIcon         no
0x03c00003 NoiconTitle          no
0x03c00003 Lenience             no
0x03c00003 StickyIcon           no
0x03c00003 CirculateSkipIcon    no
0x03c00003 CirculateSkip        no
0x03c00003 ClickToFocus         no
0x03c00003 SloppyFocus          no
0x03c00003 SkipMapping          no
0x03c00003 Handles              no
0x03c00003 Title                no
0x03c00003 Mapped               no
0x03c00003 Iconified            no
0x03c00003 Transient            no
0x03c00003 Raised               no
0x03c00003 Visible              no
0x03c00003 IconOurs             no
0x03c00003 PixmapOurs           no
0x03c00003 ShapedIcon           no
0x03c00003 Maximized            no
0x03c00003 WmTakeFocus          no
0x03c00003 WmDeleteWindow       yes
0x03c00003 IconMoved            no
0x03c00003 IconUnmapped         no
0x03c00003 MapPending           no
0x03c00003 HintOverride         yes
0x03c00003 MWMButtons           no
0x03c00003 MWMBorders           no
0x03c00003 title height         0
0x03c00003 border width         4
0x03c00003 base size            width 8, height 7
0x03c00003 size increment       width 9, height 9
0x03c00003 min size             width 8, height 7
0x03c00003 max size             width 32767, height 32767
0x03c00003 gravity              SouthEast
0x03c00003 pixel                text 0xffffff, back 0x7f7f7f
0x03c00003 window               Fvwm Pager
0x03c00003 icon                 Fvwm Pager
0x03c00003 class                FvwmModule
0x03c00003 resource             FvwmPager
.EE
.IP 3
All information available.
.EX
FvwmCommand -i3 'Killmodule Fvwm*'    
.EE
This will report which windows are closed.
.EX
0x03400003 destroy
0x02400002 destroy
.EE
.RE

.IP "\fI-m\fR"
Monitors fvwm2 window information transaction. FvwmCommand continuously outputs
information that it receives without exiting. 
This option can be used in a
background job often combined with -i3 option in order to control windows
dynamically.
.EX
FvwmCommand -mi3 | grep 'iconify'
.EE
It will report when windows are iconified or deiconified.
.sp
Note: FvwmCommand does not block buffer its output but many utilities such as 
grep or sed use block buffer. The output of the next example will not show up
until either FvwmCommand is terminated or stdout buffer from
grep is filled.
.EX
FvwmCommand -mi3 | grep ' map' | 
sed 's/\(0x[0-9a-f]*\).*/windowid \1 move 0 0/'
.EE
Instead, use tools with buffer control such as pty or perl. 
The below will iconify new windows when opened.
.EX
Fvwm -mi3 | perl -ne '
$|=1; 
print "windowid $1 iconify\\n" if /^(0x\\S+) add/;
\' > ~/\.FvwmCommandC
.EE
.IP "\fI-r\fR"
Waits for a reply before it exits. 
FvwmCommand exits if no information or error is returned in a fixed amount of 
time period. (Refer option -w.)
The option -r overrides this time limit and wait for at least one message
back. 
After the initial message, it will wait for another message for the time
limit.
This option is useful when the system is too loaded to make any predition
when the system is responding AND the command causes some
message to be sent back.

.IP "\fI-S <name>\fR" 0.4i
Invokes another server, FvwmCommandS, with FIFO set <name>.
.br
If -f option is not used with this option,
the invoking FvwmCommand uses the default FIFO to communicate 
the default server to invoke a new server.
.br
If -f option is used with this option,
the invoking FvwmCommand uses the default FIFO to communicate 
the default server to invoke a new server. Then, switch the FIFO
set and start communicating the new server.
.br
This option -S is useful when a dedicated connection is necessary 
to run a background
job while another connection is kept for interactive use.

If the <name> is a relative path name, that is relative from where
fvwm2 is running, not from where FvwmCommand is invoked.

.IP "\fI-v\fR"
Returns FvwmCommand version number and exits.

.IP "\fI-w <time>\fR"
Waits for <time> micro seconds for a message.
FvwmCommand exits if no information or error is returned in a fixed amount of 
time period unless option -m is used. 
The default is 500 ms. This option overrides this default value.

.SH WRAPPER
.sp
.sp
FvwmCommand.sh has bourne shell function definitions
to keep the syntax similar to fvwm2 configuration file. 
This file is to be sourced:
.EX
\&. FvwmCommand.sh
.br
DesktopSize 5x5
.EE
.br
FvwmCommand.pm is for perl in order 
to keep the syntax similar to fvwm2 configuration file. 
Commas can be used to separate Fvwm2 commands' arguments. 
.EX
use FvwmCommand;
if( $ARGV[0] eq 'home' ) { 
    Desk 0,0; GotoPage '1 1'; 
}elsif( $ARGV[0] eq 'jump' ) { 
    Desk "0 2"; GotoPage 0, 1; 
}
.EE
Although arguments in FvwmCommand are not case sensitive as fvwm2,
the functions defined in FvwmCommand.sh and FvwmCommand.pl are case sensitive.


.SH ERRORS
If the following error message show up, it is most likely that FvwmCommandS
is not running.
.EX
FvwmCommand error in opening message fifo
--No such file or directory--
.EE
Fvwm2 modules don't return error messages to fvwm2 but output on 
stderr. These error messages will not be shown as FvwmCommand messages.

.SH SEE ALSO
fvwm2

.SH AUTHOR
Toshi Isogai  isogai@ucsub.colorado.edu