= FvwmAuto(1)

:doctype: manpage
:mantitle: FvwmAuto
:manname: FvwmAuto
:manmanual: Fvwm Modules
:manvolnum: 1
:page-layout: base

== NAME

FvwmAuto - the fvwm auto-raise module

== SYNOPSIS

**Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus] [EnterCommand [LeaveCommand]]**

_FvwmAuto_ can only be invoked by fvwm. Command line invocation of the
_FvwmAuto_ will not work.

== DESCRIPTION

The _FvwmAuto_ module is most often used to automatically raise focused
windows.

== INVOCATION

The correct syntax is:

....
Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus] [EnterCommand [LeaveCommand]]

AddToMenu Modules
+ "Auto Raise (300 ms)"  Module FvwmAuto 300
+ "Auto Raise/Lower"     Module FvwmAuto 300 "Silent Raise" "Silent Lower"
....

The _Timeout_ argument is required. It specifies how long a window must
retain the keyboard input focus before the command is executed. The
delay is measured in milliseconds, and any integer greater than zero is
valid.

If the literal option _-passid_ is given, the window id of the window
just entered or left is appended to the command that is sent to fvwm.
This can be used with the *WindowId* command of fvwm.

The options _-menter_, _-menterleave_ and _-mfocus_ influence the
actions FvwmAuto reacts to. No more than one of the options can be
chosen. In _-mfocus_ mode, FvwmAuto raises the window that has the
focus. In _-menter_ mode, FvwmAuto raises the window under the pointer
when the pointer enters a window. The _LeaveCommand_ is executed on the
window that was below the pointer before it entered the new window. When
the pointer leaves a window and enters the root window, the
_EnterCommand_ is executed too, but without a window to operate on. In
_-menterleave_ mode, FvwmAuto works just like in _-menter_ mode, but the
_LeaveCommand_ is also executed if the pointer moves out of a window but
does not enter a new window. The latter two modes of operation are
useful with windows that do not accept the focus.

Note: -menterleave mode can interfere with popup windows of some
applications. One example is the zoom menu of Ghostview. Please do not
complain about this to us - it is a bug in Ghostview.

_EnterCommand_ and _LeaveCommand_ are optional. _EnterCommand_ is
executed _Timeout_ milliseconds after a window gets the input focus,
_LeaveCommand_ is executed _Timeout_ milliseconds after the window has
lost focus. Note that you always should use the 'Silent' keyword before
the command itself. FvwmAuto prepends "Silent " to the command string on
its own if yor forget this. Without this prefix fvwm would ask you for a
window to act on if the window has died before the command sent by
FvwmAuto has been processed by fvwm. This can for example happen with
popup menus.

"Silent Raise" is the default for _EnterCommand_, but any fvwm function
is allowed. I would not use "Close" or "Destroy" with a low timeout,
though. The _LeaveCommand_ can be handy for a tidy desktop. Experiment
with:

....
Module FvwmAuto 0 Nop "Silent Lower"
Module FvwmAuto 0 Nop "Silent Iconify"
....

An example for auto raising windows with ClickToFocus:

....
Style * ClickToFocus
FvwmAuto 0 -menter "Silent Raise"
....

An example for auto raising and lowering only some windows:

....
To start FvwmAuto:
FvwmAuto 0 -passid -menter \
"Silent selective_raiselower raise" \
"Silent selective_raiselower lower"
....

And put this in your .fvwm2rc:

....
AddToFunc selective_raiselower
+ I WindowId $1 (FvwmIconMan) $0
+ I WindowId $1 (FvwmButtons) $0
+ IWindowId $1 (xclock) $0
...
....

More complex example (three FvwmAuto's are running):

....
DestroyFunc RestoreIconified
AddToFunc   RestoreIconified
+ I Current (Iconic) Iconify false

DestroyFunc RegisterFocus
AddToFunc   RegisterFocus
+ I Exec date +"%T $n focused" >>/tmp/focus-stats.txt

DestroyFunc RegisterUnfocus
AddToFunc   RegisterUnfocus
+ I Exec date +"%T $n unfocused" >>/tmp/focus-stats.txt

KillModule FvwmAuto
Module FvwmAuto 250 Raise Nop
Module FvwmAuto 800 RestoreIconified Nop
Module FvwmAuto   0 RegisterFocus RegisterUnfocus
....

== NOTES

There is a special Raise/Lower support in FvwmAuto. It was added to
improve Raise/Lower callbacks, since most of FvwmAuto usages is
auto-raising or auto-lowering. This improvement includes locking on
M_RAISE_WINDOW and M_LOWER_WINDOW packets and not raising/lowering
explicitly raised windows. The special Raise/Lower support is enabled
only when either _EnterCommand_ or _LeaveCommand_ contain substring
"Raise" or "Lower". You can use this fact to enable/disable any special
support by renaming these commands, if FvwmAuto does not automatically
do want you expect it to do.

Using _FvwmAuto_ in conjunction with _EdgeCommand_ can be even more
powerful. There is a short example in the _fvwm_ man page.

== AUTHOR

FvwmAuto just appeared one day, nobody knows how.
FvwmAuto was simply rewritten 09/96, nobody knows by whom.
