ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.txt
(Generate patch)

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.1 by root, Mon Jan 2 19:36:07 2006 UTC vs.
Revision 1.8 by root, Tue Jan 3 23:41:37 2006 UTC

1NAME 1NAME
2 rxvtperl - rxvt-unicode's embedded perl interpreter 2 rxvtperl - rxvt-unicode's embedded perl interpreter
3 3
4SYNOPSIS 4SYNOPSIS
5 * Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be 5 # create a file grab_test in $HOME:
6 loaded automatically.
7
8 * Scripts are evaluated in a 'use strict' and 'use utf8' environment,
9 and thus must be encoded as UTF-8.
10 6
11 sub on_sel_grab { 7 sub on_sel_grab {
12 warn "you selected ", $_[0]->selection; 8 warn "you selected ", $_[0]->selection;
13 () 9 ()
14 } 10 }
15 11
16 1 12 # start a rxvt using it:
13
14 rxvt --perl-lib $HOME -pe grab_test
17 15
18DESCRIPTION 16DESCRIPTION
19 On startup, rxvt will scan /opt/rxvt/lib/urxvt/perl-ext/ for files and 17 Everytime a terminal object gets created, scripts specified via the
20 will load them. Everytime a terminal object gets created, the directory 18 "perl" resource are loaded and associated with it.
21 specified by the "perl-lib" resource will be additionally scanned. 19
20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21 thus must be encoded as UTF-8.
22 22
23 Each script will only ever be loaded once, even in rxvtd, where scripts 23 Each script will only ever be loaded once, even in rxvtd, where scripts
24 will be shared for all terminals. 24 will be shared (but not enabled) for all terminals.
25 25
26 Hooks in scripts specified by "perl-lib" will only be called for the 26 Prepackaged Extensions
27 terminals created with that specific option value. 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.
28 54
29 General API Considerations 55 General API Considerations
30 All objects (such as terminals, time watchers etc.) are typical 56 All objects (such as terminals, time watchers etc.) are typical
31 reference-to-hash objects. The hash can be used to store anything you 57 reference-to-hash objects. The hash can be used to store anything you
32 like. All members starting with an underscore (such as "_ptr" or 58 like. All members starting with an underscore (such as "_ptr" or
33 "_hook") are reserved for internal uses and must not be accessed or 59 "_hook") are reserved for internal uses and MUST NOT be accessed or
34 modified). 60 modified).
35 61
36 When objects are destroyed on the C++ side, the perl object hashes are 62 When objects are destroyed on the C++ side, the perl object hashes are
37 emptied, so its best to store related objects such as time watchers and 63 emptied, so its best to store related objects such as time watchers and
38 the like inside the terminal object so they get destroyed as soon as the 64 the like inside the terminal object so they get destroyed as soon as the
… …
40 66
41 Hooks 67 Hooks
42 The following subroutines can be declared in loaded scripts, and will be 68 The following subroutines can be declared in loaded scripts, and will be
43 called whenever the relevant event happens. 69 called whenever the relevant event happens.
44 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
45 All of them must return a boolean value. If it is true, then the event 77 All of them must return a boolean value. If it is true, then the event
46 counts as being *consumed*, and the invocation of other hooks is 78 counts as being *consumed*, and the invocation of other hooks is
47 skipped, and the relevant action might not be carried out by the C++ 79 skipped, and the relevant action might not be carried out by the C++
48 code. 80 code.
49 81
… …
76 selection is requested from the server. The selection text can be 108 selection is requested from the server. The selection text can be
77 queried and changed by calling "$term->selection". 109 queried and changed by calling "$term->selection".
78 110
79 Returning a true value aborts selection grabbing. It will still be 111 Returning a true value aborts selection grabbing. It will still be
80 hilighted. 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.
81 121
82 on_focus_in $term 122 on_focus_in $term
83 Called whenever the window gets the keyboard focus, before urxvt 123 Called whenever the window gets the keyboard focus, before urxvt
84 does focus in processing. 124 does focus in processing.
85 125
… …
112 display code is run after this hook, and takes precedence. 152 display code is run after this hook, and takes precedence.
113 153
114 on_refresh_end $term 154 on_refresh_end $term
115 Called just after the screen gets redrawn. See "on_refresh_begin". 155 Called just after the screen gets redrawn. See "on_refresh_begin".
116 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
117 Functions in the "urxvt" Package 167 Functions in the "urxvt" Package
118 urxvt::fatal $errormessage 168 urxvt::fatal $errormessage
119 Fatally aborts execution with the given error message. Avoid at all 169 Fatally aborts execution with the given error message. Avoid at all
120 costs! The only time this is acceptable is when the terminal process 170 costs! The only time this is acceptable is when the terminal process
121 starts up. 171 starts up.
… …
129 correct place, e.g. on stderr of the connecting urxvtc client. 179 correct place, e.g. on stderr of the connecting urxvtc client.
130 180
131 $time = urxvt::NOW 181 $time = urxvt::NOW
132 Returns the "current time" (as per the event loop). 182 Returns the "current time" (as per the event loop).
133 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
134 The "urxvt::term" Class 223 The "urxvt::term" Class
135 $value = $term->resource ($name[, $newval]) 224 $value = $term->resource ($name[, $newval])
136 Returns the current resource value associated with a given name and 225 Returns the current resource value associated with a given name and
137 optionally sets a new value. Setting values is most useful in the 226 optionally sets a new value. Setting values is most useful in the
138 "init" hook. Unset resources are returned and accepted as "undef". 227 "init" hook. Unset resources are returned and accepted as "undef".
… …
155 244
156 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 245 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
157 borderLess color cursorBlink cursorUnderline cutchars delete_key 246 borderLess color cursorBlink cursorUnderline cutchars delete_key
158 display_name embed ext_bwidth fade font geometry hold iconName 247 display_name embed ext_bwidth fade font geometry hold iconName
159 imFont imLocale inputMethod insecure int_bwidth intensityStyles 248 imFont imLocale inputMethod insecure int_bwidth intensityStyles
160 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 249 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
161 modifier mouseWheelScrollPage name pastableTabs path perl perl_eval 250 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
162 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 251 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
163 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 252 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
164 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 253 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
165 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 254 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
166 shade term_name title transparent transparent_all tripleclickwords 255 shade term_name title transparent transparent_all tripleclickwords
… …
178 267
179 $oldtext = $term->selection ([$newtext]) 268 $oldtext = $term->selection ([$newtext])
180 Return the current selection text and optionally replace it by 269 Return the current selection text and optionally replace it by
181 $newtext. 270 $newtext.
182 271
183 $term->scr_overlay ($x, $y, $text) 272 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
184 Create a simple multi-line overlay box. See the next method for 273 overlay box. See the next method for details. # #=cut
185 details.
186 274
187 $term->scr_overlay_new ($x, $y, $width, $height) 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]])
188 Create a new (empty) overlay at the given position with the given 289 Create a new (empty) overlay at the given position with the given
189 width/height. A border will be put around the box. If either $x or 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
190 $y is negative, then this is counted from the right/bottom side, 296 If either $x or $y is negative, then this is counted from the
191 respectively. 297 right/bottom side, respectively.
192 298
193 $term->scr_overlay_off 299 This method returns an urxvt::overlay object. The overlay will be
194 Switch the overlay off again. 300 visible as long as the perl object is referenced.
195 301
196 $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 302 The methods currently supported on "urxvt::overlay" objects are:
197 Put a single character (specified numerically) at the given overlay
198 position.
199 303
200 $term->scr_overlay_set ($x, $y, $text) 304 $overlay->set ($x, $y, $text, $rend)
201 Write a string at the given position into the overlay. 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.
202 314
203 $cellwidth = $term->strwidth $string 315 $cellwidth = $term->strwidth $string
204 Returns the number of screen-cells this string would need. Correctly 316 Returns the number of screen-cells this string would need. Correctly
205 accounts for wide and combining characters. 317 accounts for wide and combining characters.
206 318
… …
211 $string = $term->locale_decode $octets 323 $string = $term->locale_decode $octets
212 Convert the given locale-encoded octets into a perl string. 324 Convert the given locale-encoded octets into a perl string.
213 325
214 $term->tt_write ($octets) 326 $term->tt_write ($octets)
215 Write the octets given in $data to the tty (i.e. as program input). 327 Write the octets given in $data to the tty (i.e. as program input).
216 To pass characters instead of octets, you should convetr you strings 328 To pass characters instead of octets, you should convert your
217 first to the locale-specific encoding using "$term->locale_encode". 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.
218 432
219 The "urxvt::timer" Class 433 The "urxvt::timer" Class
220 This class implements timer watchers/events. Time is represented as a 434 This class implements timer watchers/events. Time is represented as a
221 fractional number of seconds since the epoch. Example: 435 fractional number of seconds since the epoch. Example:
222 436
223 # create a digital clock display in upper right corner 437 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
224 $term->{timer} = urxvt::timer 438 $term->{timer} = urxvt::timer
225 ->new 439 ->new
226 ->start (urxvt::NOW) 440 ->interval (1)
227 ->cb (sub { 441 ->cb (sub {
228 my ($timer) = @_;
229 my $time = $timer->at;
230 $timer->start ($time + 1);
231 $self->scr_overlay (-1, 0, 442 $term->{overlay}->set (0, 0,
232 POSIX::strftime "%H:%M:%S", localtime $time); 443 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
233 }); 444 });
234 445
235 $timer = new urxvt::timer 446 $timer = new urxvt::timer
236 Create a new timer object in stopped state. 447 Create a new timer object in started state. It is scheduled to fire
448 immediately.
237 449
238 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 450 $timer = $timer->cb (sub { my ($timer) = @_; ... })
239 Set the callback to be called when the timer triggers. 451 Set the callback to be called when the timer triggers.
240 452
241 $tstamp = $timer->at 453 $tstamp = $timer->at
242 Return the time this watcher will fire next. 454 Return the time this watcher will fire next.
243 455
244 $timer = $timer->set ($tstamp) 456 $timer = $timer->set ($tstamp)
245 Set the time the event is generated to $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.
246 463
247 $timer = $timer->start 464 $timer = $timer->start
248 Start the timer. 465 Start the timer.
249 466
250 $timer = $timer->start ($tstamp) 467 $timer = $timer->start ($tstamp)
… …
292ENVIRONMENT 509ENVIRONMENT
293 URXVT_PERL_VERBOSITY 510 URXVT_PERL_VERBOSITY
294 This variable controls the verbosity level of the perl extension. Higher 511 This variable controls the verbosity level of the perl extension. Higher
295 numbers indicate more verbose output. 512 numbers indicate more verbose output.
296 513
297 0 - only fatal messages 514 =0 - only fatal messages
298 3 - script loading and management 515 =3 - script loading and management
299 10 - all events received 516 =10 - all events received
300 517
301AUTHOR 518AUTHOR
302 Marc Lehmann <pcg@goof.com> 519 Marc Lehmann <pcg@goof.com>
303 http://software.schmorp.de/pkg/rxvt-unicode 520 http://software.schmorp.de/pkg/rxvt-unicode
304 521

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines