NAME

X11::Fvwm - Perl extension for the Fvwm2 X11 Window Manager

SYNOPSIS

use X11::Fvwm;

$handle = new X11::Fvwm;

$handle->initModule;

$handle->addHandler(M_CONFIGURE_WINDOW, \&configure_a_window);
$handle->addHandler(M_CONFIG_INFO, \&some_other_sub);

$handle->eventLoop;

$handle->endModule;

DESCRIPTION

The X11::Fvwm package is designed to provide access via Perl 5 to the module API of Fvwm 2. This code is based upon Fvwm 2.0.45 beta.

The most common track to interfacing with Fvwm is to create an object of the X11::Fvwm class, and use it to create/destroy event handlers, and catch and route such events from Fvwm. Event handlers can be tied to specific event types, or given masks that include multiple events, for which the handler would be passed the data for any of the events it accepts.

Exported constants

The following constants are exported automatically by X11::Fvwm. Most of these are defined either in the modules.tex file that is part of the docs/ directory in the fvwm distribution, or within the code itself (particularly the files fvwm.h and module.h in the actual source directory):

C_ALL
C_FRAME
C_ICON
C_L1
C_L2
C_L3
C_L4
C_L5
C_LALL
C_NO_CONTEXT
C_R1
C_R2
C_R3
C_R4
C_R5
C_RALL
C_ROOT
C_SIDEBAR
C_TITLE
C_WINDOW
F_ALL_COMMON_FLAGS
F_BORDER
F_CirculateSkip
F_CirculateSkipIcon
F_ClickToFocus
F_DoesWmTakeFocus
F_DoesWmDeleteWindow
F_HintOverride
F_ICON_MOVED
F_ICON_OURS
F_ICON_UNMAPPED
F_ICONIFIED
F_Lenience
F_MAP_PENDING
F_MAPPED
F_MAXIMIZED
F_MWMButtons
F_MWMBorders
F_NOICON_TITLE
F_ONTOP
F_PIXMAP_OURS
F_RAISED
F_SHAPED_ICON
F_SHOW_ON_MAP
F_STARTICONIC
F_STICKY
F_SUPPRESSICON
F_SloppyFocus
F_StickyIcon
F_TITLE
F_TRANSIENT
F_VISIBLE
F_WINDOWLISTSKIP
HEADER_SIZE
MAX_BODY_SIZE
MAX_MASK
MAX_PACKET_SIZE
M_ADD_WINDOW
M_CONFIGURE_WINDOW
M_CONFIG_INFO
M_DEFAULTICON
M_DEICONIFY
M_DESTROY_WINDOW
M_DEWINDOWSHADE
M_END_CONFIG_INFO
M_END_WINDOWLIST
M_ERROR
M_FOCUS_CHANGE
M_ICONIFY
M_ICON_FILE
M_ICON_LOCATION
M_ICON_NAME
M_LOWER_WINDOW
M_MAP
M_MINI_ICON
M_NEW_DESK
M_NEW_PAGE
M_RAISE_WINDOW
M_RES_CLASS
M_RES_NAME
M_STRING
M_WINDOWSHADE
M_WINDOW_NAME
P_LAZY_HANDLERS
P_PACKET_PASSALL
P_STRIP_NEWLINES
START_FLAG

See "CONSTANTS AND FLAGS" below for short definitions of these.

METHODS

Object manipulation is provided via these methods. $self is assumed to be an object of this class, and all methods aside from new are assumed to be prefixed as $self->method.

new

$self = new X11::Fvwm %params

Create and return an object of the X11::Fvwm class. The return value is the blessed reference. Any combination of INIT, CONFIG, MASK, NAME, OPTIONS and DEBUG may be passed in with corresponding values to specify certain parameters at creation time. Each of these are treated as key/value pairs, so even options such as INIT that are only meaningful if set to "1" still must have that value.

If INIT is specified and evaluates to true, initModule is run.

