FVWM - Perl library - FVWM::Module

Manual page for FVWM::Module in unstable branch (2.5.14)

FVWM::Module

NAME

SYNOPSIS

    use lib `fvwm-perllib dir`;
    use FVWM::Module;

    my $module = new FVWM::Module;

    $module->send("Beep");

    # auto-raise all windows
    sub autoRaise { $_[0]->send("Raise", $_[1]->_win_id) };
    $module->addHandler(M_FOCUS_CHANGE, \&autoRaise);

    # terminate itself after 5 minutes
    my $scheduler = $module->track('Scheduler');
    $scheduler->schedule(5 * 60, sub { $module->terminate; });

    # print the current desk number ($pageTracker is auto updated)
    my $pageTracker = $module->track("PageInfo");
    $module->showMessage("Desk: " . $pageTracker->data->{desk_n});

    $module->eventLoop;

DESCRIPTION

If you are interested in all module protocol details that this class tries to make invisible, visit the web page http://fvwm.org/documentation/dev_modules.php. You will need an information about packet arguments anyway to be able to write complex modules. This is however not obligatory for simple modules that only send commands back when something happens.

A typical FVWM module has an initialization part including setting event handlers using addHandler methods and entering an event loop using eventLoop method. Most of the work is done in the event handlers although a module may define other execution ways, for example using $SIG{ALRM}.

An FVWM module receives 3 values from fvwm: rcFile - the file this module was called from or ``none'' if the module is called as a command from another module or from a binding/function (this value is not really useful), winId - the window context of this module if it is called from window decoration bindings or window menu (the value is integer, 0 if there is no window context), and finally context that indicates the place this module was called from, like menu or window title (see the fvwm documentation). All these values may be accessed as properties of the module object, like "$module->{winId}".  

METHODS

new, version, versionInfo, argv, send, track, eventLoop, sendReady, sendUnlock, postponeSend, terminate, resetHandlers, addHandler, deleteHandler, addDefaultErrorHandler, debug, showError, showMessage, showDebug, isDummy.

The following methods are called from other methods above, but may be useful in other situations as well:

internalDie, name, mask, xmask, isInMask, syncMask, syncXMask, isInSyncMask, disconnect, getHandlerCategory, readPacket, invokeHandler, processPacket, emulateEvent.

These methods deal with a received packet (event):

isEventExtended

These methods deal with configuration directories:

userDataDir, siteDataDir, searchDirs

new param-hash

Creates a module object. Only one module instance may be created in the program, since this object gets exclusive rights on communication with fvwm.

The following parameters may be given in the constractor:

    Name          - used in module configuration and debugging
    Mask          - events a module is interested to receive
    XMask         - the same for extended events
    SyncMask      - events to lock on
    SyncXMask     - the same for extended events
    EnableAlias   - whether a module accepts an alias in command line
    EnableOptions - options that a module accepts in command line
    Debug         - 0 means no debug, 1 - user debug, 2,3,4 - perllib

Example:

    my $module = new FVWM::Module(
        Name => "FvwmPerlBasedWindowRearranger",
        Mask => M_CONFIGURE_WINDOW | M_END_WINDOWLIST,
        EnableOptions => { "animate" => \$a, "cascade" => \$c },
        Debug => 2,
    );

Event types needed for the 4 mask parameters are defined in FVWM::Constants.

Set Debug to 2 to nicely dump all communication with fvwm (sent commands and received events). Setting it to 3 makes it even more verbose.

Some options cause an automatically parsing of the module command line args. See Getopt::Long for the format of the hash ref accepted by EnableOptions parameter. If boolean EnableAlias parameter is given, then the alias argument may be specified anywhere on the command line, for example before or after long/short options or even in between, as long as there are no conflicts with some non-mandatory option arguments. In which case ``--'' may be used to indicate the end of the options. All non-parsed command line arguments are available to the program using argv method.

version

Returns FVWM version string x.y.z.

versionInfo

Returns FVWM version info string, like `` (from cvs)'' or `` (snap-YYYYMMDD)''. This string is usually empty for the final version.

argv

Returns remaining module arguments (array ref) passed in the command line. Arguments that are used for fvwm-to-module communication are not included. Arguments that are automatically parsed using EnableAlias and/or EnableOptions specified in the constructor are not included.

send command [window-id] [continue-flag]

