ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.txt
Revision: 1.8
Committed: Tue Jan 3 23:41:37 2006 UTC (18 years, 6 months ago) by root
Content type: text/plain
Branch: MAIN
Changes since 1.7: +7 -5 lines
Log Message:
*** empty log message ***

File Contents

# Content
1 NAME
2 rxvtperl - rxvt-unicode's embedded perl interpreter
3
4 SYNOPSIS
5 # create a file grab_test in $HOME:
6
7 sub on_sel_grab {
8 warn "you selected ", $_[0]->selection;
9 ()
10 }
11
12 # start a rxvt using it:
13
14 rxvt --perl-lib $HOME -pe grab_test
15
16 DESCRIPTION
17 Everytime a terminal object gets created, scripts specified via the
18 "perl" resource are loaded and associated with it.
19
20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21 thus must be encoded as UTF-8.
22
23 Each script will only ever be loaded once, even in rxvtd, where scripts
24 will be shared (but not enabled) for all terminals.
25
26 Prepackaged Extensions
27 This section describes the extensiosn delivered with this version. You
28 can find them in /opt/rxvt/lib/urxvt/perl/.
29
30 You can activate them like this:
31
32 rxvt -pe <extensionname>
33
34 selection
35 Intelligent selection. This extension tries to be more intelligent
36 when the user extends selections (double-click). Right now, it tries
37 to select urls and complete shell-quoted arguments, which is very
38 convenient, too, if your ls supports "--quoting-style=shell".
39
40 It also offers the following bindable event:
41
42 rot13
43 Rot-13 the selection when activated. Used via keyboard trigger:
44
45 URxvt.keysym.C-M-r: perl:selection:rot13
46
47 digital-clock
48 Displays a digital clock using the built-in overlay.
49
50 example-refresh-hooks
51 Displays a very simple digital clock in the upper right corner of
52 the window. Illustrates overwriting the refresh callbacks to create
53 your own overlays or changes.
54
55 General API Considerations
56 All objects (such as terminals, time watchers etc.) are typical
57 reference-to-hash objects. The hash can be used to store anything you
58 like. All members starting with an underscore (such as "_ptr" or
59 "_hook") are reserved for internal uses and MUST NOT be accessed or
60 modified).
61
62 When objects are destroyed on the C++ side, the perl object hashes are
63 emptied, so its best to store related objects such as time watchers and
64 the like inside the terminal object so they get destroyed as soon as the
65 terminal is destroyed.
66
67 Hooks
68 The following subroutines can be declared in loaded scripts, and will be
69 called whenever the relevant event happens.
70
71 The first argument passed to them is an object private to each terminal
72 and extension package. You can call all "urxvt::term" methods on it, but
73 its not a real "urxvt::term" object. Instead, the real "urxvt::term"
74 object that is shared between all packages is stored in the "term"
75 member.
76
77 All of them must return a boolean value. If it is true, then the event
78 counts as being *consumed*, and the invocation of other hooks is
79 skipped, and the relevant action might not be carried out by the C++
80 code.
81
82 When in doubt, return a false value (preferably "()").
83
84 on_init $term
85 Called after a new terminal object has been initialized, but before
86 windows are created or the command gets run.
87
88 on_reset $term
89 Called after the screen is "reset" for any reason, such as resizing
90 or control sequences. Here is where you can react on changes to
91 size-related variables.
92
93 on_start $term
94 Called at the very end of initialisation of a new terminal, just
95 before returning to the mainloop.
96
97 on_sel_make $term, $eventtime
98 Called whenever a selection has been made by the user, but before
99 the selection text is copied, so changes to the beginning, end or
100 type of the selection will be honored.
101
102 Returning a true value aborts selection making by urxvt, in which
103 case you have to make a selection yourself by calling
104 "$term->selection_grab".
105
106 on_sel_grab $term, $eventtime
107 Called whenever a selection has been copied, but before the
108 selection is requested from the server. The selection text can be
109 queried and changed by calling "$term->selection".
110
111 Returning a true value aborts selection grabbing. It will still be
112 hilighted.
113
114 on_sel_extend $term
115 Called whenever the user tries to extend the selection (e.g. with a
116 double click) and is either supposed to return false (normal
117 operation), or should extend the selection itelf and return true to
118 suppress the built-in processing.
119
120 See the selection example extension.
121
122 on_focus_in $term
123 Called whenever the window gets the keyboard focus, before urxvt
124 does focus in processing.
125
126 on_focus_out $term
127 Called wheneever the window loses keyboard focus, before urxvt does
128 focus out processing.
129
130 on_view_change $term, $offset
131 Called whenever the view offset changes, i..e the user or program
132 scrolls. Offset 0 means display the normal terminal, positive values
133 show this many lines of scrollback.
134
135 on_scroll_back $term, $lines, $saved
136 Called whenever lines scroll out of the terminal area into the
137 scrollback buffer. $lines is the number of lines scrolled out and
138 may be larger than the scroll back buffer or the terminal.
139
140 It is called before lines are scrolled out (so rows 0 .. min ($lines
141 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
142 the total number of lines that will be in the scrollback buffer.
143
144 on_tty_activity $term *NYI*
145 Called whenever the program(s) running in the urxvt window send
146 output.
147
148 on_refresh_begin $term
149 Called just before the screen gets redrawn. Can be used for overlay
150 or similar effects by modify terminal contents in refresh_begin, and
151 restoring them in refresh_end. The built-in overlay and selection
152 display code is run after this hook, and takes precedence.
153
154 on_refresh_end $term
155 Called just after the screen gets redrawn. See "on_refresh_begin".
156
157 on_keyboard_command $term, $string
158 Called whenever the user presses a key combination that has a
159 "perl:string" action bound to it (see description of the keysym
160 resource in the rxvt(1) manpage).
161
162 Variables in the "urxvt" Package
163 $urxvt::TERM
164 The current terminal. Whenever a callback/Hook is bein executed,
165 this variable stores the current "urxvt::term" object.
166
167 Functions in the "urxvt" Package
168 urxvt::fatal $errormessage
169 Fatally aborts execution with the given error message. Avoid at all
170 costs! The only time this is acceptable is when the terminal process
171 starts up.
172
173 urxvt::warn $string
174 Calls "rxvt_warn" with the given string which should not include a
175 newline. The module also overwrites the "warn" builtin with a
176 function that calls this function.
177
178 Using this function has the advantage that its output ends up in the
179 correct place, e.g. on stderr of the connecting urxvtc client.
180
181 $time = urxvt::NOW
182 Returns the "current time" (as per the event loop).
183
184 RENDITION
185 Rendition bitsets contain information about colour, font, font styles
186 and similar information for each screen cell.
187
188 The following "macros" deal with changes in rendition sets. You should
189 never just create a bitset, you should always modify an existing one, as
190 they contain important information required for correct operation of
191 rxvt-unicode.
192
193 $rend = urxvt::DEFAULT_RSTYLE
194 Returns the default rendition, as used when the terminal is starting
195 up or being reset. Useful as a base to start when creating
196 renditions.
197
198 $rend = urxvt::OVERLAY_RSTYLE
199 Return the rendition mask used for overlays by default.
200
201 $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
202 Return the bit that enabled bold, italic, blink, reverse-video and
203 underline, respectively. To enable such a style, just logically OR
204 it into the bitset.
205
206 $foreground = urxvt::GET_BASEFG $rend
207 $background = urxvt::GET_BASEBG $rend
208 Return the foreground/background colour index, respectively.
209
210 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
211 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
212 Replace the foreground/background colour in the rendition mask with
213 the specified one.
214
215 $value = urxvt::GET_CUSTOM ($rend)
216 Return the "custom" value: Every rendition has 5 bits for use by
217 extensions. They can be set and changed as you like and are
218 initially zero.
219
220 $rend = urxvt::SET_CUSTOM ($rend, $new_value)
221 Change the custom value.
222
223 The "urxvt::term" Class
224 $value = $term->resource ($name[, $newval])
225 Returns the current resource value associated with a given name and
226 optionally sets a new value. Setting values is most useful in the
227 "init" hook. Unset resources are returned and accepted as "undef".
228
229 The new value must be properly encoded to a suitable character
230 encoding before passing it to this method. Similarly, the returned
231 value may need to be converted from the used encoding to text.
232
233 Resource names are as defined in src/rsinc.h. Colours can be
234 specified as resource names of the form "color+<index>", e.g.
235 "color+5". (will likely change).
236
237 Please note that resource strings will currently only be freed when
238 the terminal is destroyed, so changing options frequently will eat
239 memory.
240
241 Here is a a likely non-exhaustive list of resource names, not all of
242 which are supported in every build, please see the source to see the
243 actual list:
244
245 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
246 borderLess color cursorBlink cursorUnderline cutchars delete_key
247 display_name embed ext_bwidth fade font geometry hold iconName
248 imFont imLocale inputMethod insecure int_bwidth intensityStyles
249 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
250 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
251 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
252 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
253 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
254 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
255 shade term_name title transparent transparent_all tripleclickwords
256 utmpInhibit visualBell
257
258 ($row, $col) = $term->selection_mark ([$row, $col])
259 ($row, $col) = $term->selection_beg ([$row, $col])
260 ($row, $col) = $term->selection_end ([$row, $col])
261 Return the current values of the selection mark, begin or end
262 positions, and optionally set them to new values.
263
264 $success = $term->selection_grab ($eventtime)
265 Try to request the primary selection from the server (for example,
266 as set by the next method).
267
268 $oldtext = $term->selection ([$newtext])
269 Return the current selection text and optionally replace it by
270 $newtext.
271
272 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
273 overlay box. See the next method for details. # #=cut
274
275 sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;
276
277 my @lines = split /\n/, $text;
278
279 my $w = 0;
280 for (map $self->strwidth ($_), @lines) {
281 $w = $_ if $w < $_;
282 }
283
284 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
285 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
286 }
287
288 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
289 Create a new (empty) overlay at the given position with the given
290 width/height. $rstyle defines the initial rendition style (default:
291 "OVERLAY_RSTYLE").
292
293 If $border is 2 (default), then a decorative border will be put
294 around the box.
295
296 If either $x or $y is negative, then this is counted from the
297 right/bottom side, respectively.
298
299 This method returns an urxvt::overlay object. The overlay will be
300 visible as long as the perl object is referenced.
301
302 The methods currently supported on "urxvt::overlay" objects are:
303
304 $overlay->set ($x, $y, $text, $rend)
305 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
306 text in rxvt-unicode's special encoding and an array of
307 rendition values at a specific position inside the overlay.
308
309 $overlay->hide
310 If visible, hide the overlay, but do not destroy it.
311
312 $overlay->show
313 If hidden, display the overlay again.
314
315 $cellwidth = $term->strwidth $string
316 Returns the number of screen-cells this string would need. Correctly
317 accounts for wide and combining characters.
318
319 $octets = $term->locale_encode $string
320 Convert the given text string into the corresponding locale
321 encoding.
322
323 $string = $term->locale_decode $octets
324 Convert the given locale-encoded octets into a perl string.
325
326 $term->tt_write ($octets)
327 Write the octets given in $data to the tty (i.e. as program input).
328 To pass characters instead of octets, you should convert your
329 strings first to the locale-specific encoding using
330 "$term->locale_encode".
331
332 $nrow = $term->nrow
333 $ncol = $term->ncol
334 Return the number of rows/columns of the terminal window (i.e. as
335 specified by "-geometry", excluding any scrollback).
336
337 $nsaved = $term->nsaved
338 Returns the number of lines in the scrollback buffer.
339
340 $view_start = $term->view_start ([$newvalue])
341 Returns the negative row number of the topmost line. Minimum value
342 is 0, which displays the normal terminal contents. Larger values
343 scroll this many lines into the scrollback buffer.
344
345 $term->want_refresh
346 Requests a screen refresh. At the next opportunity, rxvt-unicode
347 will compare the on-screen display with its stored representation.
348 If they differ, it redraws the differences.
349
350 Used after changing terminal contents to display them.
351
352 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
353 Returns the text of the entire row with number $row_number. Row 0 is
354 the topmost terminal line, row "$term->$ncol-1" is the bottommost
355 terminal line. The scrollback buffer starts at line -1 and extends
356 to line "-$term->nsaved". Nothing will be returned if a nonexistent
357 line is requested.
358
359 If $new_text is specified, it will replace characters in the current
360 line, starting at column $start_col (default 0), which is useful to
361 replace only parts of a line. The font index in the rendition will
362 automatically be updated.
363
364 $text is in a special encoding: tabs and wide characters that use
365 more than one cell when displayed are padded with urxvt::NOCHAR
366 characters ("chr 65535"). Characters with combining characters and
367 other characters that do not fit into the normal tetx encoding will
368 be replaced with characters in the private use area.
369
370 You have to obey this encoding when changing text. The advantage is
371 that "substr" and similar functions work on screen cells and not on
372 characters.
373
374 The methods "$term->special_encode" and "$term->special_decode" can
375 be used to convert normal strings into this encoding and vice versa.
376
377 $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
378 Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
379 Rendition bitsets contain information about colour, font, font
380 styles and similar information. See also "$term->ROW_t".
381
382 When setting rendition, the font mask will be ignored.
383
384 See the section on RENDITION, above.
385
386 $length = $term->ROW_l ($row_number[, $new_length])
387 Returns the number of screen cells that are in use ("the line
388 length"). Unlike the urxvt core, this returns "$term->ncol" if the
389 line is joined with the following one.
390
391 $bool = $term->is_longer ($row_number)
392 Returns true if the row is part of a multiple-row logical "line"
393 (i.e. joined with the following row), which means all characters are
394 in use and it is continued on the next row (and possibly a
395 continuation of the previous row(s)).
396
397 $line = $term->line ($row_number)
398 Create and return a new "urxvt::line" object that stores information
399 about the logical line that row $row_number is part of. It supports
400 the following methods:
401
402 $text = $line->t
403 Returns the full text of the line, similar to "ROW_t"
404
405 $rend = $line->r
406 Returns the full rendition array of the line, similar to "ROW_r"
407
408 $length = $line->l
409 Returns the length of the line in cells, similar to "ROW_l".
410
411 $rownum = $line->beg
412 $rownum = $line->end
413 Return the row number of the first/last row of the line,
414 respectively.
415
416 $offset = $line->offset_of ($row, $col)
417 Returns the character offset of the given row|col pair within
418 the logical line.
419
420 ($row, $col) = $line->coord_of ($offset)
421 Translates a string offset into terminal coordinates again.
422
423 ($row, $col) = $line->coord_of ($offset) =item $text =
424 $term->special_encode $string
425 Converts a perl string into the special encoding used by
426 rxvt-unicode, where one character corresponds to one screen cell.
427 See "$term->ROW_t" for details.
428
429 $string = $term->special_decode $text
430 Converts rxvt-unicodes text reprsentation into a perl string. See
431 "$term->ROW_t" for details.
432
433 The "urxvt::timer" Class
434 This class implements timer watchers/events. Time is represented as a
435 fractional number of seconds since the epoch. Example:
436
437 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
438 $term->{timer} = urxvt::timer
439 ->new
440 ->interval (1)
441 ->cb (sub {
442 $term->{overlay}->set (0, 0,
443 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
444 });
445
446 $timer = new urxvt::timer
447 Create a new timer object in started state. It is scheduled to fire
448 immediately.
449
450 $timer = $timer->cb (sub { my ($timer) = @_; ... })
451 Set the callback to be called when the timer triggers.
452
453 $tstamp = $timer->at
454 Return the time this watcher will fire next.
455
456 $timer = $timer->set ($tstamp)
457 Set the time the event is generated to $tstamp.
458
459 $timer = $timer->interval ($interval)
460 Normally (and when $interval is 0), the timer will automatically
461 stop after it has fired once. If $interval is non-zero, then the
462 timer is automatically rescheduled at the given intervals.
463
464 $timer = $timer->start
465 Start the timer.
466
467 $timer = $timer->start ($tstamp)
468 Set the event trigger time to $tstamp and start the timer.
469
470 $timer = $timer->stop
471 Stop the timer.
472
473 The "urxvt::iow" Class
474 This class implements io watchers/events. Example:
475
476 $term->{socket} = ...
477 $term->{iow} = urxvt::iow
478 ->new
479 ->fd (fileno $term->{socket})
480 ->events (1) # wait for read data
481 ->start
482 ->cb (sub {
483 my ($iow, $revents) = @_;
484 # $revents must be 1 here, no need to check
485 sysread $term->{socket}, my $buf, 8192
486 or end-of-file;
487 });
488
489 $iow = new urxvt::iow
490 Create a new io watcher object in stopped state.
491
492 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
493 Set the callback to be called when io events are triggered.
494 $reventmask is a bitset as described in the "events" method.
495
496 $iow = $iow->fd ($fd)
497 Set the filedescriptor (not handle) to watch.
498
499 $iow = $iow->events ($eventmask)
500 Set the event mask to watch. Bit #0 (value 1) enables watching for
501 read data, Bit #1 (value 2) enables watching for write data.
502
503 $iow = $iow->start
504 Start watching for requested events on the given handle.
505
506 $iow = $iow->stop
507 Stop watching for events on the given filehandle.
508
509 ENVIRONMENT
510 URXVT_PERL_VERBOSITY
511 This variable controls the verbosity level of the perl extension. Higher
512 numbers indicate more verbose output.
513
514 =0 - only fatal messages
515 =3 - script loading and management
516 =10 - all events received
517
518 AUTHOR
519 Marc Lehmann <pcg@goof.com>
520 http://software.schmorp.de/pkg/rxvt-unicode
521