If CONFIG is specified and evaluates to true, getConfigInfo is run, but no values are returned from it. It is run only to warm up the internal cache.

If MASK is specified, the value passed in is sent to Fvwm as the packet mask this application requires.

If NAME is specified, it is stored as the internal name for the application, which is used primarily for selecting configuration options intended for the running application.

If OPTIONS is specified, it is stored as the Perl options for the object. Otherwise, the options default to P_STRIP_NEWLINES.

If DEBUG is specified and evaluates to true, debugging is enabled for this object.

mask

$old_mask = $self->mask($new_mask)

Get or set the current mask for this object. If called with no argument, then the current value of the mask is returned. Otherwise, the single argument is sent to Fvwm as a new mask request.

name

$name = $self->name($new_name)

Get or set the name by which the running object expects to br identified. This defaults to the last element of $0, the script name, but they do not have to be identical. Do understand that Fvwm will attempt some communications based on the name by which it knows the running module. name() has no bearing on this. This is the value used for pattern matching if the getConfigInfo method is called with the *trimname option.

options

$opts = $self->options($new_options)

Get or set the Perl-level options that this object uses. These are the P_* constants. See also the setOptions method, described below.

initModule

$self->initModule($mask)

Initialize this object with respect to the Fvwm communication streams. Takes the Fvwm-related items out of the arguments list and leaves any remaining arguments in an instance variable called argv. The read and write pipes are recorded for use by the communication methods, and the configuration file, window ID and context are stored on instance variables as well (see "Instance Variables").

initModule takes one optional argument, a packet mask to send after the communications pipes are set up. If passed, it will override any value that may have been specified in the call to new. If not specified, then the value from new is used, and if there was no specific mask given to new then no mask is sent, meaning that the object will get every packet sent out by Fvwm.

sendInfo

$self->sendInfo($win_id, $data)

Send to Fvwm a data packet with possible window specification. The contents of $data will be sent, encoded as Fvwm specifies. $win_id may be 0, in which case Fvwm handles the transaction itself, unless the transaction is in fact window-specific, in which case Fvwm prompts the user to select a target window.

readPacket

$self->readPacket()

Read a data packet from Fvwm via the input handle the module received at start-up. Returns the triple ($len, $packet, $type), and also stores this on the instance variable lastPacket. This call will block until there is data available on the pipe to be read.

processPacket

$self->processPacket($len, $packet, $type)

Breaks down the contents of $packet based on $type. Dispatches all packet handlers that accept packets of type $type, passing as arguments $type follwed by the contents of the packet itself. If $len is undef, then the triple stored in lastPacket is used. If $len is equal to -1, then this method immediately returns a value of 0.

If the $stop flag passed when a handler was created (see addHandler) was true, then a false (zero) return value from the handler causes processPacket to return 0. Setting the option P_LAZY_HANDLERS causes all handlers created to set their stop value to 0.

The execution of handlers is done in a two-stage loop, the first being by looping incrementally through all the masks for which known handlers exist and secondly in the order in which handlers were added for a given mask. If two handlers are created for the packet M_ERROR and one for the combination of M_ERROR and M_STRING, then the two for M_ERROR alone will be evaluated first, in the order in which they were created. Afterwards, the one handler will be executed. This is because the value of M_ERROR and M_STRING combined will be greater than M_ERROR alone.

In general, if multiple handlers are going to be assigned to a given packet type, they should be as independant of each other as possible, and reliance on execution order should be avoided.

addHandler

$new_id = $self->addHandler($mask, $reference)

Add a new handler routine to the internal table, set to be called for any packets whose type is included in $mask. The mask argument may contain more than one of the known packet types (see "Packet Types"), or may be the special string EXIT. All handlers of type EXIT are called by eventLoop at termination (or may be explicitly called within signal catchers and the like with invokeHandler). Others are called when a packet of the flagged type arrives.