Sends command back for execution. If the window-id is specified this command will be executed in this window context. continue-flag of 0 signals that this is the last sent command from the module, the default for this flag is 1.

track [mode-hash] [name] [param-hash]

Creates a module tracker object (see FVWM::Tracker) specified by a name.

mode-hash may include parameters:

    NoStart - true value means the created tracker is not auto-started
    NoReuse - true value means not to reuse any existing named tracker

param-hash is specific to the tracker named name. Every tracker class (a subclass of FVWM::Tracker) has its own manual page, contact it for the tracker details and usage.

eventLoop

The main event loop. A module should define some event handlers using addHandler before entering the event loop. When the event happens all event handlers registered on this event are called, then a module returns to the event loop awaiting for new events forever.

This method may be finished when one of the following happens. 1) Explicit terminate is called in one of the event handlers. 2) Signal handler (system signals are independent from this event loop) decides to die. This is usually catched and a proper shutdown is done. 3) An event handler died, in this case the module aborts, this is done on purpose to encourage programmers to fix bugs. 4) Communication with fvwm closed, for example KillModule called or the main fvwm process exited.

In all these cases (except for the third one) ON_EXIT event handlers are called if defined and then disconnect is called. So no communication is available after this method is finished. If you need a communication before the module exits, define an ON_EXIT event handler.

sendReady

This is automatically called (if needed) when a module enters eventLoop, but sometimes you may want to tell fvwm that the module is fully ready earlier. This only makes sence if the module was run using ModuleSynchronous command, in this case fvwm gets locked until the module sends the ``ready'' notification.

sendUnlock

When an event was configured to be sent to a module synchronously using SyncMask and SyncXMask, fvwm gets locked until the module sends the ``unlock'' notification. This is automatically sent (if needed) when a handler is finished, but sometimes a handler should release fvwm earlier.

postponeSend command [window-id] [continue-flag]

The same like send, but the actual command sending is postponed until before the module enters the reading-from-fvwm phase in eventLoop.

terminate [continue]

This method is used for 2 purposed, usually in event handlers. To terminate the entire event loop and to terminate only an execution of the current handler if continue is set.

resetHandlers

This deletes all event handlers without exception.

addHandler mask code

Defines a handler (that is a code subroutine) for the given mask event (or several events). Usually the event type is one of the FVWM M_* or MX_* constants (see FVWM::Constants), but it may also be ON_EXIT, this special event is called just before the event loop is terminated.

The mask may include several events in the same category (the event types are or-ed). In this case the handler will be called for every matching event. Currently there are 3 categories: regular events (M_*), extended events (MX_*) and special events (ON_EXIT). These 3 categories of events can't be mixed, primary because of technical reasons.

The handler subroutine is called with these parameters:

    ($self, $event)

where $self is a module object, $event is FVWM::Event object.

If the mask includes more than one event type, use "$event->type" to dispatch event types if needed.

The handler may call "$self->terminate" to terminate the event loop completely or "$self->terminate("continue")" to terminate the current event handler only. The second form is useful when the handler subroutine calls other subroutines that need to terminate the primary one.

If several event handlers are added for the same event type, they are executed in the added order. To forbid the further propagation of the same event, an event handler may call "$event->propagationAllowed(0)".

The return value from addHandler is an identifier the only purpose of which is to be passed to deleteHandler in case the newly defined handler should be deleted at some point.

deleteHandler id

Removes the handler specified by id. The return value is 1 if the handler is found and deleted, 0 otherwise.

addDefaultErrorHandler

This adds the default handler for M_ERROR event. This class simply prints an error message to the standard error stream, but subclasses may define another default handler by overwriting this method.

debug msg [level]

Prints msg to the standard error stream if level is greater or equal to the module debug level defined using Debug in the constructor. The default level for this method is 1 that makes it possible to add user debugging output without specifying a level. The default module level is 0, so no debugging output of positive levels is shown.

This module uses debug internally (with level 2) to dump all incoming and outgoing communication data in send and processPacket. Apparently this output is only seen if Debug is set to 2 or greater.

showError msg

Writes msg to the error stream (stderr). It is supposed that the argument has no traling end of line. May be used to signal non fatal error.

Subclasses may overwrite this method and, for example, show all error messages in separate windows or in the common error window.

showMessage msg

Writes msg to the message stream (stderr). It is supposed that the argument has no traling end of line. May be used to show a named output.

Subclasses may overwrite this method and, for example, show all messages in separate windows or in the common message window.

showDebug msg

Unconditionally writes msg to the debug stream (stderr). It is supposed that the argument has no traling end of line. Used in debug to actually show the message when the level is matched.

Subclasses may overwrite this method and, for example, show all debugging messages in separate windows or in the common debug window.

isDummy

Usually a module should be executed by fvwm only. But to help creating GUI applications, the dummy mode is supported when the module is started from the command line. No events are received in this case, but with some effort they may be emulated:

    $module->emulateEvent(M_NEW_DESK, [ 2 ]) if $module->isDummy;

internalDie msg

This may be used to end the module with the corresponding msg. For a clean module exit use showError and terminate instead.

name [name]

Sets or returns the module name. Called automatically from the constructor.

mask [mask] [explicit-flag] =item xmask [mask] [explicit-flag]

Sets or returns the module mask. Called automatically from the constructor.

Regular and extended event types should never be mixed, this is why there are 2 variants of this method, the first is for regular and the second is for extended event types. Without a parameter, the module mask is returned, the integer parameter indicates a mask to set and the old mask is returned.

The module only receives the packets matching these 2 module masks (regular and extended).

This class is smart to update the minimal module masks automatically if you never set them explicitly (either in constructor or using these methods). The explicit-flag parameter should not be usually used, it defaults to 1. If you set it to 0 then the module is informed to continue to automatically update masks on the following addHandlers calls even after the current mask setting.

isInMask type

Returns true if the module mask matches the given type. Good for both regular and extended event types as long as they are queried separately.

syncMask [mask] =item syncXMask [mask]

The same as mask and xmask, but sets/returns the synchronization mask of the module.

The module is synchronized with fvwm on all packets matching these 2 module synchronization masks (regular and extended).

isInSyncMask type

Returns true if the module synchronization mask matches the given type. Good for both regular and extended event types as long as they are queried separately.

disconnect

This method invokes ON_EXIT handlers if any and closes communication. It is called automatically from eventLoop before finishing. It is safe to call this method more than once.

This method may be called from signal handlers before exiting for the proper shutdown.

getHandlerCategory type

Returns one of 3 string ids depending on the event handler type that has the same meaning as the corresponding packet type (``regular'' or ``extended'') with an addition of ``special'' category for ON_EXIT handlers.

readPacket

This is a blocking method that waits until there is a packet on the communication end from fvwm. Then it returns a list of 2 values, packet type and packet data (unpacked array of arguments).

invokeHandler event

Dispatches the apropos event handlers with the event data. This method is called automatically, so you usually should not worry about it.

processPacket [type data]

This method constructs the event object from the packet data and calls invokeHandler with it. Prints debug info if requested. Finally calls sendUnlock if needed.

You should not really worry about this method, it is called automatically from the event loop.

emulateEvent type data

This method emulates the event as returned by readPacket. The given event is processed immeadeatelly if in the event loop, or just before the real readPacket otherwise.

The parameters are the same as in processPacket and the same as in FVWM::Event constructor.

eventLoopPrepared

Called from eventLoop every time before reading the packet for new data. Subclasses should pass this method the same arguments that eventLoop received for a possible future use.

eventLoopFinished

Called from eventLoop just before the return. Subclasses should pass this method the same arguments that eventLoop received for a possible future use.

isEventExtended type

For technical reasons there are 2 categories of FVWM events, regular and extended. This is done to enable more events. With introdution of the extended event types (with the highest bit set) it is now possible to have 31+31=62 different event types rather than 32. This is a good point, the bad point is that only event types of the same category may be masked (or-ed) together. This method returns 1 or 0 depending on whether the event type is extended or not.

userDataDir

Returns the user data directory, usually ~/.fvwm or set by $FVWM_USERDIR.

siteDataDir

Returns the system-wide data directory, the one configured when FVWM is installed. It is also returned by `fvwm-config --fvwm-datadir`.

searchDirs

It is a good practice for a module to search for the given configuration in one of 2 data directories, the user one and the system-wide. This method returns a list of both directories in that order.

BUGS

CAVEATS

AUTHOR

THANKS TO

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

METHODS

BUGS

CAVEATS

AUTHOR

THANKS TO

SEE ALSO

Switch to window theme, pager on top theme, navigation theme,

Last modified on April 26, 2010