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