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.6 by root, Tue Jan 3 04:20: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 Miscellaneous selection modifications.
36
37 rot13
38 Rot-13 the selection when activated. Used via keyboard trigger:
39
40 URxvt.keysym.C-M-r: perl:selection:rot13
41
42 digital-clock
43 Displays a digital clock using the built-in overlay.
44
45 example-refresh-hooks
46 Displays a very simple digital clock in the upper right corner of
47 the window. Illustrates overwriting the refresh callbacks to create
48 your own overlays or changes.
28 49
29 General API Considerations 50 General API Considerations
30 All objects (such as terminals, time watchers etc.) are typical 51 All objects (such as terminals, time watchers etc.) are typical
31 reference-to-hash objects. The hash can be used to store anything you 52 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 53 like. All members starting with an underscore (such as "_ptr" or
… …
112 display code is run after this hook, and takes precedence. 133 display code is run after this hook, and takes precedence.
113 134
114 on_refresh_end $term 135 on_refresh_end $term
115 Called just after the screen gets redrawn. See "on_refresh_begin". 136 Called just after the screen gets redrawn. See "on_refresh_begin".
116 137
138 on_keyboard_command $term, $string
139 Called whenever the user presses a key combination that has a
140 "perl:string" action bound to it (see description of the keysym
141 resource in the rxvt(1) manpage).
142
117 Functions in the "urxvt" Package 143 Functions in the "urxvt" Package
118 urxvt::fatal $errormessage 144 urxvt::fatal $errormessage
119 Fatally aborts execution with the given error message. Avoid at all 145 Fatally aborts execution with the given error message. Avoid at all
120 costs! The only time this is acceptable is when the terminal process 146 costs! The only time this is acceptable is when the terminal process
121 starts up. 147 starts up.
… …
129 correct place, e.g. on stderr of the connecting urxvtc client. 155 correct place, e.g. on stderr of the connecting urxvtc client.
130 156
131 $time = urxvt::NOW 157 $time = urxvt::NOW
132 Returns the "current time" (as per the event loop). 158 Returns the "current time" (as per the event loop).
133 159
160 RENDITION
161 Rendition bitsets contain information about colour, font, font styles
162 and similar information for each screen cell.
163
164 The following "macros" deal with changes in rendition sets. You should
165 never just create a bitset, you should always modify an existing one, as
166 they contain important information required for correct operation of
167 rxvt-unicode.
168
169 $rend = urxvt::DEFAULT_RSTYLE
170 Returns the default rendition, as used when the terminal is starting
171 up or being reset. Useful as a base to start when creating
172 renditions.
173
174 $rend = urxvt::OVERLAY_RSTYLE
175 Return the rendition mask used for overlays by default.
176
177 $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
178 Return the bit that enabled bold, italic, blink, reverse-video and
179 underline, respectively. To enable such a style, just logically OR
180 it into the bitset.
181
182 $foreground = urxvt::GET_BASEFG $rend
183 $background = urxvt::GET_BASEBG $rend
184 Return the foreground/background colour index, respectively.
185
186 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
187 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
188 Replace the foreground/background colour in the rendition mask with
189 the specified one.
190
191 $value = urxvt::GET_CUSTOM ($rend)
192 Return the "custom" value: Every rendition has 5 bits for use by
193 extensions. They can be set and changed as you like and are
194 initially zero.
195
196 $rend = urxvt::SET_CUSTOM ($rend, $new_value)
197 Change the custom value.
198
134 The "urxvt::term" Class 199 The "urxvt::term" Class
135 $value = $term->resource ($name[, $newval]) 200 $value = $term->resource ($name[, $newval])
136 Returns the current resource value associated with a given name and 201 Returns the current resource value associated with a given name and
137 optionally sets a new value. Setting values is most useful in the 202 optionally sets a new value. Setting values is most useful in the
138 "init" hook. Unset resources are returned and accepted as "undef". 203 "init" hook. Unset resources are returned and accepted as "undef".
… …
155 220
156 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 221 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
157 borderLess color cursorBlink cursorUnderline cutchars delete_key 222 borderLess color cursorBlink cursorUnderline cutchars delete_key
158 display_name embed ext_bwidth fade font geometry hold iconName 223 display_name embed ext_bwidth fade font geometry hold iconName
159 imFont imLocale inputMethod insecure int_bwidth intensityStyles 224 imFont imLocale inputMethod insecure int_bwidth intensityStyles
160 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 225 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
161 modifier mouseWheelScrollPage name pastableTabs path perl perl_eval 226 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
162 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 227 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
163 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 228 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
164 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 229 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
165 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 230 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
166 shade term_name title transparent transparent_all tripleclickwords 231 shade term_name title transparent transparent_all tripleclickwords
… …
178 243
179 $oldtext = $term->selection ([$newtext]) 244 $oldtext = $term->selection ([$newtext])
180 Return the current selection text and optionally replace it by 245 Return the current selection text and optionally replace it by
181 $newtext. 246 $newtext.
182 247
183 $term->scr_overlay ($x, $y, $text) 248 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
184 Create a simple multi-line overlay box. See the next method for 249 overlay box. See the next method for details. # #=cut
185 details.
186 250
187 $term->scr_overlay_new ($x, $y, $width, $height) 251 sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;
252
253 my @lines = split /\n/, $text;
254
255 my $w = 0;
256 for (map $self->strwidth ($_), @lines) {
257 $w = $_ if $w < $_;
258 }
259
260 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
261 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
262 }
263
264 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
188 Create a new (empty) overlay at the given position with the given 265 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 266 width/height. $rstyle defines the initial rendition style (default:
267 "OVERLAY_RSTYLE").
268
269 If $border is 2 (default), then a decorative border will be put
270 around the box.
271
190 $y is negative, then this is counted from the right/bottom side, 272 If either $x or $y is negative, then this is counted from the
191 respectively. 273 right/bottom side, respectively.
192 274
193 $term->scr_overlay_off 275 This method returns an urxvt::overlay object. The overlay will be
194 Switch the overlay off again. 276 visible as long as the perl object is referenced.
195 277
196 $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 278 Currently, the only method on the "urxvt::overlay" object is "set":
197 Put a single character (specified numerically) at the given overlay
198 position.
199 279
200 $term->scr_overlay_set ($x, $y, $text) 280 $overlay->set ($x, $y, $text, $rend)
201 Write a string at the given position into the overlay. 281 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts text in
282 rxvt-unicode's special encoding and an array of rendition values at
283 a specific position inside the overlay.
202 284
203 $cellwidth = $term->strwidth $string 285 $cellwidth = $term->strwidth $string
204 Returns the number of screen-cells this string would need. Correctly 286 Returns the number of screen-cells this string would need. Correctly
205 accounts for wide and combining characters. 287 accounts for wide and combining characters.
206 288
… …
211 $string = $term->locale_decode $octets 293 $string = $term->locale_decode $octets
212 Convert the given locale-encoded octets into a perl string. 294 Convert the given locale-encoded octets into a perl string.
213 295
214 $term->tt_write ($octets) 296 $term->tt_write ($octets)
215 Write the octets given in $data to the tty (i.e. as program input). 297 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 298 To pass characters instead of octets, you should convert your
217 first to the locale-specific encoding using "$term->locale_encode". 299 strings first to the locale-specific encoding using
300 "$term->locale_encode".
301
302 $nrow = $term->nrow
303 $ncol = $term->ncol
304 Return the number of rows/columns of the terminal window (i.e. as
305 specified by "-geometry", excluding any scrollback).
306
307 $nsaved = $term->nsaved
308 Returns the number of lines in the scrollback buffer.
309
310 $view_start = $term->view_start ([$newvalue])
311 Returns the negative row number of the topmost line. Minimum value
312 is 0, which displays the normal terminal contents. Larger values
313 scroll this many lines into the scrollback buffer.
314
315 $term->want_refresh
316 Requests a screen refresh. At the next opportunity, rxvt-unicode
317 will compare the on-screen display with its stored representation.
318 If they differ, it redraws the differences.
319
320 Used after changing terminal contents to display them.
321
322 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
323 Returns the text of the entire row with number $row_number. Row 0 is
324 the topmost terminal line, row "$term->$ncol-1" is the bottommost
325 terminal line. The scrollback buffer starts at line -1 and extends
326 to line "-$term->nsaved".
327
328 If $new_text is specified, it will replace characters in the current
329 line, starting at column $start_col (default 0), which is useful to
330 replace only parts of a line. The font index in the rendition will
331 automatically be updated.
332
333 $text is in a special encoding: tabs and wide characters that use
334 more than one cell when displayed are padded with urxvt::NOCHAR
335 characters ("chr 65535"). Characters with combining characters and
336 other characters that do not fit into the normal tetx encoding will
337 be replaced with characters in the private use area.
338
339 You have to obey this encoding when changing text. The advantage is
340 that "substr" and similar functions work on screen cells and not on
341 characters.
342
343 The methods "$term->special_encode" and "$term->special_decode" can
344 be used to convert normal strings into this encoding and vice versa.
345
346 $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
347 Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
348 Rendition bitsets contain information about colour, font, font
349 styles and similar information. See also "$term->ROW_t".
350
351 When setting rendition, the font mask will be ignored.
352
353 See the section on RENDITION, above.
354
355 $length = $term->ROW_l ($row_number[, $new_length])
356 Returns the number of screen cells that are in use ("the line
357 length"). If it is -1, then the line is part of a multiple-row
358 logical "line", which means all characters are in use and it is
359 continued on the next row.
360
361 $text = $term->special_encode $string
362 Converts a perl string into the special encoding used by
363 rxvt-unicode, where one character corresponds to one screen cell.
364 See "$term->ROW_t" for details.
365
366 $string = $term->special_decode $text
367 Converts rxvt-unicodes text reprsentation into a perl string. See
368 "$term->ROW_t" for details.
218 369
219 The "urxvt::timer" Class 370 The "urxvt::timer" Class
220 This class implements timer watchers/events. Time is represented as a 371 This class implements timer watchers/events. Time is represented as a
221 fractional number of seconds since the epoch. Example: 372 fractional number of seconds since the epoch. Example:
222 373
223 # create a digital clock display in upper right corner 374 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
224 $term->{timer} = urxvt::timer 375 $term->{timer} = urxvt::timer
225 ->new 376 ->new
226 ->start (urxvt::NOW) 377 ->interval (1)
227 ->cb (sub { 378 ->cb (sub {
228 my ($timer) = @_;
229 my $time = $timer->at;
230 $timer->start ($time + 1);
231 $self->scr_overlay (-1, 0, 379 $term->{overlay}->set (0, 0,
232 POSIX::strftime "%H:%M:%S", localtime $time); 380 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
233 }); 381 });
234 382
235 $timer = new urxvt::timer 383 $timer = new urxvt::timer
236 Create a new timer object in stopped state. 384 Create a new timer object in started state. It is scheduled to fire
385 immediately.
237 386
238 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 387 $timer = $timer->cb (sub { my ($timer) = @_; ... })
239 Set the callback to be called when the timer triggers. 388 Set the callback to be called when the timer triggers.
240 389
241 $tstamp = $timer->at 390 $tstamp = $timer->at
242 Return the time this watcher will fire next. 391 Return the time this watcher will fire next.
243 392
244 $timer = $timer->set ($tstamp) 393 $timer = $timer->set ($tstamp)
245 Set the time the event is generated to $tstamp. 394 Set the time the event is generated to $tstamp.
395
396 $timer = $timer->interval ($interval)
397 Normally (and when $interval is 0), the timer will automatically
398 stop after it has fired once. If $interval is non-zero, then the
399 timer is automatically rescheduled at the given intervals.
246 400
247 $timer = $timer->start 401 $timer = $timer->start
248 Start the timer. 402 Start the timer.
249 403
250 $timer = $timer->start ($tstamp) 404 $timer = $timer->start ($tstamp)

Diff Legend

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