# The Official FVWM Homepage - Fvwm-to-Module Communication

## When communication takes place

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.

## Communication packet format

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:

    #define M_NEW_PAGE           (1)
    #define M_NEW_DESK           (1<<1)
    #define M_ADD_WINDOW         (1<<2)
    #define M_RAISE_WINDOW       (1<<3)
    #define M_LOWER_WINDOW       (1<<4)
    #define M_CONFIGURE_WINDOW   (1<<5)
    #define M_FOCUS_CHANGE       (1<<6)
    #define M_DESTROY_WINDOW     (1<<7)
    #define M_ICONIFY            (1<<8)
    #define M_DEICONIFY          (1<<9)
    #define M_WINDOW_NAME        (1<<10)
    #define M_ICON_NAME          (1<<11)
    #define M_RES_CLASS          (1<<12)
    #define M_RES_NAME           (1<<13)
    #define M_END_WINDOWLIST     (1<<14)
    #define M_ICON_LOCATION      (1<<15)
    #define M_MAP                (1<<16)
    #define M_ERROR              (1<<17)
    #define M_CONFIG_INFO        (1<<18)
    #define M_END_CONFIG_INFO    (1<<19)
    #define M_ICON_FILE          (1<<20)
    #define M_DEFAULTICON        (1<<21)
    #define M_STRING             (1<<22)
    #define M_MINI_ICON          (1<<23)
    #define M_WINDOWSHADE        (1<<24)
    #define M_DEWINDOWSHADE      (1<<25)
    #define M_LOCKONSEND         (1<<26)
    #define M_SENDCONFIG         (1<<27)

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.

The body information is packet specific, as described below.

## M_NEW_PAGE

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.

## M_NEW_DESK

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.

## M_ADD_WINDOW, and M_CONFIGURE_WINDOW

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.

Format for Add and Configure Window Packets
Byte | Significance
0 | 0xffffffff - Start of packet
1 | packet type
2 | length of packet, including header, expressed in long integers
3 | ID of the application's top level window
4 | ID of the Fvwm frame window
5 | Pointer to the Fvwm database entry
6 | X location of the window's frame
7 | Y location of the window's frame
8 | Width of the window's frame (pixels)
9 | Height of the window's frame (pixels)
10 | Desktop number
11 | Windows flags field
12 | Window Title Height (pixels)
13 | Window Border Width (pixels)
14 | Window Base Width (pixels)
15 | Window Base Height (pixels)
16 | Window Resize Width Increment(pixels)
17 | Window Resize Height Increment (pixels)
18 | Window Minimum Width (pixels)
19 | Window Minimum Height (pixels)
20 | Window Maximum Width Increment(pixels)
21 | Window Maximum Height Increment (pixels)
22 | Icon Label Window ID, or 0
23 | Icon Pixmap Window ID, or 0
24 | Window Gravity
\ 25 | Pixel value of the text color
26 | Pixel value of the window border color

## M_LOWER_WINDOW, M_RAISE_WINDOW, and M_DESTROY_WINDOW

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.

Format for Lower, Raise, and Focus Change Packets
Byte | Significance
0 | 0xffffffff - Start of packet
1 | packet type
2 | length of packet, including header, expressed in long integers
3 | ID of the application's top level window
4 | ID of the Fvwm frame window
5 | Pointer to the Fvwm database entry

## M_FOCUS_CHANGE

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.

## M_ICONIFY and M_ICON_LOCATION

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.

Format for Iconify and Icon Location Packets
Byte | Significance
0 | 0xffffffff - Start of packet
1 | packet type
2 | length of packet, including header, expressed in long integers
3 | ID of the application's top level window
4 | ID of the Fvwm frame window
5 | Pointer to the Fvwm database entry
6 | X location of the window's frame
7 | Y location of the window's frame
8 | Width of the window's frame
9 | Height of the window's frame

## M_DEICONIFY

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.

## M_MAP

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.

## M_WINDOW_NAME, M_ICON_NAME, M_RES_CLASS, M_RES_NAME,

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.

## M_END_WINDOWLIST

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.

## M_ERROR

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.

## M_CONFIG_INFO

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.

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.

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.

## M_END_CONFIG_INFO

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.

## M_ICON_FILE

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.

## M_DEFAULTICON

This packet is sent during send window list. This is the icon associated with Style "*". The packet contains the filename of the icon.

## M_STRING

This packet is sent when a "SendToModule" command is processed.

## M_MINI_ICON

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.

## M_WINDOWSHADE and M_DEWINDOWSHADE

This packet is sent when a window is window shaded. It contains no additional information.

## M_LOCKONSEND

This is a request sent from modules to fvwm and is described under Module to Fvwm communication.

## M_SENDCONFIG

This is a request sent from modules to fvwm and is described under Module to Fvwm communication.