The return value from addHandler is an identifier into the internal table kept and tracked by the X11::Fvwm object. This identifier is used in the case where a handler should be deleted. The return value itself should not be directly used, as its format is internal and does not give any indication of execution priority.

The second argument to addHandler is a reference to a subroutine (or closure). This is the code (or callback, if you prefer) that will be executed with the packet contents as arguments. Every handler gets arguments of the form:

($self, $type, $id, $frameid, $ptr, [, @args])

where $type is the packet type itself (or EXIT), $id is the X Windows window ID of the application main window, $frameid is the X window ID of the frame created by Fvwm to house the window decorations, and $ptr is an index into the internal database that Fvwm maintains for all managed windows. $self is the reference to the X11::Fvwm object that invoked the addHandler method, allowing the routine access to the instance variables. If the packet, by definition, has additional arguments, these follow after the initial four, in the order described by the module API documentation packaged with Fvwm. All packets, however, contain at least these three initial values (the $type argument is provided by processPacket for the sake of handlers written to manage multiple packet types).

The $ptr argument is guaranteed to be unique for all windows currently managed. It can prove useful as an index itself (see the PerlTkWL sample application, which uses this value in such a way).

The addHandler method does not allow or support symbolic references to subroutines.

deleteHandler

$self->deleteHandler($id)

Delete the specified handler from the internal table. $id must be a value returned from an earlier call to addHandler.

invokeHandler

$self->invokeHandler($type, @args)

Force the execution of all handlers that would trigger on a packet of type $type. @args will be passed to each called routine immediately following $type itself, as is the behavior of processPacket.

setOptions

$new_opts = $self->setOptions($set, $clear, $preserve)

A more extensive way to set and clear Perl object options. All flags set in the value $set will be added to (via logical OR) the current options. All flags in $clear will be removed from the current options. If $preserve is passed, it is expected to be a scalar reference, and the current options settings are stored in it before alteration. Either of $set or $clear can be undef, in which case they have no effect. The return value is the new option set.

This differs from the options method described earlier, which only fetches or assigns the options, it does not allow for the detail provided here.

getConfigInfo

%hash = $self->getConfigInfo(@keys)

Fetch information from the running Fvwm process through the configuration interface. Configuration lines are those lines in the configuration file that start with a leading * character. The first time this method is called, the module fetches all configuration information, discarding the leading asterisk from the names. Specific values may be requested, or the entire contents fetched. A module has access to all configuration data, not just the lines that match the name of the program. The return value is a hash table whose keys are the name part of the configuration lines (sans asterisk) and whose values are the contents of the lines.

In addition to the configuration lines, Fvwm also sends the following parameters: IconPath, PixmapPath, ColorLimit and ClickTime. These are also retrievable by those names.

The values in the optional arguments @keys can be a specific name to look up (or names), or any of the following special directives:

-refresh forces getConfigInfo to re-read the data from Fvwm.

-all causes the method to return the full configuration table, not just those names that contain the module name as a substring of the configuration item name (this value is taken from the NAME instance variable).

-trimname instructs the method to excise the module name (the value of the NAME instance variable) from any keys in the final return set that contain the name as a substring. As an example, a module named TkWinList can get back names such as Foreground rather than TkWinListForeground. Keys not containing the substring will not be affected.

If any specific keys are requested in @args, then the returned hash table only contains those keys which were in fact present in the internal table. -trimname can still be used to remove the module name from the keys.

If an option is intended to be lengthy and possibly span lines, multiple occurances of that configuration name can appear in the configuration file. In cases where the same name appears more than once, the value returned for that key is an array reference rather than a scalar. The contents of the referred array are all the values from the series of lines.

Again, the PerlTkWL sample application utilizes these features, and may be referenced for further information.

Note: Alpha versions of this module used the asterisk (*) to specify directives to getConfigInfo. That has been deprecated with the first beta release (0.3), and will be removed entirely in the first official release.

eventLoop

$self->eventLoop($top)

