<html>
<head>
<title>The Official FVWM Homepage - Fvwm-to-Module Communication</title>
</head>
<body BACKGROUND="black-stone1.jpg"
bgcolor="#000000" text="#ffffff"
link="#FFFF88" vlink="#EEDDDD" alink="#ff0000">
<center>
<h1><font color="pink">The Official FVWM Homepage - Fvwm-to-Module Communication</font></h1>
</center>
<H2> <font color="turquoise">When communication takes place</font></h2>
Fvwm
can send messages to the modules in either a broadcast mode, or a
module specific mode. Certain messages regarding important window or
desktop manipulations are broadcast to all modules, whether they
want it or not. Modules are able to request information about current windows
from fvwm, via the Send_WindowList built-in. When invoked this way,
only requesting module receives the data.
<H2> <font color="turquoise">Communication packet format</font></h2>
Packets from fvwm to modules conform to a standard format, so modules
which are not interested in broadcast messages can easily ignore them.
A header consisting of 4 unsigned long integers, followed by a body of
a variable length make up a packet. The header always begins with
0xffffffff. This is provided to help modules re-synchronize to the
data stream if necessary. The next entry describes the packet type.
Existing packet types are listed in the file fvwm/module.h:
<font color="yellow"><PRE>
#define <A href="#M_NEW_PAGE">M_NEW_PAGE</A> (1)
#define <A href="#M_NEW_DESK">M_NEW_DESK</A> (1<<1)
#define <A href="#M_ADD_WINDOW">M_ADD_WINDOW</A> (1<<2)
#define <A href="#M_RAISE_WINDOW">M_RAISE_WINDOW</A> (1<<3)
#define <A href="#M_LOWER_WINDOW">M_LOWER_WINDOW</A> (1<<4)
#define <A href="#M_CONFIGURE_WINDOW">M_CONFIGURE_WINDOW</A> (1<<5)
#define <A href="#M_FOCUS_CHANGE">M_FOCUS_CHANGE</A> (1<<6)
#define <A href="#M_DESTROY_WINDOW">M_DESTROY_WINDOW</A> (1<<7)
#define <A href="#M_ICONIFY">M_ICONIFY</A> (1<<8)
#define <A href="#M_DEICONIFY">M_DEICONIFY</A> (1<<9)
#define <A href="#M_WINDOW_NAME">M_WINDOW_NAME</A> (1<<10)
#define <A href="#M_ICON_NAME">M_ICON_NAME</A> (1<<11)
#define <A href="#M_RES_CLASS">M_RES_CLASS</A> (1<<12)
#define <A href="#M_RES_NAME">M_RES_NAME</A> (1<<13)
#define <A href="#M_END_WINDOWLIST">M_END_WINDOWLIST</A> (1<<14)
#define <A href="#M_ICON_LOCATION">M_ICON_LOCATION</A> (1<<15)
#define <A href="#M_MAP">M_MAP</A> (1<<16)
#define <A href="#M_ERROR">M_ERROR</A> (1<<17)
#define <A href="#M_CONFIG_INFO">M_CONFIG_INFO</A> (1<<18)
#define <A href="#M_END_CONFIG_INFO">M_END_CONFIG_INFO</A> (1<<19)
#define <A href="#M_ICON_FILE">M_ICON_FILE</A> (1<<20)
#define <A href="#M_DEFAULTICON">M_DEFAULTICON</A> (1<<21)
#define <A href="#M_STRING">M_STRING</A> (1<<22)
#define <A href="#M_MINI_ICON">M_MINI_ICON</A> (1<<23)
#define <A href="#M_WINDOWSHADE">M_WINDOWSHADE</A> (1<<24)
#define <A href="#M_DEWINDOWSHADE">M_DEWINDOWSHADE</A> (1<<25)
#define <A href="#M_LOCKONSEND">M_LOCKONSEND</A> (1<<26)
#define <A href="#M_SENDCONFIG">M_SENDCONFIG</A> (1<<27)
</PRE></font>
<P>
Additional packet types will be defined in the future. The third entry
in the header tells the total length of the packet, in unsigned longs,
including the header. The fourth entry is the last time stamp received
from the X server, which is expressed in milliseconds.
<P>
The body information is packet specific, as described below.
<H2><A NAME="M_NEW_PAGE">M_NEW_PAGE</A></H2>
<P>
These packets contain 5 integers. The first two are the x and y
coordinates of the upper left corner of the current viewport on the
virtual desktop. The third value is the number of the current desktop.
The fourth and fifth values are the maximum allowed values of the
coordinates of the upper-left hand corner of the viewport.
<P>
<H2><A NAME="M_NEW_DESK">M_NEW_DESK</A></H2>
<P>
The body of this packet consists of a single long integer, whose value
is the number of the currently active desktop. This packet is
transmitted whenever the desktop number is changed.
<P>
<H2><A NAME="M_ADD_WINDOW">M_ADD_WINDOW</A>, and <A NAME="M_CONFIGURE_WINDOW">M_CONFIGURE_WINDOW</A></H2>
<P>
These packets contain 24 values. The first 3 identify the window, and
the next twelve identify the location and size, as described in the
table below. Configure packets will be generated when the
viewport on the current desktop changes, or when the size or location
of the window is changed. The flags field is an bitwise OR of the
flags defined in fvwm.h.
<P>
<P><DIV ALIGN=CENTER><P ALIGN=CENTER><TABLE COLS=2 BORDER FRAME=BOX RULES=GROUPS>
<COLGROUP><COL ALIGN=LEFT><COLGROUP><COL ALIGN=LEFT>
<TBODY>
<TR><TD VALIGN=BASELINE ALIGN=CENTER NOWRAP COLSPAN=2>
Format for Add and Configure Window Packets</TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>Byte </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>Significance </TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>0 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 0xffffffff - Start of packet </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
1 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> packet type </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
2 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> length of packet, including header, expressed in long integers
</TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>3 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> ID of the application's top level window </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
4 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> ID of the Fvwm frame window </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
5 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Pointer to the Fvwm database entry </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
6 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> X location of the window's frame </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
7 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Y location of the window's frame</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
8 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Width of the window's frame (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
9 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Height of the window's frame (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
10 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Desktop number</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
11 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Windows flags field</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
12 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Title Height (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
13 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Border Width (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
14 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Base Width (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
15 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Base Height (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
16 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Resize Width Increment(pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
17 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Resize Height Increment (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
18 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Minimum Width (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
19 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Minimum Height (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
20 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Maximum Width Increment(pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
21 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Maximum Height Increment (pixels) </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
22 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Icon Label Window ID, or 0</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
23 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Icon Pixmap Window ID, or 0</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
24 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Window Gravity</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> \
25 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Pixel value of the text color </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
26 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Pixel value of the window border color </TD></TR>
</TBODY>
</TABLE>
</P></DIV><P><H2>
<A NAME="M_LOWER_WINDOW">M_LOWER_WINDOW</A>,
<A NAME="M_RAISE_WINDOW">M_RAISE_WINDOW</A>, and
<A NAME="M_DESTROY_WINDOW">M_DESTROY_WINDOW</A>
</H2>
<P>
These packets contain 3 values, all of the same size as an unsigned
long. The first value is the ID of the affected application's top level
window, the next is the ID of the Fvwm frame window, and the final
value is the pointer to Fvwm's internal database entry for that
window. Although the pointer itself is of no use to a module, it can
be used as a reference number when referring to the window.
<P>
<P><DIV ALIGN=CENTER><P ALIGN=CENTER><TABLE COLS=2 BORDER FRAME=BOX RULES=GROUPS>
<COLGROUP><COL ALIGN=LEFT><COLGROUP><COL ALIGN=LEFT>
<TBODY>
<TR><TD VALIGN=BASELINE ALIGN=CENTER NOWRAP COLSPAN=2>
Format for Lower, Raise, and Focus Change Packets</TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>Byte </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>Significance </TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>0 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 0xffffffff - Start of packet </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
1 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> packet type </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
2 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> length of packet, including header, expressed in long integers
</TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>3 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> ID of the application's top level window </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
4 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> ID of the Fvwm frame window </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
5 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Pointer to the Fvwm database entry </TD></TR>
</TBODY>
</TABLE>
</P></DIV><P><H2><A NAME="M_FOCUS_CHANGE">M_FOCUS_CHANGE</A></H2>
<P>
These packets contain 5 values, all of the same size as an unsigned
long. The first value is the ID of the affected application's (the
application which now has the input focus) top level
window, the next is the ID of the Fvwm frame window, and the final
value is the pointer to Fvwm's internal database entry for that
window. Although the pointer itself is of no use to a module, it can
be used as a reference number when referring to the window. The fourth
and fifth values are the text focus color's pixel value and the window
border's focus color's pixel value. In the
event that the window which now has the focus is not a window which
fvwm recognizes, only the ID of the affected application's top level
window is passed. Zeros are passed for the other values.
<P>
<H2>
<A NAME="M_ICONIFY">M_ICONIFY</A> and
<A NAME="M_ICON_LOCATION">M_ICON_LOCATION</A>
</H2>
<P>
These packets contain up to 11 values. The first 3 are the usual identifiers,
and the next four describe the location and size of the window being iconified,
as described in the table.
Under the conditons where an actual builtin icon is created or destroyed,
the next 4 values describe the location and size of the icon.
Note that M_ICONIFY packets are sent
whenever a window is first iconified, or when the icon window is changed
via the XA_WM_HINTS in a property notify event. An M_ICON_LOCATION
packet will be sent when the icon is moved.
In addition, if a window which has transients is
iconified, then an M_ICONIFY packet is sent for each transient
window, with the x, y, width, and height fields set to 0. This packet
will be sent even if the transients were already iconified. Note that
no icons are actually generated for the transients in this case.
<P>
<P><DIV ALIGN=CENTER><P ALIGN=CENTER><TABLE COLS=2 BORDER FRAME=BOX RULES=GROUPS>
<COLGROUP><COL ALIGN=LEFT><COLGROUP><COL ALIGN=LEFT>
<TBODY>
<TR><TD VALIGN=BASELINE ALIGN=CENTER NOWRAP COLSPAN=2>
Format for Iconify and Icon Location Packets</TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>Byte </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>Significance </TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>0 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 0xffffffff - Start of packet </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
1 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> packet type </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
2 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> length of packet, including header, expressed in long integers
</TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>3 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> ID of the application's top level window </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
4 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> ID of the Fvwm frame window </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
5 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Pointer to the Fvwm database entry </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
6 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> X location of the window's frame </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
7 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Y location of the window's frame</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
8 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Width of the window's frame </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
9 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Height of the window's frame </TD></TR>
</TBODY>
</TABLE>
</P></DIV><P><H2><A NAME="M_DEICONIFY">M_DEICONIFY</A></H2>
<P>
These packets contain up to 11 values, starting with the usual window
identifiers. The packet is sent when a window is de-iconified.
Like M_ICONIFY, window and icon location and size are sent except
that icon information comes first followed by window information.
<P>
<H2><A NAME="M_MAP">M_MAP</A></H2>
<P>
These packets contain 3 values, which are the usual window
identifiers. The packets are sent when a window is mapped, if it is
not being deiconified. This is useful to determine when a window is
finally mapped, after being added.
<P>
<H2>
<A NAME="M_WINDOW_NAME">M_WINDOW_NAME</A>,
<A NAME="M_ICON_NAME">M_ICON_NAME</A>,
<A NAME="M_RES_CLASS">M_RES_CLASS</A>,
<A NAME="M_RES_NAME">M_RES_NAME</A>,
</H2>
<P>
These packets contain 3 values, which are the usual window
identifiers, followed by a variable length character string. The
packet size field in the header is expressed in units of unsigned
longs, and the packet is zero-padded until it is the size of an
unsigned long. The RES_CLASS and RES_NAME fields are fields in the
XClass structure for the window. Icon and Window name packets will
will be sent upon window creation or whenever the name is changed. The
RES_CLASS and RES_NAME packets are sent on window creation. All
packets are sent in response to a Send_WindowList request from a module.
<P>
<H2><A NAME="M_END_WINDOWLIST">M_END_WINDOWLIST</A></H2>
<P>
These packets contain no values. This packet is sent to mark the end
of transmission in response to a Send_WindowList request. A module
which request Send_WindowList, and processes all packets received
between the request and the M_END_WINDOWLIST will have a snapshot of
the status of the desktop.
<P>
<H2><A NAME="M_ERROR">M_ERROR</A></H2>
<P>
When fvwm has an error message to report, it is echoed to the modules
in a packet of this type. This packet has 3 values, all zero, followed
by a variable length string which contains the error message.
<P>
<H2><A NAME="M_CONFIG_INFO">M_CONFIG_INFO</A></H2>
<P>
Fvwm records all configuration commands that it encounters which
begins with the character ``*''. When the built-in command
``Send_ConfigInfo'' is invoked by a module, this entire list is
transmitted to the module in packets (one line per packet) of this
type. The packet consists of three zeros, followed by a variable
length character string. In addition, the PixmapPath, IconPath, and
ClickTime are sent to the module.
<P>
Note that all the module configuration commands are sent. Each
module has to check the configuration commands to see if
it is a command for that specific module. This is actually
a feature. This way one module can learn about all other
modules configurations. Also fvwm2 doesn't currently know
anything about module aliases so all module configuration
commands have to be sent for at least 2 reasons.
It is unlikely that this behavior will ever change.
<P>
Starting with release 2.0.47, a module can set M_SENDCONFIG on in its
mask and recieve M_CONFIG_INFO packets while it is running.
(M_CONFIG_INFO has to be on also.) A module can use M_SENDCONFIG
to be able to change configuration while it is running.
Refer to module FvwmAnimate for an example.
<P>
<H2><A NAME="M_END_CONFIG_INFO">M_END_CONFIG_INFO</A></H2>
<P>
After fvwm sends all of its M_CONFIG_INFO packets to a module, it
sends a packet of this type to indicate the end of the configuration
information. This packet contains no values.
This packet it not sent for subsequent config lines sent when the
M_SENDCONFIG mask bit is on.
<H2><A NAME="M_ICON_FILE">M_ICON_FILE</A></H2>
This packet is broadcast when a window is added or during
send window list. It is only sent for windows that have icons
defined, and contains the filename of the icon.
<H2><A NAME="M_DEFAULTICON">M_DEFAULTICON</A></H2>
This packet is sent during
send window list. This is the icon associated with Style "*".
The packet contains the filename of the icon.
<H2><A NAME="M_STRING">M_STRING</A></H2>
This packet is sent when a "SendToModule" command is processed.
<H2><A NAME="M_MINI_ICON">M_MINI_ICON</A></H2>
This packet is broadcast when a window is added or during
send window list. It is only sent for windows that have mini_icons
defined, and contains the filename of the mini_icon.
<H2><A NAME="M_WINDOWSHADE">M_WINDOWSHADE</A> and
<A NAME="M_DEWINDOWSHADE">M_DEWINDOWSHADE</A>
</H2>
This packet is sent when a window is window shaded.
It contains no additional information.
<H2><A NAME="M_LOCKONSEND">M_LOCKONSEND</A></H2>
This is a request sent from modules to fvwm and is described
under <a href="mod_m2f_communication.html">Module to Fvwm communication</a>.
<H2><A NAME="M_SENDCONFIG">M_SENDCONFIG</A></H2>
This is a request sent from modules to fvwm and is described
under <a href="mod_m2f_communication.html">Module to Fvwm communication</a>.
<P>
<hr>
</body>
</html>
