/usr/bin/fvwm-perllib is in fvwm 1:2.6.5.ds-4.1.
This file is owned by root:root, with mode 0o755.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 | #!/usr/bin/perl
# Copyright (c) 2002-2009 Mikhael Goikhman
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
# Filter this script to pod2man to get a man page:
# pod2man -c "Fvwm Utilities" fvwm-perllib | nroff -man | less -e
#use strict; # comment to make it faster
BEGIN {
# use vars qw($prefix $datarootdir $datadir $perllibdir);
$prefix = "/usr";
$datarootdir = "${prefix}/share";
$datadir = "${datarootdir}";
$perllibdir = "${datadir}/fvwm/perllib";
# try to do it as fast as possible
if ($ARGV[0] eq 'dir') {
print $perllibdir;
exit(0);
}
}
use Getopt::Long;
use lib $perllibdir;
use General::FileSystem '-die';
my $version = "2.6.5";
my $version_info = "";
my $pager = $ENV{PAGER} || "less -e";
my $do_man = 0;
my $do_cat = 0;
my $do_raw = 0;
GetOptions(
"help|h|?" => \&show_help,
"version|v|V" => \&show_version,
"man" => \$do_man,
"cat" => \$do_cat,
"raw" => \$do_raw,
"dir" => sub { print $perllibdir; exit(0); },
) || wrong_usage();
if ($ARGV[0] eq 'man') {
$do_man = 1;
shift;
} elsif ($ARGV[0] eq 'cat') {
$do_cat = 1;
shift;
} elsif ($ARGV[0] eq 'raw') {
$do_raw = 1;
shift;
}
wrong_usage() if !$do_man && !$do_cat && !$do_raw || @ARGV > 1;
my $man_or_cat_str = $do_man || $do_raw ? "man" : "cat";
my $internal_pods = {};
$internal_pods->{index} = qq{
:head1 NAME
index - lists all available help topics
:head1 DESCRIPTION
Recent I<fvwm> versions install the Perl library that makes creating
fvwm modules in Perl possible and easy.
You may read the Perl library documentation locally by running:
% fvwm-perllib $man_or_cat_str <topic>
Available topics:
index
tutorial
events
{{CLASS_NAMES}}
For example:
% fvwm-perllib $man_or_cat_str FVWM::Module
:head1 AUTHOR
Mikhael Goikhman <migo\@homemail.com>.
};
$internal_pods->{tutorial} = q{
:head1 NAME
tutorial - common techniques for writting fvwm modules
:head1 TUTORIAL
:head2 What is a window manager
A window manager is a program that runs on top of the X Window
System and manages windows, menus, key and mouse bindings, virtual
desktops and pages, draws window decorations using defined colors or
images, title-bar buttons and fonts. The window manager defines
window placement and focus policies. It may also manage such things
as root background, mouse cursors, sounds, run applications and
do other nice things.
:head2 What is a module
In the unix traditions, different functionality may be implemented
by separate programs to reduce a bloat. A module is an optional
program that is intended to extend the window manager using a defined
module protocol.
Fvwm modules are spawned by the main I<fvwm> executable. They
usually listen to the window manager events, do some useful work and
send back commands for execution. There are transient modules that
exit immediately or shortly, and persistent modules that exit
together with a window manager or when a user requests. Some
modules may control windows or other modules. Some modules may supply
a GUI, others may be non interactive.
:head2 Creating a simple module
Let's create a module that shows a flash window for one second when
you change pages. We will use I<xmessage> with nifty options for our
flash purposes, but you may use your fantasy to do this better.
First, we should understand when our module works. Usually a module
does nothing (sleeps) and is awaken when something interesting
happens. This is achieved using events. A module defines events that
it is interesting to receive and set-ups event handlers (perl
functions) to be called when the event happens. Then a module enters
the event loop where it sleeps all the time until one or another
event happens. Most of the module work is done in the event
handlers. When an event is processed, the module enters the event
loop again.
In our case, we should listen to an fvwm event I<M_NEW_PAGE>. The list
of all events may be found in man page "events". When we receive
the event we want to get new page coordinates and display them
using our special xmessage window.
Now, from theory to practice. The header of all modules written in
Perl is pretty standard:
#!/usr/bin/perl -w
use lib `fvwm-perllib dir`;
use FVWM::Module;
Then create the actual module object:
my $module = new FVWM::Module(
Mask => M_NEW_PAGE | M_NEW_DESK,
Debug => 1,
);
The B<Debug> option tells to print the event names that a module
receives to help writing a module, it also echoes all sent commands.
The B<Mask> option tells which events a module wants to receive, in
our case these are events generated on the page and desk changes.
To handle events, event handlers that are perl functions, should be
defined. It is ok not to define any event handler for I<M_NEW_DESK>
and to define two event handlers for I<M_NEW_PAGE>. But for our
purposes one I<M_NEW_PAGE> would be more than enough:
$module->add_handler(M_NEW_PAGE, \&got_new_page);
It is a time to implement our C<got_new_page> function that will be
called every time the desktop page is changed.
sub got_new_page {
my ($module, $event) = @_;
my $width = $event->_vp_width;
my $height = $event->_vp_height;
if (!$width || !$height) {
# this may happen when doing DeskTopSize 1x1 on page 2 2
return;
}
my $page_nx = int($event->_vp_x / $width);
my $page_ny = int($event->_vp_y / $height);
# actually show the flash
$module->send("Exec xmessage -name FlashWindow \
-bg cyan -fg white -center -timeout 1 -button '' \
-xrm '*cursorName: none' -xrm '*borderWidth: 2' \
-xrm '*borderColor: yellow' -xrm '*Margin: 12' \
'($page_nx, $page_ny)'");
}
All event handlers are called with 2 parameters, a module and an
event objects. The arguments for all events are defined in
L<FVWM::EventNames>. Each event type has its own arguments. Our
I<M_NEW_PAGE> has 5 arguments: vp_x vp_y desk vp_width vp_height.
We should do some calculations to get the page numbers from viewport
coordinates.
The B<send> method passes the command to I<fvwm> for execution.
It would be better to set-up the FlashWindow specially:
$module->send("Style FlashWindow StaysOnTop, NoTitle, NoHandles, \
BorderWidth 10, WindowListSkip, NeverFocus, UsePPosition");
Finally, all persistent modules should enter the event loop:
$module->event_loop;
The full module source that we just wrote is available at
ftp://ftp.fvwm.org/pub/fvwm/devel/sources/tests/perl/module-flash .
To run it execute this fvwm command:
Module /path/to/module-flash
To kill the module, execute:
KillModule /path/to/module-flash
:head2 Using event trackers
In fact, the task of calculating page coordinates, or managing
information about all windows, or gathering colorset, module or
global information is so often, that there are existing
implentation in the form of event trackers. Tracker is an instance
of L<FVWM::Tracker> superclass. Currently these tracker classes are
available (see their man pages):
FVWM::Tracker::Colorsets
FVWM::Tracker::GlobalConfig
FVWM::Tracker::ModuleConfig
FVWM::Tracker::PageInfo
FVWM::Tracker::Scheduler
FVWM::Tracker::WindowList
Using a tracker is easy, something along lines:
my $tracker = $module->track("WindowList");
my $colorset_tracker = $module->track("Colorsets");
Our module that we wrote above may be reduced if we use:
my $viewport = $module->track("PageInfo");
my $page_nx = $viewport->data("page_nx");
my $page_ny = $viewport->data("page_ny");
Note that the tracker continues to work and maintain the up-to-date
information about the current page and desk (or up-to-date windows
or colorsets depending on the tracker type) at any given moment.
Internally, trackers listen to appropriate events using the same
event handler mechanism, so there is no speed advantage. However
it is a good idea to reuse the existing verified code and reduce
the number of events needed to be trapped manually. There is
usually no problem if the developer and the tracker define
handlers for the same events (besides the handler order maybe).
:head2 On the module masks
In our example above we explicitly defined Mask in constructor.
This is not really needed. If not specified, the event mask is
managed automatically (it is updated every time a new event handler
is added).
Note, there are actually two event masks, called "mask" and
"xmask" (extended mask). If you are interested in the details,
refer to the fvwm documentation or perllib sources.
When trackers are added or removed, the module mask (and xmask)
are automatically tweaked underhand. In short, there is often no
reason to worry about the module masks. However, in rare cases
you may want to define SyncMask (or SyncXMask), so that fvwm is
synchronized with the module on certain events.
:head2 Creating a more functional module
Let's extend our new-page-flash example above and add a way to stop
our module and to define another string format. This would be
possible using the following I<fvwm> commands:
SendToModule /path/to/module-flash stop
SendToModule /path/to/module-flash format '[%d %d]'
To handle such commands, we should define I<M_STRING> event handler.
use General::Parse;
my $format = "(%d, %d)"; # the default format
$module->mask($module->mask | M_STRING);
$module->add_handler(M_STRING, sub {
my ($module, $event) = @_;
my $line = $event->_text;
my ($action, @args) = get_tokens($line);
if ($action eq "stop") {
$module->terminate;
} elsif ($action eq "format") {
$format = $args[0];
}
});
Now, let's convert our module to be GTK+ based and not to be
dependent on I<xmessage>.
use lib `fvwm-perllib dir`;
use FVWM::Module::Gtk;
use POSIX qw(SIGALRM);
Gtk->init;
my $format = "(%d, %d)";
my $module = new FVWM::Module::Gtk;
my $pageinfo = $module->track("PageInfo");
$pageinfo->observe("desk/page changed", sub {
my ($module, $tracker, $data) = @_;
my $page_nx = $data->{page_nx};
my $page_ny = $data->{page_ny};
my $width = $data->{vp_width};
my $height = $data->{vp_height};
# actually show the flash
my ($w, $h) = (80, 50);
my $string = sprintf($format, $page_nx, $page_ny);
my $window = new Gtk::Window('toplevel');
$window->set_title("FlashWindow");
$window->set_border_width(5);
$window->set_usize($w, $h);
$window->set_uposition(($width - $w) / 2, ($height - $h) / 2);
my $frame = new Gtk::Frame();
$window->add($frame);
$frame->set_shadow_type('etched_out');
my $label = new Gtk::Label($string);
$frame->add($label);
$window->show_all;
POSIX::sigaction(SIGALRM, POSIX::SigAction->new(
sub { $window->destroy(); }
));
alarm(1);
});
$module->event_loop;
The full module source that we just wrote is available at
ftp://ftp.fvwm.org/pub/fvwm/devel/sources/tests/perl/module-gtkflash .
:head1 EXAMPLES
Currently see I<ftp://ftp.fvwm.org/pub/fvwm/devel/sources/tests/perl/>
for examples.
Learning the sources of B<FvwmPerl>, B<FvwmDebug>, B<FvwmGtkDebug>
modules may help too.
:head1 SEE ALSO
See L<FVWM::Module> and L<FVWM::Module::Gtk> for the module API.
:head1 AUTHOR
Mikhael Goikhman <migo@homemail.com>.
};
$internal_pods->{events} = q{
:head1 NAME
events - list of all fvwm events with arguments
:head1 DESCRIPTION
This list is automatically generated from L<FVWM::EventNames> package.
Given L<FVWM::Event> object of certain event type, say I<M_STRING>,
here is the syntax to get value of its I<win_id> argument:
$win_id = $event->_win_id;
There are several more ways to access arguments, like:
$win_id = $event->arg_values->[0];
$text = $event->args->{text};
:head1 EVENTS WITH ARGUMENTS
{{EVENT_NAMES}}
:head1 ARGUMENT TYPE LEGEND
Here is a mapping of fvwm argument types to perl native types:
number - integer
bool - boolean, true or false
window - X window id in decimal, use sprintf("0x%07x", $wid)
pixel - "rgb:" . join('/', sprintf("%06lx", $val) =~ /(..)(..)(..)/)
string - string (scalar)
wflags - window flags in binary string
looped - loop of zero or more fixed argument bunches
Run L<FvwmDebug> or L<FvwmGtkDebug> to browse events.
:head1 SEE ALSO
See "tutorial", L<FVWM::Event>, L<FVWM::EventNames> and L<FvwmDebug>.
:head1 AUTHOR
Mikhael Goikhman <migo@homemail.com>.
};
my $topic = $ARGV[0] || "index";
my $file = "-";
my $text = "";
if (exists $internal_pods->{$topic}) {
$text = $internal_pods->{$topic};
$text =~ s/^\t//mg;
$text =~ s/^:/=/mg;
if ($topic eq 'index') {
my @class_names = sort @{list_filenames($perllibdir, 1)};
@class_names = map { s!\.pm$!!; s!/!::!g; $_ } @class_names;
$text =~ s/{{CLASS_NAMES}}/join("\n ", @class_names)/seg;
}
if ($topic eq 'events') {
my $content = `cat '$perllibdir/FVWM/EventNames.pm'`;
my $result = "";
foreach ($content =~ /\t&([^\s]+.*?\t\tfields[^\n]+(?:\n\t\t\t[^\n]+)*)/sg) {
my ($name, $rest) = /^([^\s]+).*?((?:\n\t\t\t[^\n]+)*)$/s; # ]
$result .= " $name\n";
$rest =~ s/([^\s]+)\s*=>\s*([\w]+)/
$result .= sprintf(" %-16s\t%s\n", $1, $2)
/eg;
$result .= "\n";
}
$text =~ s!{{EVENT_NAMES}}!$result!se;
}
} else {
$file = "$perllibdir/$topic.pm";
$file =~ s!::!/!g;
die "No $file found.\n" unless -f $file;
}
my $man_converter = $do_man ? " | nroff -man | $pager" : "";
open(MANPIPE, $do_cat ? "| pod2text '$file' | $pager" :
"| pod2man --section 3 --release 'fvwm $version$version_info'" .
" --center 'Fvwm Perl library' '$file'" .
" | sed 's/<STANDARD INPUT>/perllib/ig'$man_converter")
or die "Can't open pipe to pod/man viewer\n";
print MANPIPE $text
or die "Can't write to pod/man viewer\n";
close MANPIPE;
# ---------------------------------------------------------------------------
sub show_help {
print "Shows documentation of the supplied FVWM Perl library.\n\n";
print "Usage: fvwm-perllib man|cat\n";
print "\tAn introduction to the FVWM Perl library\n\n";
print "Usage: fvwm-perllib man|cat|raw <Perl::Class>\n";
print "\tManual page for <Perl::Class>, try: man FVWM::Module\n";
print "\t\$PAGER is used for a pager, the default is '$pager'\n\n";
print "Usage: fvwm-perllib dir\n";
print "\tFor use in fvwm modules written in Perl\n\n";
print "Usage: fvwm-perllib [OPTIONS]\n";
print "Options:\n";
print "\t--help show this help and exit\n";
print "\t--version show the version and exit\n";
exit 0;
}
sub show_version {
print "$version\n";
exit 0;
}
sub wrong_usage {
print STDERR "Try '$0 --help' for more information.\n";
exit -1;
}
__END__
# ---------------------------------------------------------------------------
=head1 NAME
fvwm-perllib - shows the documentation of the Fvwm Perl library
=head1 SYNOPSIS
B<fvwm-perllib>
[ B<--help>|B<-h>|B<-?> ]
[ B<--version>|B<-v>|B<-V> ]
[ B<man> [ I<Perl::Class> ] ]
[ B<cat> [ I<Perl::Class> ] ]
[ B<raw> [ I<Perl::Class> ] ]
[ B<dir> ]
=head1 DESCRIPTION
Starting from fvwm-2.5.x versions there is a built-in support for creating
fvwm modules in Perl. This B<fvwm-perllib> utility provides help services
for the Fvwm Perl library.
=head1 OPTIONS
B<--help>
show the help and exit
B<--version>
show the version and exit
B<--man> or B<man> [ I<Perl::Class> ]
show manual page just like man(1)
B<--cat> or B<cat> [ I<Perl::Class> ]
show manual page in plain text
B<--raw> or B<raw> [ I<Perl::Class> ]
generate output in man format (not human readable)
B<--dir> or B<dir>
print perllib directory without a trailing end of line
=head1 USAGE
Use this in the fvwm modules written in Perl:
use lib `fvwm-perllib dir`;
Introduction to the Fvwm Perl library:
% fvwm-perllib man
Manual page for the C<FVWM::Module> class:
% fvwm-perllib man FVWM::Module
Standard options:
% fvwm-perllib --help
% fvwm-perllib --version
=head1 AUTHORS
Mikhael Goikhman <migo@homemail.com>.
=head1 COPYING
The script is distributed by the same terms as fvwm itself.
See GNU General Public License for details.
=head1 BUGS
No known bugs.
Report bugs to fvwm-bug@fvwm.org.
=cut
# ***************************************************************************
|