An endless loop is entered in which readPacket and processPacket are called. When processPacket indicates a completion (by an exit code of zero), any EXIT handlers are called and the module exits.

endModule

$self->endModule

Sends a final packet to Fvwm indicating that the module is exiting, then closes the input and output pipes.

Instance Variables

In addition to the methods above, there are also several instance variables available to the programmer. Not all of the instance variables are intended to be accessed or altered by the programmer, but the ones in the following listing are meant to be public:

MASK

This is the current mask registered with Fvwm. Setting this does not automatically set a new mask. Use the mask() method above for that.

NAME

This is the current application name, for the purpose of associating module configuration options. Set it with name() described above.

OPTIONS

The current Perl-level module options. Can be tested against the P_* constants. Can be set with the either the setOptions method or the options method, both described above.

DEBUG

A flag used to note when debugging information is requested. Can be used in handler routines to supplement debugging, or set/unset as desired for selective debugging.

fvwmWinId

The X window ID for the window from whose context the module was launched, if applicable. If the module was not launced from the context of a specific window, this value is zero.

fvwmContext

The actual context of the launch, if applicable. Can be compared against the C_* constants. Also set to zero if the module was not launched in context of a specific window.

fvwmRcfile

The configuration file that Fvwm read at its own start-up. In earlier API models, the module was responsible for reading this file directly to obtain configuration information. That is no longer necessary, but having the path to the file handy may still be useful to some applications.

packetTypes

This is a reference to the internal hash-table of unpack formats used in the processing of packet data. Most likely, a module developer will not need this, as the handlers are invoked with the data already unpacked and sent as subroutine arguments. However, some cases arise (such as the initialization in the PerlTkWL sample application) when it is necessary to talk to and understand the results from Fvwm directly. Modify this at your own peril.

lastPacket

A list-reference containing the data from the most-recent packet read, as a triple ($len, $packet, $type). Will be undefined until the first packet read.

CONSTANTS AND FLAGS

The lines of communication between Fvwm and the module are maintained via the well-defined flags and constants from the header files in the source. The following values are exported by default into the namespace of the application or package using X11::Fvwm. They are taken directly from the header files, so should be portable across platforms:

Packet Types

Most of the packets have the same first three parameters as explained in the definition of the addHandler method. For this section, assume that $id, $frameid and $ptr have the same meaning as defined there. Much of this text is based on the file modules.tex in the Fvwm distribution.

M_ADD_WINDOW

This packet is essentially identical to M_CONFIGURE_WINDOW below, differing only in that M_ADD_WINDOW is sent once, when the window is created, and the M_CONFIGURE_WINDOW packet is sent when the viewport on the current desktop changes, or when the size or location of the window is changed. They contain 24 values. The first 3 identify the window, and the next twelve identify the location and size, as described in the list below. The flags field is an bitwise OR of the flags defined below in "Flags":

Arg #        Usage

0            $id
1            $frameid
2            $ptr
3            X location of the window frame
4            Y location of the window frame
5            Width of the window frame (pixels)
6            Height of the window frame (pixels)
7            Desktop number
8            Windows flags field
9            Window Title Height (pixels)
10           Window Border Width (pixels)
11           Window Base Width (pixels) 
12           Window Base Height (pixels)
13           Window Resize Width Increment(pixels)
14           Window Resize Height Increment (pixels)
15           Window Minimum Width (pixels)
16           Window Minimum Height (pixels)
17           Window Maximum Width Increment(pixels)
18           Window Maximum Height Increment (pixels)
19           Icon Label Window ID, or 0
20           Icon Pixmap Window ID, or 0
21           Window Gravity
22           Pixel value of the text color
23           Pixel value of the window border color

M_CONFIGURE_WINDOW

Same structure and contents as M_ADD_WINDOW.

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, ColorLimit and ClickTime parameters are sent to the module.

M_DEFAULTICON

This packet identifies the default icon for the session. The first three arguments are all zero, and the fourth is a text string containing the name of the icon to use.

M_DEICONIFY

This packet contains the standard three arguments. It is sent whenever the indicated window is de-iconified.

M_DESTROY_WINDOW

The three default arguments identify a window that was just destroyed, and is no longer on the display.

M_DEWINDOWSHADE

The three default arguments identify a window that was just unshaded (applicable only if window-shading was enabled in the configuration).

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.

M_END_WINDOWLIST

This packet is sent to mark the end of transmission in response to a Send_WindowList request. A module which requests Send_WindowList, then 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. It does not have the standard first three values.

M_FOCUS_CHANGE

This packet signifies that the window manager focus has changed. The first three parameters are the common three. There are also a fourth and fifth parameter, the pixel value of the window's text focus color and the window's border focus color, respectively. If the window that now has the focus is not a window recognized by Fvwm, then only the first of these five values, the X window ID, is set. The rest will be zeros.

M_ICONIFY

This packets contain 7 values. The first 3 are the usual identifiers, and the next four describe the location and size of the icon window, as described below. Note that M_ICONIFY packets will be 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. 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.

Arg #        Usage

0            $id
1            $frameid
2            $ptr
3            X location of the icon frame
4            Y location of the icon frame
5            Width of the icon frame (pixels)
6            Height of the icon frame (pixels)

M_ICON_FILE

This packet has the three standard arguments identifying the window, then a text string with the the name of the file used as the icon image. This packet is sent only if the window in question uses an icon other than the default icon image (see M_DEFAULTICON above).

M_ICON_LOCATION

Similar to the M_ICONIFY packet described earlier, this packet has the same arguments in the same order. It is sent whenever the associated icon is moved.

M_ICON_NAME

This packet is like the M_RES_CLASS and M_RES_NAME packets. It contains the usual three window identifiers, followed by a variable length character string that is the icon name (not to be confused with the name of the icon image; this is the name by which the window is identified while in an iconic state).

M_LOWER_WINDOW

The three default arguments identify a window that was just moved to the bottom of the stacking order.

M_MAP

Contains the standard 3 values. 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_MINI_ICON

This packet contains eight numeric values and a string. The first three are the typical triple, identifying the window. The full packet looks like:

Arg #        Usage

0            $id
1            $frameid
2            $ptr
3            Width of the mini-icon
4            Height of the mini-icon
5            Depth (number of bit-planes)
6            The X server Pixmap ID of the image
7            The X server Pixmap ID of the mask image
8            The name of the mini-icon file

This packet is only sent if the window has a mini-icon associated with it.

M_NEW_DESK

This packet type does not have the usual three leading arguments. 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_NEW_PAGE

These packets also differ from the standard in not having the usual first three arguments. Instead, they 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_RAISE_WINDOW

The three default arguments identify a window that was just moved to the top of the stacking order.

M_RES_CLASS

This packet contains the usual three window identifiers, followed by a variable length character string. The RES_CLASS and RES_NAME fields are fields in the XClass structure for the window. The RES_CLASS and RES_NAME packets are sent on window creation and in response to a Send_WindowList request from a module.

M_RES_NAME

This packet is identical to M_RES_CLASS, identifying instead the resource name for the window.

M_STRING

Similar to the other text packets such as M_ICON_NAME or M_RES_CLASS, this packet contains zeros for the first three arguments, and a variable-length text string as its fourth. This is sent to all modules whose name matches the name pattern from a SendToModule command.

M_WINDOWSHADE

The three default arguments identify a window that was just shaded (applicable only if window-shading was enabled in the configuration).

M_WINDOW_NAME

This packet is like the M_ICON_NAME, M_RES_CLASS and M_RES_NAME packets. It contains the usual three window identifiers, followed by a variable length character string that is the window name.

Packet Values

These values are used in disassembling a raw packet into data that is then passed to a handler. In general, a developer will not need these, as the bulk of the work that they are used for occurs in readPacket. They are here for completeness, and in case an application does have a need.

