ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.5 by root, Mon Jan 2 17:20:00 2006 UTC vs.
Revision 1.22 by root, Tue Jan 3 19:10:54 2006 UTC

1=encoding utf8
2
1=head1 NAME 3=head1 NAME
2 4
3rxvtperl - rxvt-unicode's embedded perl interpreter 5@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
4 6
5=head1 SYNOPSIS 7=head1 SYNOPSIS
6 8
7* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically. 9 # create a file grab_test in $HOME:
8
9* Each script will only be loaded once, even in urxvtd, and will be valid
10globally.
11
12* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
13thus must be encoded as UTF-8.
14 10
15 sub on_sel_grab { 11 sub on_sel_grab {
16 warn "you selected ", $_[0]->selection; 12 warn "you selected ", $_[0]->selection;
17 () 13 ()
18 } 14 }
19 15
20 1 16 # start a @@RXVT_NAME@@ using it:
17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
21 19
22=head1 DESCRIPTION 20=head1 DESCRIPTION
21
22Everytime a terminal object gets created, scripts specified via the
23C<perl> resource are loaded and associated with it.
24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8.
27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals.
30
31=head2 Prepackaged Extensions
32
33This section describes the extensiosn delivered with this version. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35
36You can activate them like this:
37
38 @@RXVT_NAME@@ -pe <extensionname>
39
40=over 4
41
42=item selection
43
44Intelligent selection. This etxension tries to be more intelligent when the user
45extends selections (double-click).
46
47It also offers the following bindable event:
48
49=over 4
50
51=item rot13
52
53Rot-13 the selection when activated. Used via keyboard trigger:
54
55 URxvt.keysym.C-M-r: perl:selection:rot13
56
57=back
58
59=item digital-clock
60
61Displays a digital clock using the built-in overlay.
62
63=item example-refresh-hooks
64
65Displays a very simple digital clock in the upper right corner of the
66window. Illustrates overwriting the refresh callbacks to create your own
67overlays or changes.
68
69=back
70
71=head2 General API Considerations
72
73All objects (such as terminals, time watchers etc.) are typical
74reference-to-hash objects. The hash can be used to store anything you
75like. All members starting with an underscore (such as C<_ptr> or
76C<_hook>) are reserved for internal uses and must not be accessed or
77modified).
78
79When objects are destroyed on the C++ side, the perl object hashes are
80emptied, so its best to store related objects such as time watchers and
81the like inside the terminal object so they get destroyed as soon as the
82terminal is destroyed.
23 83
24=head2 Hooks 84=head2 Hooks
25 85
26The following subroutines can be declared in loaded scripts, and will be called 86The following subroutines can be declared in loaded scripts, and will be called
27whenever the relevant event happens. 87whenever the relevant event happens.
64Called whenever a selection has been copied, but before the selection is 124Called whenever a selection has been copied, but before the selection is
65requested from the server. The selection text can be queried and changed 125requested from the server. The selection text can be queried and changed
66by calling C<< $term->selection >>. 126by calling C<< $term->selection >>.
67 127
68Returning a true value aborts selection grabbing. It will still be hilighted. 128Returning a true value aborts selection grabbing. It will still be hilighted.
129
130=item on_sel_extend $term
131
132Called whenever the user tries to extend the selection (e.g. with a double
133click) and is either supposed to return false (normal operation), or
134should extend the selection itelf and return true to suppress the built-in
135processing.
136
137See the F<selection> example extension.
69 138
70=item on_focus_in $term 139=item on_focus_in $term
71 140
72Called whenever the window gets the keyboard focus, before urxvt does 141Called whenever the window gets the keyboard focus, before urxvt does
73focus in processing. 142focus in processing.
106 175
107=item on_refresh_end $term 176=item on_refresh_end $term
108 177
109Called just after the screen gets redrawn. See C<on_refresh_begin>. 178Called just after the screen gets redrawn. See C<on_refresh_begin>.
110 179
180=item on_keyboard_command $term, $string
181
182Called whenever the user presses a key combination that has a
183C<perl:string> action bound to it (see description of the B<keysym>
184resource in the @@RXVT_NAME@@(1) manpage).
185
111=back 186=back
112 187
113=head2 Functions in the C<urxvt> Package 188=head2 Functions in the C<urxvt> Package
114 189
115=over 4 190=over 4
120costs! The only time this is acceptable is when the terminal process 195costs! The only time this is acceptable is when the terminal process
121starts up. 196starts up.
122 197
123=item urxvt::warn $string 198=item urxvt::warn $string
124 199
125Calls C<rxvt_warn> witht eh given string which should not include a 200Calls C<rxvt_warn> with the given string which should not include a
126newline. The module also overwrites the C<warn> builtin with a function 201newline. The module also overwrites the C<warn> builtin with a function
127that calls this function. 202that calls this function.
128 203
129Using this function has the advantage that its output ends up in the 204Using this function has the advantage that its output ends up in the
130correct place, e.g. on stderr of the connecting urxvtc client. 205correct place, e.g. on stderr of the connecting urxvtc client.
131 206
132=item $cellwidth = urxvt::wcswidth $string
133
134Returns the number of screen-cells this string would need. Correctly
135accounts for wide and combining characters.
136
137=item $time = urxvt::NOW 207=item $time = urxvt::NOW
138 208
139Returns the "current time" (as per the event loop). 209Returns the "current time" (as per the event loop).
210
211=back
212
213=head2 RENDITION
214
215Rendition bitsets contain information about colour, font, font styles and
216similar information for each screen cell.
217
218The following "macros" deal with changes in rendition sets. You should
219never just create a bitset, you should always modify an existing one,
220as they contain important information required for correct operation of
221rxvt-unicode.
222
223=over 4
224
225=item $rend = urxvt::DEFAULT_RSTYLE
226
227Returns the default rendition, as used when the terminal is starting up or
228being reset. Useful as a base to start when creating renditions.
229
230=item $rend = urxvt::OVERLAY_RSTYLE
231
232Return the rendition mask used for overlays by default.
233
234=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
235
236Return the bit that enabled bold, italic, blink, reverse-video and
237underline, respectively. To enable such a style, just logically OR it into
238the bitset.
239
240=item $foreground = urxvt::GET_BASEFG $rend
241
242=item $background = urxvt::GET_BASEBG $rend
243
244Return the foreground/background colour index, respectively.
245
246=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
247
248=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
249
250Replace the foreground/background colour in the rendition mask with the
251specified one.
252
253=item $value = urxvt::GET_CUSTOM ($rend)
254
255Return the "custom" value: Every rendition has 5 bits for use by
256extensions. They can be set and changed as you like and are initially
257zero.
258
259=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
260
261Change the custom value.
262
263=back
140 264
141=cut 265=cut
142 266
143package urxvt; 267package urxvt;
144 268
158 unless $msg =~ /\n$/; 282 unless $msg =~ /\n$/;
159 urxvt::warn ($msg); 283 urxvt::warn ($msg);
160 }; 284 };
161} 285}
162 286
287my @hook_count;
163my $verbosity = $ENV{URXVT_PERL_VERBOSITY} || 10; 288my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
164 289
165sub verbose { 290sub verbose {
166 my ($level, $msg) = @_; 291 my ($level, $msg) = @_;
167 warn "$msg\n"; #d# 292 warn "$msg\n" if $level <= $verbosity;
168} 293}
169 294
170my @invoke_cb; 295# find on_xxx subs in the package and register them
296# as hooks
297sub register_package($) {
298 my ($pkg) = @_;
299
300 for my $htype (0.. $#HOOKNAME) {
301 my $name = $HOOKNAME[$htype];
302
303 my $ref = $pkg->can ("on_" . lc $name)
304 or next;
305
306 $term->{_hook}[$htype]{$ref*1} = $ref;
307 $hook_count[$htype]++
308 or set_should_invoke $htype, 1;
309 }
310}
311
312my $script_pkg = "script0000";
313my %script_pkg;
314
315# load a single script into its own package, once only
316sub script_package($) {
317 my ($path) = @_;
318
319 $script_pkg{$path} ||= do {
320 my $pkg = "urxvt::" . ($script_pkg++);
321
322 verbose 3, "loading script '$path' into package '$pkg'";
323
324 open my $fh, "<:raw", $path
325 or die "$path: $!";
326
327 my $source = "package $pkg; use strict; use utf8;\n"
328 . "#line 1 \"$path\"\n{\n"
329 . (do { local $/; <$fh> })
330 . "\n};\n1";
331
332 eval $source or die "$path: $@";
333
334 $pkg
335 }
336}
171 337
172# called by the rxvt core 338# called by the rxvt core
173sub invoke { 339sub invoke {
174 local $term = shift; 340 local $term = shift;
175 my $htype = shift; 341 my $htype = shift;
176 342
177 my $cb = $invoke_cb[$htype]; 343 if ($htype == 0) { # INIT
344 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");
345
346 for my $ext (split /:/, $term->resource ("perl_ext")) {
347 my @files = grep -f $_, map "$_/$ext", @dirs;
348
349 if (@files) {
350 register_package script_package $files[0];
351 } else {
352 warn "perl extension '$ext' not found in perl library search path\n";
353 }
354 }
355
356 } elsif ($htype == 1) { # DESTROY
357 if (my $hook = $term->{_hook}) {
358 for my $htype (0..$#$hook) {
359 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
360 or set_should_invoke $htype, 0;
361 }
362 }
363 }
364
365 my $cb = $term->{_hook}[$htype]
366 or return;
178 367
179 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 368 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
180 if $verbosity >= 10; 369 if $verbosity >= 10;
181 370
182 while (my ($k, $v) = each %$cb) { 371 while (my ($k, $v) = each %$cb) {
183 return 1 if $v->($term, @_); 372 return 1 if $v->($term, @_);
184 } 373 }
185 374
186 0 375 0
187} 376}
188
189# find on_xxx subs in the package and register them
190# as hooks
191sub register_package($) {
192 my ($pkg) = @_;
193
194 for my $hook (0.. $#HOOKNAME) {
195 my $name = $HOOKNAME[$hook];
196
197 my $ref = $pkg->can ("on_" . lc $name)
198 or next;
199
200 $invoke_cb[$hook]{$ref*1} = $ref;
201 set_should_invoke $hook, 1;
202 }
203}
204
205my $script_pkg = "script0000";
206my %script_pkg;
207
208# load a single script into its own package, once only
209sub load_script($) {
210 my ($path) = @_;
211
212 $script_pkg{$path} ||= do {
213 my $pkg = $script_pkg++;
214 verbose 3, "loading script '$path' into package '$pkg'";
215
216 open my $fh, "<:raw", $path
217 or die "$path: $!";
218
219 eval "package $pkg; use strict; use utf8;\n"
220 . "#line 1 \"$path\"\n"
221 . do { local $/; <$fh> }
222 or die "$path: $@";
223
224 register_package $pkg;
225
226 $pkg
227 };
228}
229
230load_script $_ for grep -f $_, <$LIBDIR/perl-ext/*>;
231
232=back
233 377
234=head2 The C<urxvt::term> Class 378=head2 The C<urxvt::term> Class
235 379
236=over 4 380=over 4
237 381
258 402
259 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 403 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
260 borderLess color cursorBlink cursorUnderline cutchars delete_key 404 borderLess color cursorBlink cursorUnderline cutchars delete_key
261 display_name embed ext_bwidth fade font geometry hold iconName 405 display_name embed ext_bwidth fade font geometry hold iconName
262 imFont imLocale inputMethod insecure int_bwidth intensityStyles 406 imFont imLocale inputMethod insecure int_bwidth intensityStyles
263 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 407 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
264 modifier mouseWheelScrollPage name pastableTabs path pointerBlank 408 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
265 pointerBlankDelay preeditType print_pipe pty_fd reverseVideo saveLines 409 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
266 scrollBar scrollBar_align scrollBar_floating scrollBar_right 410 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
267 scrollBar_thickness scrollTtyKeypress scrollTtyOutput scrollWithBuffer 411 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
268 scrollstyle secondaryScreen secondaryScroll selectstyle shade term_name 412 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
269 title transparent transparent_all tripleclickwords utmpInhibit 413 shade term_name title transparent transparent_all tripleclickwords
270 visualBell 414 utmpInhibit visualBell
271 415
272=cut 416=cut
273 417
274sub urxvt::term::resource($$;$) { 418sub urxvt::term::resource($$;$) {
275 my ($self, $name) = (shift, shift); 419 my ($self, $name) = (shift, shift);
293 437
294=item $oldtext = $term->selection ([$newtext]) 438=item $oldtext = $term->selection ([$newtext])
295 439
296Return the current selection text and optionally replace it by C<$newtext>. 440Return the current selection text and optionally replace it by C<$newtext>.
297 441
298=item $term->scr_overlay ($x, $y, $text) 442#=item $term->overlay ($x, $y, $text)
299 443#
300Create a simple multi-line overlay box. See the next method for details. 444#Create a simple multi-line overlay box. See the next method for details.
301 445#
302=cut 446#=cut
303 447
304sub urxvt::term::scr_overlay { 448sub urxvt::term::scr_overlay {
449die;
305 my ($self, $x, $y, $text) = @_; 450 my ($self, $x, $y, $text) = @_;
306 451
307 my @lines = split /\n/, $text; 452 my @lines = split /\n/, $text;
308 453
309 my $w = 0; 454 my $w = 0;
310 for (map urxvt::wcswidth $_, @lines) { 455 for (map $self->strwidth ($_), @lines) {
311 $w = $_ if $w < $_; 456 $w = $_ if $w < $_;
312 } 457 }
313 458
314 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 459 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
315 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 460 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
316} 461}
317 462
318=item $term->scr_overlay_new ($x, $y, $width, $height) 463=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
319 464
320Create a new (empty) overlay at the given position with the given 465Create a new (empty) overlay at the given position with the given
321width/height. A border will be put around the box. If either C<$x> or 466width/height. C<$rstyle> defines the initial rendition style
322C<$y> is negative, then this is counted from the right/bottom side, 467(default: C<OVERLAY_RSTYLE>).
323respectively.
324 468
325=item $term->scr_overlay_off 469If C<$border> is C<2> (default), then a decorative border will be put
470around the box.
326 471
327Switch the overlay off again. 472If either C<$x> or C<$y> is negative, then this is counted from the
473right/bottom side, respectively.
328 474
329=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 475This method returns an urxvt::overlay object. The overlay will be visible
476as long as the perl object is referenced.
330 477
331Put a single character (specified numerically) at the given overlay 478The methods currently supported on C<urxvt::overlay> objects are:
332position.
333 479
480=over 4
481
334=item $term->scr_overlay_set ($x, $y, $text) 482=item $overlay->set ($x, $y, $text, $rend)
335 483
336Write a string at the given position into the overlay. 484Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
485text in rxvt-unicode's special encoding and an array of rendition values
486at a specific position inside the overlay.
487
488=item $overlay->hide
489
490If visible, hide the overlay, but do not destroy it.
491
492=item $overlay->show
493
494If hidden, display the overlay again.
495
496=back
497
498=item $cellwidth = $term->strwidth $string
499
500Returns the number of screen-cells this string would need. Correctly
501accounts for wide and combining characters.
502
503=item $octets = $term->locale_encode $string
504
505Convert the given text string into the corresponding locale encoding.
506
507=item $string = $term->locale_decode $octets
508
509Convert the given locale-encoded octets into a perl string.
510
511=item $term->tt_write ($octets)
512
513Write the octets given in C<$data> to the tty (i.e. as program input). To
514pass characters instead of octets, you should convert your strings first
515to the locale-specific encoding using C<< $term->locale_encode >>.
516
517=item $nrow = $term->nrow
518
519=item $ncol = $term->ncol
520
521Return the number of rows/columns of the terminal window (i.e. as
522specified by C<-geometry>, excluding any scrollback).
523
524=item $nsaved = $term->nsaved
525
526Returns the number of lines in the scrollback buffer.
527
528=item $view_start = $term->view_start ([$newvalue])
529
530Returns the negative row number of the topmost line. Minimum value is
531C<0>, which displays the normal terminal contents. Larger values scroll
532this many lines into the scrollback buffer.
533
534=item $term->want_refresh
535
536Requests a screen refresh. At the next opportunity, rxvt-unicode will
537compare the on-screen display with its stored representation. If they
538differ, it redraws the differences.
539
540Used after changing terminal contents to display them.
541
542=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
543
544Returns the text of the entire row with number C<$row_number>. Row C<0>
545is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
546terminal line. The scrollback buffer starts at line C<-1> and extends to
547line C<< -$term->nsaved >>.
548
549If C<$new_text> is specified, it will replace characters in the current
550line, starting at column C<$start_col> (default C<0>), which is useful
551to replace only parts of a line. The font index in the rendition will
552automatically be updated.
553
554C<$text> is in a special encoding: tabs and wide characters that use more
555than one cell when displayed are padded with urxvt::NOCHAR characters
556(C<chr 65535>). Characters with combining characters and other characters
557that do not fit into the normal tetx encoding will be replaced with
558characters in the private use area.
559
560You have to obey this encoding when changing text. The advantage is
561that C<substr> and similar functions work on screen cells and not on
562characters.
563
564The methods C<< $term->special_encode >> and C<< $term->special_decode >>
565can be used to convert normal strings into this encoding and vice versa.
566
567=item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
568
569Like C<< $term->ROW_t >>, but returns an arrayref with rendition
570bitsets. Rendition bitsets contain information about colour, font, font
571styles and similar information. See also C<< $term->ROW_t >>.
572
573When setting rendition, the font mask will be ignored.
574
575See the section on RENDITION, above.
576
577=item $length = $term->ROW_l ($row_number[, $new_length])
578
579Returns the number of screen cells that are in use ("the line length"). If
580it is C<-1>, then the line is part of a multiple-row logical "line", which
581means all characters are in use and it is continued on the next row.
582
583=item $text = $term->special_encode $string
584
585Converts a perl string into the special encoding used by rxvt-unicode,
586where one character corresponds to one screen cell. See
587C<< $term->ROW_t >> for details.
588
589=item $string = $term->special_decode $text
590
591Converts rxvt-unicodes text reprsentation into a perl string. See
592C<< $term->ROW_t >> for details.
337 593
338=back 594=back
339 595
340=head2 The C<urxvt::timer> Class 596=head2 The C<urxvt::timer> Class
341 597
342This class implements timer watchers/events. Time is represented as a 598This class implements timer watchers/events. Time is represented as a
343fractional number of seconds since the epoch. Example: 599fractional number of seconds since the epoch. Example:
344 600
345 # create a digital clock display in upper right corner 601 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
346 $term->{timer} = urxvt::timer 602 $term->{timer} = urxvt::timer
347 ->new 603 ->new
348 ->start (urxvt::NOW) 604 ->interval (1)
349 ->cb (sub { 605 ->cb (sub {
350 my ($timer) = @_;
351 my $time = $timer->at;
352 $timer->start ($time + 1);
353 $self->scr_overlay (-1, 0, 606 $term->{overlay}->set (0, 0,
354 POSIX::strftime "%H:%M:%S", localtime $time); 607 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
355 }); 608 });
356 609
357=over 4 610=over 4
358 611
359=item $timer = new urxvt::timer 612=item $timer = new urxvt::timer
360 613
361Create a new timer object in stopped state. 614Create a new timer object in started state. It is scheduled to fire
615immediately.
362 616
363=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 617=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
364 618
365Set the callback to be called when the timer triggers. 619Set the callback to be called when the timer triggers.
366 620
369Return the time this watcher will fire next. 623Return the time this watcher will fire next.
370 624
371=item $timer = $timer->set ($tstamp) 625=item $timer = $timer->set ($tstamp)
372 626
373Set the time the event is generated to $tstamp. 627Set the time the event is generated to $tstamp.
628
629=item $timer = $timer->interval ($interval)
630
631Normally (and when C<$interval> is C<0>), the timer will automatically
632stop after it has fired once. If C<$interval> is non-zero, then the timer
633is automatically rescheduled at the given intervals.
374 634
375=item $timer = $timer->start 635=item $timer = $timer->start
376 636
377Start the timer. 637Start the timer.
378 638

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines