= FvwmMFL(1)

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

== NAME

FvwmMFL - the Fvwm3 front-loader module

== SYNOPSIS

_FvwmMFL_ can only be invoked by Fvwm3. Command line invocation of the
_FvwmMFL_ will not work.

This module has no command-line options.

== DESCRIPTION

The _FvwmMFL_ module provides access to Fvwm events over a unix-domain
socket. This module is intended to provide externally-written programs
(clients) the ability to receive information from Fvwm and to perform an
action on that event.

The information from Fvwm3 is in the form of JSON packets. Each JSON
packet has different fields, depending on the type requested.

== COMMUNICATION

The default unix-domain socket for _FvwmMFL_ is
*$TMPDIR/fvwmmfl/fvwm_mfl_$DISPLAY.sock*.

The path for where *fvwm_mfl_$DISPLAY.sock* is created can be changed by
setting the *FVWMMFL_SOCKET_PATH* environment variable.  _FvwmMFL_ will create
this if it does not exist, and set relevant permissions.

== REGISTERING INTEREST

Commands can be sent to _FvwmMFL_ to control which information is sent
the client. The _set_ command is used for this. The table below shows
which events can be subscribed to.

[cols="<,<",]
|===
|_Event_ |_Description_
|new_window |Fired when a new window is mapped and visible.
|map |Fired when a window is mapped.
|configure_window |Fired when a window is moved or resized.
|destroy_window |Fired when a window is closed.
|new_page |Fired when a new page is switched to.
|new_desk |Fired when a new desk is switched to.
|raise_window |Fired when a window is raised (or changes layer).
|lower_window |Fired when a window is lowered (or changed layer).
|focus_change |Fired when a window loses/gains focus.
|enter_window |Fired when a window has the pointer moved into it.
|leave_Window |Fired when a window has pointer moved out of it.
|window_shade |Fired when a window is shaded.
|window_unshade |Fired when a window is unshaded.
|window_name |Fired when the window name changes.
|visible_name |Fired when the visible window name changes.
|res_class |Fired when the class of the window is set.
|res_name |Fired when the resource of the window is set.
|iconify |Fired when a window is iconified.
|deiconify |Fired when a window is deiconified.
|icon_name |Fired when the icon name changes.
|visible_icon_name |Fired when the icon's visible name changes.
|icon_file |Fired when the path to the icon changes.
|icon_location |Fired when the icon location changes.
|restack |Fired when the window stacking order changes.
|echo |Fired when Fvwm receives an Echo command.
|===

For example, to register an interest in _new_window_ and _focus_change_,
the following commands would be set via the socket:

....
set new_window
set focus_change
....

To remove interest in an event, use the _unset_ command:

....
unset focus_change
....

== JSON FORMAT

Each packet sent to a client is in plain JSON. The information contained
in each packet varies depending on the event.

TODO: document each JSON structure.

== EXAMPLE

The following example shows how to monitor for _focus_change_ events at
the shell, printing the JSON returned:

....
  echo set focus_change | nc -U /tmp/fvwm_mfl.sock 2>&1 | jq --unbuffered
....

Outputs:

....
{ "focus_change": { "window": "0x5400022", "type": 0, "hilight": {
"text_colour": 16777215, "bg_colour": 32767 } } }
....

== AUTHORS

This module first appeared in 2020.