START_FLAG

This is the value that should be in the first word of the packet. It is set to 0xffffffff (if the word size is 32 bits). If this is not the first word in the packet, the packet cannot be considered usable.

HEADER_SIZE

The size, in words, of the header. This is used to separate the words that comprise the header from the packet body.

MAX_BODY_SIZE

Maximum size of a packet body, in words.

MAX_MASK

A mask that matches all M_* packet type values, useful as an operator to a logical and.

MAX_PACKET_SIZE

Maximum packet size (in words), including both header and body.

Context Specifiers

When a module is launched, one of the parameters passed on the command-line is the context in which the module was started. This is stored on the X11::Fvwm object instance in the variable fvwmContext. These flags can be used in tests against this value to determine where the running module was launched from.

C_ALL

A mask that matches all C_* flags. Useful as a logical and operand.

C_NO_CONTEXT

The module has no launch context. These are modules that are launched from the configuration file as Fvwm starts up.

C_ROOT

The module was launched from the root window (via PopUp menu or hot-key).

C_SIDEBAR

Launch was from the sidebar decorating an application.

C_TITLE

Lauch occurred from the titlebar itself (but not any of the buttons).

C_WINDOW

The module was launched from within the window of a running application.

C_FRAME

Launch was from the frame of a managed window.

C_ICON

Launch was from the icon of a managed application.

C_L1

The first (leftmost) button on the left of the titlebar.

C_L2

Second left-side button (to the right of C_L1).

C_L3

Third left-side button (to the right of C_L2).

C_L4

Fourth left-side button (to the right of C_L3).

C_L5

Fifth left-side button (to the right of C_L4).

C_LALL

A mask that matches any of the C_L[12345] context flags.

C_R1

The first (rightmost) button on the right of the titlebar.

C_R2

Second right-side button (to the left of C_R1).

C_R3

Third right-side button (to the left of C_R2).

C_R4

Fourth right-side button (to the left of C_R3).

C_R5

Fifth right-side button (to the left of C_R4).

C_RALL

A mask that matches any of the C_R[12345] context flags.

Flags

These are the flags, from the file fvwm.h, that are packed into the FLAGS value of M_ADD_WINDOW and M_CONFIGURE_WINDOW packets. Unlike the other constants and flags used by the X11::Fvwm module, these have slightly different names than their native Fvwm counterparts. This is because the values in fvwm.h have no distinct prefix, such as C_ or M_. So as to reduce the risk of name conflict, all of these flags were given a prefix of F_.

F_ALL_COMMON_FLAGS

A mask covering the more commonly-used style flags: F_STARTICONIC, F_ONTOP, F_STICKY, F_WINDOWLISTSKIP, F_SUPPRESSICON, F_NOICON_TITLE, F_Lenience, F_StickyIcon, F_CirculateSkipIcon, F_CirculateSkip, F_ClickToFocus, F_SloppyFocus, F_SHOW_ON_MAP.

F_BORDER

This window has a border drawn with it.

F_CirculateSkip

This window has the CirculateSkip style property set.

F_CirculateSkipIcon

This window has the CirculateSkipIcon style property set.

F_ClickToFocus

Whether the window focus style is ClickToFocus.

F_DoesWmTakeFocus

Whether the _XA_WM_TAKE_FOCUS property is set on the window.

F_DoesWmDeleteWindow

Whether the _XA_WM_DELETE_WINDOW property is set on the window.

F_HintOverride

Not documented yet.

F_ICON_MOVED

Not documented yet.

F_ICON_OURS

The icon window was provided by Fvwm, and should be freed by Fvwm.

F_ICON_UNMAPPED

Not documented yet.

F_ICONIFIED

This window is currently iconified.

F_Lenience

Not documented yet.

F_MAP_PENDING

This application is still awaiting mapping.

F_MAPPED

This window (application) is mapped on the display.

F_MAXIMIZED

