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.
fvwm.h and module.h in the actual source
directory):
See CONSTANTS AND FLAGS below for short definitions of these.
$self is assumed to
be an object of this class, and all methods aside from
new
are assumed
to be prefixed as $self->method.
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.
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.
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.
Get or set the Perl-level options that this object uses. These are the
P_* constants. See also the
setOptions
method, described below.
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.
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.
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.
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.
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:
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.
Delete the specified handler from the internal table. $id must be a
value returned from an earlier call to
addHandler
.
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
.
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.
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.
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.
Sends a final packet to Fvwm indicating that the module is exiting, then closes the input and output pipes.
P_*
constants. Can be set with the either the
setOptions
method or the
options
method, both described above.
C_* constants. Also set to zero if the module was not launched in context
of a specific window.
$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.
0xffffffff (if the word size is 32 bits). If this is not the first
word in the packet, the packet cannot be considered usable.
_XA_WM_TAKE_FOCUS property is set on the window.
_XA_WM_DELETE_WINDOW property is set on the window.
/dev/console.