This window is currently maximized.

F_MWMButtons

This window has its style set to include MWM-ish buttons.

F_MWMBorders

This window has its style set to include MWM-ish borders.

F_NOICON_TITLE

This window will not have a title with its icon.

F_ONTOP

This window is set with the StaysOnTop style setting, meaning that it will always be raised over any windows that ubscure it, even partially (except other StaysOnTop windows).

F_PIXMAP_OURS

The pixmap used for the icon was loaded and provided by Fvwm, and should also be freed by Fvwm when no longer needed.

F_RAISED

If it is a sticky window, this indicates whether or not it needs to be raised.

F_SHAPED_ICON

The icon for this window is a shaped icon.

F_SHOW_ON_MAP

When this window is mapped, the desktop should switch to the apropos quadrant and desk.

F_STARTICONIC

This window was instructed to start in an iconic state.

F_STICKY

This window is considered sticky.

F_SUPPRESSICON

This application should not be displayed when iconic.

F_SloppyFocus

This window responds to a focus style of SloppyFocus.

F_StickyIcon

The icon for this window is considered sticky.

F_TITLE

This window is assigned a title bar.

F_TRANSIENT

This window is a transient window.

F_VISIBLE

Window is considered fully-visible (only obscuring should be windows that are set to StaysOnTop).

F_WINDOWLISTSKIP

This window should be skipped over in generated lists of windows.

Perl Values

These are values that relate to the Perl objects directly. They are not defined anywhere in Fvwm, but exist as convenience to the module programmer.

P_LAZY_HANDLERS

If this option is set, then any new handlers created are set automatically to ignore return codes when evaluated in the loop that processPacket executes. Since the idea is to use return values to detect errors, setting this is of dubious usefulness. But it can have its application (though some would say that explicitly setting the handlers in this fashion is clearer).

P_PACKET_PASSALL

This option tells processPacket not to strip out any extra arguments from packets such as M_STRING that may have extra data after the variable-length string. It is not set by default.

P_STRIP_NEWLINES

If this option is set, then those packets that pass text data (such as M_ICON_NAME or M_STRING) will have any trailing new-lines stripped (but not internal ones). This option is set by default.

P_ALL_OPTIONS

A combination of all P_* value, useful as a mask for a logical and.

EXAMPLES

Examples are provided in the scripts directory of the distribution. These are:

PerlWinList

A simple window-listing program that demonstrates simple module/Fvwm communication, without a lot of features to clutter up the source code. Outputs to /dev/console.

PerlDebug

A packet-debug utility that echoes packets to the console or to a specified file.

BUGS

Would not surprise me in the least.

CAVEATS

In keeping with the UNIX philosophy, X11::Fvwm does not keep you from doing stupid things, as that would also keep you from doing clever things. What this means is that there are several areas with which you can hang your module or even royally confuse your running Fvwm process. This is due to flexibility, not bugs.

The contents of the M_WINDOWSHADE, M_DEWINDOWSHADE and M_MINI_ICON packets are based on patches submitted by the author. Without these patches, these packets do not return a level of information useful to X11::Fvwm. Access to the frame ID or the database ID is dependant on these patches. As of release 0.4, these patches are available in a sub-directory of the X11::Fvwm distribution called "patches", and are assumed to be applied against Fvwm 2.0.45.

The ColorLimit parameter that is fetched by getConfigInfo is only accessible if you have applied the color-limiting patch to Fvwm 2.0.45. This patch is also supplied in the "patches" sub-directory, for your convenience.

AUTHOR

Randy J. Ray <randy@byz.org>

ADDITIONAL CREDITS

Considerable text used in defining the packet types was taken from or based heavily upon the modules.tex file written by Robert J. Nation, which is distributed with Fvwm.

SEE ALSO

For more information, see fvwm and X11::Fvwm::Tk

cpanm X11::Fvwm

perl -MCPAN -e shell
install X11::Fvwm