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.13 by root, Sun Jan 8 00:20:12 2006 UTC vs.
Revision 1.27 by root, Fri Jan 13 12:40:46 2006 UTC

1NAME 1NAME
2 rxvtperl - rxvt-unicode's embedded perl interpreter 2 urxvtperl - rxvt-unicode's embedded perl interpreter
3 3
4SYNOPSIS 4SYNOPSIS
5 # create a file grab_test in $HOME: 5 # create a file grab_test in $HOME:
6 6
7 sub on_sel_grab { 7 sub on_sel_grab {
8 warn "you selected ", $_[0]->selection; 8 warn "you selected ", $_[0]->selection;
9 () 9 ()
10 } 10 }
11 11
12 # start a rxvt using it: 12 # start a urxvt using it:
13 13
14 rxvt --perl-lib $HOME -pe grab_test 14 urxvt --perl-lib $HOME -pe grab_test
15 15
16DESCRIPTION 16DESCRIPTION
17 Everytime a terminal object gets created, extension scripts specified 17 Everytime a terminal object gets created, extension scripts specified
18 via the "perl" resource are loaded and associated with it. 18 via the "perl" resource are loaded and associated with it.
19 19
20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and 20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21 thus must be encoded as UTF-8. 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 urxvtd, where scripts
24 will be shared (but not enabled) for all terminals. 24 will be shared (but not enabled) for all terminals.
25 25
26 Prepackaged Extensions 26PREPACKAGED EXTENSIONS
27 This section describes the extensiosn delivered with this version. You 27 This section describes the extensions delivered with this release. You
28 can find them in /opt/rxvt/lib/urxvt/perl/. 28 can find them in /usr/local/lib/urxvt/perl/.
29 29
30 You can activate them like this: 30 You can activate them like this:
31 31
32 rxvt -pe <extensionname> 32 urxvt -pe <extensionname>
33 33
34 selection 34 selection (enabled by default)
35 Intelligent selection. This extension tries to be more intelligent 35 (More) intelligent selection. This extension tries to be more
36 when the user extends selections (double-click). Right now, it tries 36 intelligent when the user extends selections (double-click and
37 to select urls and complete shell-quoted arguments, which is very 37 further clicks). Right now, it tries to select words, urls and
38 complete shell-quoted arguments, which is very convenient, too, if
38 convenient, too, if your ls supports "--quoting-style=shell". 39 your ls supports "--quoting-style=shell".
39 40
41 A double-click usually selects the word under the cursor, further
42 clicks will enlarge the selection.
43
44 The selection works by trying to match a number of regexes and
45 displaying them in increasing order of length. You can add your own
46 regexes by specifying resources of the form:
47
48 URxvt.selection.pattern-0: perl-regex
49 URxvt.selection.pattern-1: perl-regex
50 ...
51
52 The index number (0, 1...) must not have any holes, and each regex
53 must contain at least one pair of capturing parentheses, which will
54 be used for the match. For example, the followign adds a regex that
55 matches everything between two vertical bars:
56
57 URxvt.selection.pattern-0: \\|([^|]+)\\|
58
59 You can look at the source of the selection extension to see more
60 interesting uses, such as parsing a line from beginning to end.
61
40 It also offers the following bindable event: 62 This extension also offers the following bindable keyboard command:
41 63
42 rot13 64 rot13
43 Rot-13 the selection when activated. Used via keyboard trigger: 65 Rot-13 the selection when activated. Used via keyboard trigger:
44 66
45 URxvt.keysym.C-M-r: perl:selection:rot13 67 URxvt.keysym.C-M-r: perl:selection:rot13
46 68
47 digital-clock 69 option-popup (enabled by default)
48 Displays a digital clock using the built-in overlay. 70 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
71 options at runtime.
72
73 selection-popup (enabled by default)
74 Binds a popup menu to Ctrl-Button3 that lets you convert the
75 selection text into various other formats/action (such as uri
76 unescaping, perl evalution, web-browser starting etc.), depending on
77 content.
78
79 searchable-scrollback<hotkey> (enabled by default)
80 Adds regex search functionality to the scrollback buffer, triggered
81 by a hotkey (default: "M-s"). While in search mode, normal terminal
82 input/output is suspended and a regex is displayed at the bottom of
83 the screen.
84
85 Inputting characters appends them to the regex and continues
86 incremental search. "BackSpace" removes a character from the regex,
87 "Up" and "Down" search upwards/downwards in the scrollback buffer,
88 "End" jumps to the bottom. "Escape" leaves search mode and returns
89 to the point where search was started, while "Enter" or "Return"
90 stay at the current position and additionally stores the first match
91 in the current line into the primary selection.
92
93 selection-autotransform
94 This selection allows you to do automatic transforms on a selection
95 whenever a selection is made.
96
97 It works by specifying perl snippets (most useful is a single "s///"
98 operator) that modify $_ as resources:
99
100 URxvt.selection-autotransform.0: transform
101 URxvt.selection-autotransform.1: transform
102 ...
103
104 For example, the following will transform selections of the form
105 "filename:number", often seen in compiler messages, into "vi
106 +$filename $word":
107
108 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
109
110 And this example matches the same,but replaces it with vi-commands
111 you can paste directly into your (vi :) editor:
112
113 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
114
115 Of course, this can be modified to suit your needs and your editor
116 :)
117
118 To expand the example above to typical perl error messages ("XXX at
119 FILENAME line YYY."), you need a slightly more elaborate solution:
120
121 URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
122 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
123
124 The first line tells the selection code to treat the unchanging part
125 of every error message as a selection pattern, and the second line
126 transforms the message into vi commands to load the file.
49 127
50 mark-urls 128 mark-urls
51 Uses per-line display filtering ("on_line_update") to underline 129 Uses per-line display filtering ("on_line_update") to underline urls
52 urls. 130 and make them clickable. When middle-clicked, the program specified
131 in the resource "urlLauncher" (default "x-www-browser") will be
132 started with the URL as first argument.
53 133
54 block-graphics-to-ascii 134 block-graphics-to-ascii
55 A not very useful example of filtering all text output to the 135 A not very useful example of filtering all text output to the
56 terminal, by replacing all line-drawing characters (U+2500 .. 136 terminal, by replacing all line-drawing characters (U+2500 ..
57 U+259F) by a similar-looking ascii character. 137 U+259F) by a similar-looking ascii character.
58 138
139 digital-clock
140 Displays a digital clock using the built-in overlay.
141
59 example-refresh-hooks 142 example-refresh-hooks
60 Displays a very simple digital clock in the upper right corner of 143 Displays a very simple digital clock in the upper right corner of
61 the window. Illustrates overwriting the refresh callbacks to create 144 the window. Illustrates overwriting the refresh callbacks to create
62 your own overlays or changes. 145 your own overlays or changes.
63 146
147API DOCUMENTATION
64 General API Considerations 148 General API Considerations
65 All objects (such as terminals, time watchers etc.) are typical 149 All objects (such as terminals, time watchers etc.) are typical
66 reference-to-hash objects. The hash can be used to store anything you 150 reference-to-hash objects. The hash can be used to store anything you
67 like. All members starting with an underscore (such as "_ptr" or 151 like. All members starting with an underscore (such as "_ptr" or
68 "_hook") are reserved for internal uses and MUST NOT be accessed or 152 "_hook") are reserved for internal uses and MUST NOT be accessed or
… …
76 Argument names also often indicate the type of a parameter. Here are 160 Argument names also often indicate the type of a parameter. Here are
77 some hints on what they mean: 161 some hints on what they mean:
78 162
79 $text 163 $text
80 Rxvt-unicodes special way of encoding text, where one "unicode" 164 Rxvt-unicodes special way of encoding text, where one "unicode"
81 character always represents one screen cell. See row_t for a 165 character always represents one screen cell. See ROW_t for a
82 discussion of this format. 166 discussion of this format.
83 167
84 $string 168 $string
85 A perl text string, with an emphasis on *text*. It can store all 169 A perl text string, with an emphasis on *text*. It can store all
86 unicode characters and is to be distinguished with text encoded in a 170 unicode characters and is to be distinguished with text encoded in a
… …
88 172
89 $octets 173 $octets
90 Either binary data or - more common - a text string encoded in a 174 Either binary data or - more common - a text string encoded in a
91 locale-specific way. 175 locale-specific way.
92 176
177 Extension Objects
178 Very perl extension is a perl class. A separate perl object is created
179 for each terminal and each extension and passed as the first parameter
180 to hooks. So extensions can use their $self object without having to
181 think about other extensions, with the exception of methods and members
182 that begin with an underscore character "_": these are reserved for
183 internal use.
184
185 Although it isn't a "urxvt::term" object, you can call all methods of
186 the "urxvt::term" class on this object.
187
188 It has the following methods and data members:
189
190 $urxvt_term = $self->{term}
191 Returns the "urxvt::term" object associated with this instance of
192 the extension. This member *must not* be changed in any way.
193
194 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
195 Dynamically enable the given hooks (named without the "on_" prefix)
196 for this extension, replacing any previous hook. This is useful when
197 you want to overwrite time-critical hooks only temporarily.
198
199 $self->disable ($hook_name[, $hook_name..])
200 Dynamically disable the given hooks.
201
93 Hooks 202 Hooks
94 The following subroutines can be declared in extension files, and will 203 The following subroutines can be declared in extension files, and will
95 be called whenever the relevant event happens. 204 be called whenever the relevant event happens.
96 205
97 The first argument passed to them is an object private to each terminal 206 The first argument passed to them is an extension oject as described in
98 and extension package. You can call all "urxvt::term" methods on it, but 207 the in the "Extension Objects" section.
99 its not a real "urxvt::term" object. Instead, the real "urxvt::term"
100 object that is shared between all packages is stored in the "term"
101 member. It is, however, blessed intot he package of the extension
102 script, so for all practical purposes you can treat an extension script
103 as a class.
104 208
105 All of them must return a boolean value. If it is true, then the event 209 All of these hooks must return a boolean value. If it is true, then the
106 counts as being *consumed*, and the invocation of other hooks is 210 event counts as being *consumed*, and the invocation of other hooks is
107 skipped, and the relevant action might not be carried out by the C++ 211 skipped, and the relevant action might not be carried out by the C++
108 code. 212 code.
109 213
110 When in doubt, return a false value (preferably "()"). 214 *When in doubt, return a false value (preferably "()").*
111 215
112 on_init $term 216 on_init $term
113 Called after a new terminal object has been initialized, but before 217 Called after a new terminal object has been initialized, but before
114 windows are created or the command gets run. Most methods are unsafe 218 windows are created or the command gets run. Most methods are unsafe
115 to call or deliver senseless data, as terminal size and other 219 to call or deliver senseless data, as terminal size and other
… …
144 248
145 on_sel_extend $term 249 on_sel_extend $term
146 Called whenever the user tries to extend the selection (e.g. with a 250 Called whenever the user tries to extend the selection (e.g. with a
147 double click) and is either supposed to return false (normal 251 double click) and is either supposed to return false (normal
148 operation), or should extend the selection itelf and return true to 252 operation), or should extend the selection itelf and return true to
149 suppress the built-in processing. 253 suppress the built-in processing. This can happen multiple times, as
254 long as the callback returns true, it will be called on every
255 further click by the user and is supposed to enlarge the selection
256 more and more, if possible.
150 257
151 See the selection example extension. 258 See the selection example extension.
152 259
153 on_view_change $term, $offset 260 on_view_change $term, $offset
154 Called whenever the view offset changes, i..e the user or program 261 Called whenever the view offset changes, i..e the user or program
… …
161 may be larger than the scroll back buffer or the terminal. 268 may be larger than the scroll back buffer or the terminal.
162 269
163 It is called before lines are scrolled out (so rows 0 .. min ($lines 270 It is called before lines are scrolled out (so rows 0 .. min ($lines
164 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is 271 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
165 the total number of lines that will be in the scrollback buffer. 272 the total number of lines that will be in the scrollback buffer.
166
167 on_tty_activity $term *NYI*
168 Called whenever the program(s) running in the urxvt window send
169 output.
170 273
171 on_osc_seq $term, $string 274 on_osc_seq $term, $string
172 Called whenever the ESC ] 777 ; string ST command sequence (OSC = 275 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
173 operating system command) is processed. Cursor position and other 276 operating system command) is processed. Cursor position and other
174 state information is up-to-date when this happens. For 277 state information is up-to-date when this happens. For
… …
185 argument. You can filter/change and output the text yourself by 288 argument. You can filter/change and output the text yourself by
186 returning a true value and calling "$term->scr_add_lines" yourself. 289 returning a true value and calling "$term->scr_add_lines" yourself.
187 Please note that this might be very slow, however, as your hook is 290 Please note that this might be very slow, however, as your hook is
188 called for all text being output. 291 called for all text being output.
189 292
293 on_tt_write $term, $octets
294 Called whenever some data is written to the tty/pty and can be used
295 to suppress or filter tty input.
296
190 on_line_update $term, $row 297 on_line_update $term, $row
191 Called whenever a line was updated or changed. Can be used to filter 298 Called whenever a line was updated or changed. Can be used to filter
192 screen output (e.g. underline urls or other useless stuff). Only 299 screen output (e.g. underline urls or other useless stuff). Only
193 lines that are being shown will be filtered, and, due to performance 300 lines that are being shown will be filtered, and, due to performance
194 reasons, not always immediately. 301 reasons, not always immediately.
… …
211 Called just after the screen gets redrawn. See "on_refresh_begin". 318 Called just after the screen gets redrawn. See "on_refresh_begin".
212 319
213 on_keyboard_command $term, $string 320 on_keyboard_command $term, $string
214 Called whenever the user presses a key combination that has a 321 Called whenever the user presses a key combination that has a
215 "perl:string" action bound to it (see description of the keysym 322 "perl:string" action bound to it (see description of the keysym
216 resource in the rxvt(1) manpage). 323 resource in the urxvt(1) manpage).
324
325 on_x_event $term, $event
326 Called on every X event received on the vt window (and possibly
327 other windows). Should only be used as a last resort. Most event
328 structure members are not passed.
217 329
218 on_focus_in $term 330 on_focus_in $term
219 Called whenever the window gets the keyboard focus, before 331 Called whenever the window gets the keyboard focus, before
220 rxvt-unicode does focus in processing. 332 rxvt-unicode does focus in processing.
221 333
222 on_focus_out $term 334 on_focus_out $term
223 Called wheneever the window loses keyboard focus, before 335 Called wheneever the window loses keyboard focus, before
224 rxvt-unicode does focus out processing. 336 rxvt-unicode does focus out processing.
225 337
226 on_key_press $term, $event, $octets 338 on_key_press $term, $event, $keysym, $octets
227 on_key_release $term, $event 339 on_key_release $term, $event, $keysym
228 on_button_press $term, $event 340 on_button_press $term, $event
229 on_button_release $term, $event 341 on_button_release $term, $event
230 on_motion_notify $term, $event 342 on_motion_notify $term, $event
231 on_map_notify $term, $event 343 on_map_notify $term, $event
232 on_unmap_notify $term, $event 344 on_unmap_notify $term, $event
… …
242 output, if any, in locale-specific encoding. 354 output, if any, in locale-specific encoding.
243 355
244 subwindow. 356 subwindow.
245 357
246 Variables in the "urxvt" Package 358 Variables in the "urxvt" Package
359 $urxvt::LIBDIR
360 The rxvt-unicode library directory, where, among other things, the
361 perl modules and scripts are stored.
362
363 $urxvt::RESCLASS, $urxvt::RESCLASS
364 The resource class and name rxvt-unicode uses to look up X
365 resources.
366
367 $urxvt::RXVTNAME
368 The basename of the installed binaries, usually "urxvt".
369
247 $urxvt::TERM 370 $urxvt::TERM
248 The current terminal. This variable stores the current "urxvt::term" 371 The current terminal. This variable stores the current "urxvt::term"
249 object, whenever a callback/hook is executing. 372 object, whenever a callback/hook is executing.
250 373
251 Functions in the "urxvt" Package 374 Functions in the "urxvt" Package
252 $term = new urxvt [arg...]
253 Creates a new terminal, very similar as if you had started it with
254 "system $binfile, arg...". Croaks (and probably outputs an error
255 message) if the new instance couldn't be created. Returns "undef" if
256 the new instance didn't initialise perl, and the terminal object
257 otherwise. The "init" and "start" hooks will be called during the
258 call.
259
260 urxvt::fatal $errormessage 375 urxvt::fatal $errormessage
261 Fatally aborts execution with the given error message. Avoid at all 376 Fatally aborts execution with the given error message. Avoid at all
262 costs! The only time this is acceptable is when the terminal process 377 costs! The only time this is acceptable is when the terminal process
263 starts up. 378 starts up.
264 379
… …
268 function that calls this function. 383 function that calls this function.
269 384
270 Using this function has the advantage that its output ends up in the 385 Using this function has the advantage that its output ends up in the
271 correct place, e.g. on stderr of the connecting urxvtc client. 386 correct place, e.g. on stderr of the connecting urxvtc client.
272 387
388 Messages have a size limit of 1023 bytes currently.
389
390 $is_safe = urxvt::safe
391 Returns true when it is safe to do potentially unsafe things, such
392 as evaluating perl code specified by the user. This is true when
393 urxvt was started setuid or setgid.
394
273 $time = urxvt::NOW 395 $time = urxvt::NOW
274 Returns the "current time" (as per the event loop). 396 Returns the "current time" (as per the event loop).
275 397
276 urxvt::CurrentTime 398 urxvt::CurrentTime
277 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, 399 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
278 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, 400 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
279 Button5Mask, AnyModifier 401 Button5Mask, AnyModifier
402 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
403 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
404 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
405 Button3MotionMask, Button4MotionMask, Button5MotionMask,
406 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
407 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
408 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
409 ColormapChangeMask, OwnerGrabButtonMask
410 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
411 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
412 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
413 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
414 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
415 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
416 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
280 Various constants for use in X events. 417 Various constants for use in X calls and event processing.
281 418
282 RENDITION 419 RENDITION
283 Rendition bitsets contain information about colour, font, font styles 420 Rendition bitsets contain information about colour, font, font styles
284 and similar information for each screen cell. 421 and similar information for each screen cell.
285 422
… …
303 440
304 $foreground = urxvt::GET_BASEFG $rend 441 $foreground = urxvt::GET_BASEFG $rend
305 $background = urxvt::GET_BASEBG $rend 442 $background = urxvt::GET_BASEBG $rend
306 Return the foreground/background colour index, respectively. 443 Return the foreground/background colour index, respectively.
307 444
308 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 445 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
309 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 446 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
310 Replace the foreground/background colour in the rendition mask with 447 Replace the foreground/background colour in the rendition mask with
311 the specified one. 448 the specified one.
312 449
313 $value = urxvt::GET_CUSTOM ($rend) 450 $value = urxvt::GET_CUSTOM $rend
314 Return the "custom" value: Every rendition has 5 bits for use by 451 Return the "custom" value: Every rendition has 5 bits for use by
315 extensions. They can be set and changed as you like and are 452 extensions. They can be set and changed as you like and are
316 initially zero. 453 initially zero.
317 454
318 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 455 $rend = urxvt::SET_CUSTOM $rend, $new_value
319 Change the custom value. 456 Change the custom value.
320 457
458 The "urxvt::anyevent" Class
459 The sole purpose of this class is to deliver an interface to the
460 "AnyEvent" module - any module using it will work inside urxvt without
461 further programming. The only exception is that you cannot wait on
462 condition variables, but non-blocking condvar use is ok. What this means
463 is that you cannot use blocking APIs, but the non-blocking variant
464 should work.
465
321 The "urxvt::term" Class 466 The "urxvt::term" Class
467 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
468 Creates a new terminal, very similar as if you had started it with
469 system "$rxvtname, arg...". $envhashref must be a reference to a
470 %ENV-like hash which defines the environment of the new terminal.
471
472 Croaks (and probably outputs an error message) if the new instance
473 couldn't be created. Returns "undef" if the new instance didn't
474 initialise perl, and the terminal object otherwise. The "init" and
475 "start" hooks will be called during this call.
476
322 $term->destroy 477 $term->destroy
323 Destroy the terminal object (close the window, free resources etc.). 478 Destroy the terminal object (close the window, free resources etc.).
479 Please note that urxvt will not exit as long as any event watchers
480 (timers, io watchers) are still active.
324 481
325 $isset = $term->option ($optval[, $set]) 482 $isset = $term->option ($optval[, $set])
326 Returns true if the option specified by $optval is enabled, and 483 Returns true if the option specified by $optval is enabled, and
327 optionally change it. All option values are stored by name in the 484 optionally change it. All option values are stored by name in the
328 hash %urxvt::OPTION. Options not enabled in this binary are not in 485 hash %urxvt::OPTION. Options not enabled in this binary are not in
… …
370 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 527 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
371 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 528 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
372 shade term_name title transparent transparent_all tripleclickwords 529 shade term_name title transparent transparent_all tripleclickwords
373 utmpInhibit visualBell 530 utmpInhibit visualBell
374 531
532 $value = $term->x_resource ($pattern)
533 Returns the X-Resource for the given pattern, excluding the program
534 or class name, i.e. "$term->x_resource ("boldFont")" should return
535 the same value as used by this instance of rxvt-unicode. Returns
536 "undef" if no resource with that pattern exists.
537
538 This method should only be called during the "on_start" hook, as
539 there is only one resource database per display, and later
540 invocations might return the wrong resources.
541
542 $success = $term->parse_keysym ($keysym_spec, $command_string)
543 Adds a keymap translation exactly as specified via a resource. See
544 the "keysym" resource in the urxvt(1) manpage.
545
375 $rend = $term->rstyle ([$new_rstyle]) 546 $rend = $term->rstyle ([$new_rstyle])
376 Return and optionally change the current rendition. Text that is 547 Return and optionally change the current rendition. Text that is
377 output by the terminal application will use this style. 548 output by the terminal application will use this style.
378 549
379 ($row, $col) = $term->screen_cur ([$row, $col]) 550 ($row, $col) = $term->screen_cur ([$row, $col])
… …
385 ($row, $col) = $term->selection_beg ([$row, $col]) 556 ($row, $col) = $term->selection_beg ([$row, $col])
386 ($row, $col) = $term->selection_end ([$row, $col]) 557 ($row, $col) = $term->selection_end ([$row, $col])
387 Return the current values of the selection mark, begin or end 558 Return the current values of the selection mark, begin or end
388 positions, and optionally set them to new values. 559 positions, and optionally set them to new values.
389 560
561 $term->selection_make ($eventtime[, $rectangular])
562 Tries to make a selection as set by "selection_beg" and
563 "selection_end". If $rectangular is true (default: false), a
564 rectangular selection will be made. This is the prefered function to
565 make a selection.
566
390 $success = $term->selection_grab ($eventtime) 567 $success = $term->selection_grab ($eventtime)
391 Try to request the primary selection from the server (for example, 568 Try to request the primary selection text from the server (for
392 as set by the next method). 569 example, as set by the next method). No visual feedback will be
570 given. This function is mostly useful from within "on_sel_grab"
571 hooks.
393 572
394 $oldtext = $term->selection ([$newtext]) 573 $oldtext = $term->selection ([$newtext])
395 Return the current selection text and optionally replace it by 574 Return the current selection text and optionally replace it by
396 $newtext. 575 $newtext.
397 576
398 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 577 $term->overlay_simple ($x, $y, $text)
399 overlay box. See the next method for details. # #=cut # #sub 578 Create a simple multi-line overlay box. See the next method for
400 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my 579 details.
401 @lines = split /\n/, $text; # # my $w = 0; # for (map
402 $self->strwidth ($_), @lines) { # $w = $_ if $w < $_; # } # #
403 $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
404 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
405 580
406 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 581 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
407 Create a new (empty) overlay at the given position with the given 582 Create a new (empty) overlay at the given position with the given
408 width/height. $rstyle defines the initial rendition style (default: 583 width/height. $rstyle defines the initial rendition style (default:
409 "OVERLAY_RSTYLE"). 584 "OVERLAY_RSTYLE").
… …
443 Convert the given text string into the corresponding locale 618 Convert the given text string into the corresponding locale
444 encoding. 619 encoding.
445 620
446 $string = $term->locale_decode ($octets) 621 $string = $term->locale_decode ($octets)
447 Convert the given locale-encoded octets into a perl string. 622 Convert the given locale-encoded octets into a perl string.
623
624 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
625 XORs the rendition values in the given span with the provided value
626 (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful
627 in refresh hooks to provide effects similar to the selection.
628
629 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
630 $rstyle2]])
631 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
632 whitespace will additionally be xored with the $rstyle2, which
633 defaults to "RS_RVid | RS_Uline", which removes reverse video again
634 and underlines it instead. Both styles *MUST NOT* contain font
635 styles.
636
637 $term->scr_bell
638 Ring the bell!
448 639
449 $term->scr_add_lines ($string) 640 $term->scr_add_lines ($string)
450 Write the given text string to the screen, as if output by the 641 Write the given text string to the screen, as if output by the
451 application running inside the terminal. It may not contain command 642 application running inside the terminal. It may not contain command
452 sequences (escape codes), but is free to use line feeds, carriage 643 sequences (escape codes), but is free to use line feeds, carriage
… …
466 Write the octets given in $data to the tty (i.e. as program input). 657 Write the octets given in $data to the tty (i.e. as program input).
467 To pass characters instead of octets, you should convert your 658 To pass characters instead of octets, you should convert your
468 strings first to the locale-specific encoding using 659 strings first to the locale-specific encoding using
469 "$term->locale_encode". 660 "$term->locale_encode".
470 661
662 $old_events = $term->pty_ev_events ([$new_events])
663 Replaces the event mask of the pty watcher by the given event mask.
664 Can be used to suppress input and output handling to the pty/tty.
665 See the description of "urxvt::timer->events". Make sure to always
666 restore the previous value.
667
471 $windowid = $term->parent 668 $windowid = $term->parent
472 Return the window id of the toplevel window. 669 Return the window id of the toplevel window.
473 670
474 $windowid = $term->vt 671 $windowid = $term->vt
475 Return the window id of the terminal window. 672 Return the window id of the terminal window.
673
674 $term->vt_emask_add ($x_event_mask)
675 Adds the specified events to the vt event mask. Useful e.g. when you
676 want to receive pointer events all the times:
677
678 $term->vt_emask_add (urxvt::PointerMotionMask);
476 679
477 $window_width = $term->width 680 $window_width = $term->width
478 $window_height = $term->height 681 $window_height = $term->height
479 $font_width = $term->fwidth 682 $font_width = $term->fwidth
480 $font_height = $term->fheight 683 $font_height = $term->fheight
… …
486 $max_scrollback = $term->saveLines 689 $max_scrollback = $term->saveLines
487 $nrow_plus_saveLines = $term->total_rows 690 $nrow_plus_saveLines = $term->total_rows
488 $lines_in_scrollback = $term->nsaved 691 $lines_in_scrollback = $term->nsaved
489 Return various integers describing terminal characteristics. 692 Return various integers describing terminal characteristics.
490 693
694 $x_display = $term->display_id
695 Return the DISPLAY used by rxvt-unicode.
696
697 $lc_ctype = $term->locale
698 Returns the LC_CTYPE category string used by this rxvt-unicode.
699
700 $env = $term->env
701 Returns a copy of the environment in effect for the terminal as a
702 hashref similar to "\%ENV".
703
491 $modifiermask = $term->ModLevel3Mask 704 $modifiermask = $term->ModLevel3Mask
492 $modifiermask = $term->ModMetaMask 705 $modifiermask = $term->ModMetaMask
493 $modifiermask = $term->ModNumLockMask 706 $modifiermask = $term->ModNumLockMask
494 Return the modifier masks corresponding to the "ISO Level 3 Shift" 707 Return the modifier masks corresponding to the "ISO Level 3 Shift"
495 (often AltGr), the meta key (often Alt) and the num lock key, if 708 (often AltGr), the meta key (often Alt) and the num lock key, if
… …
573 Return the row number of the first/last row of the line, 786 Return the row number of the first/last row of the line,
574 respectively. 787 respectively.
575 788
576 $offset = $line->offset_of ($row, $col) 789 $offset = $line->offset_of ($row, $col)
577 Returns the character offset of the given row|col pair within 790 Returns the character offset of the given row|col pair within
578 the logical line. 791 the logical line. Works for rows outside the line, too, and
792 returns corresponding offsets outside the string.
579 793
580 ($row, $col) = $line->coord_of ($offset) 794 ($row, $col) = $line->coord_of ($offset)
581 Translates a string offset into terminal coordinates again. 795 Translates a string offset into terminal coordinates again.
582 796
583 ($row, $col) = $line->coord_of ($offset) =item $text =
584 $term->special_encode $string 797 $text = $term->special_encode $string
585 Converts a perl string into the special encoding used by 798 Converts a perl string into the special encoding used by
586 rxvt-unicode, where one character corresponds to one screen cell. 799 rxvt-unicode, where one character corresponds to one screen cell.
587 See "$term->ROW_t" for details. 800 See "$term->ROW_t" for details.
588 801
589 $string = $term->special_decode $text 802 $string = $term->special_decode $text
590 Converts rxvt-unicodes text reprsentation into a perl string. See 803 Converts rxvt-unicodes text reprsentation into a perl string. See
591 "$term->ROW_t" for details. 804 "$term->ROW_t" for details.
592 805
806 $success = $term->grab_button ($button, $modifiermask)
807 Registers a synchronous button grab. See the XGrabButton manpage.
808
809 $success = $term->grab ($eventtime[, $sync])
810 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
811 synchronous ($sync is true). Also remembers the grab timestampe.
812
813 $term->allow_events_async
814 Calls XAllowEvents with AsyncBoth for the most recent grab.
815
816 $term->allow_events_sync
817 Calls XAllowEvents with SyncBoth for the most recent grab.
818
819 $term->allow_events_replay
820 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
821 the most recent grab.
822
823 $term->ungrab
824 Calls XUngrab for the most recent grab. Is called automatically on
825 evaluation errors, as it is better to lose the grab in the error
826 case as the session.
827
593 The "urxvt::popup" Class 828 The "urxvt::popup" Class
829 $popup->add_title ($title)
830 Adds a non-clickable title to the popup.
831
832 $popup->add_separator ([$sepchr])
833 Creates a separator, optionally using the character given as
834 $sepchr.
835
836 $popup->add_button ($text, $cb)
837 Adds a clickable button to the popup. $cb is called whenever it is
838 selected.
839
840 $popup->add_toggle ($text, $cb, $initial_value)
841 Adds a toggle/checkbox item to the popup. Teh callback gets called
842 whenever it gets toggled, with a boolean indicating its value as its
843 first argument.
844
845 $popup->show
846 Displays the popup (which is initially hidden).
847
594 The "urxvt::timer" Class 848 The "urxvt::timer" Class
595 This class implements timer watchers/events. Time is represented as 849 This class implements timer watchers/events. Time is represented as a
596 a fractional number of seconds since the epoch. Example: 850 fractional number of seconds since the epoch. Example:
597 851
598 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 852 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
599 $term->{timer} = urxvt::timer 853 $term->{timer} = urxvt::timer
600 ->new 854 ->new
601 ->interval (1) 855 ->interval (1)
602 ->cb (sub { 856 ->cb (sub {
603 $term->{overlay}->set (0, 0, 857 $term->{overlay}->set (0, 0,
604 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 858 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
605 }); 859 });
606 860
607 $timer = new urxvt::timer 861 $timer = new urxvt::timer
608 Create a new timer object in started state. It is scheduled to 862 Create a new timer object in started state. It is scheduled to fire
609 fire immediately. 863 immediately.
610 864
611 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 865 $timer = $timer->cb (sub { my ($timer) = @_; ... })
612 Set the callback to be called when the timer triggers. 866 Set the callback to be called when the timer triggers.
613 867
614 $tstamp = $timer->at 868 $tstamp = $timer->at
615 Return the time this watcher will fire next. 869 Return the time this watcher will fire next.
616 870
617 $timer = $timer->set ($tstamp) 871 $timer = $timer->set ($tstamp)
618 Set the time the event is generated to $tstamp. 872 Set the time the event is generated to $tstamp.
619 873
620 $timer = $timer->interval ($interval) 874 $timer = $timer->interval ($interval)
621 Normally (and when $interval is 0), the timer will automatically 875 Normally (and when $interval is 0), the timer will automatically
622 stop after it has fired once. If $interval is non-zero, then the 876 stop after it has fired once. If $interval is non-zero, then the
623 timer is automatically rescheduled at the given intervals. 877 timer is automatically rescheduled at the given intervals.
624 878
625 $timer = $timer->start 879 $timer = $timer->start
626 Start the timer. 880 Start the timer.
627 881
628 $timer = $timer->start ($tstamp) 882 $timer = $timer->start ($tstamp)
629 Set the event trigger time to $tstamp and start the timer. 883 Set the event trigger time to $tstamp and start the timer.
630 884
631 $timer = $timer->stop 885 $timer = $timer->stop
632 Stop the timer. 886 Stop the timer.
633 887
634 The "urxvt::iow" Class 888 The "urxvt::iow" Class
635 This class implements io watchers/events. Example: 889 This class implements io watchers/events. Example:
636 890
637 $term->{socket} = ... 891 $term->{socket} = ...
638 $term->{iow} = urxvt::iow 892 $term->{iow} = urxvt::iow
639 ->new 893 ->new
640 ->fd (fileno $term->{socket}) 894 ->fd (fileno $term->{socket})
641 ->events (1) # wait for read data 895 ->events (urxvt::EVENT_READ)
642 ->start 896 ->start
643 ->cb (sub { 897 ->cb (sub {
644 my ($iow, $revents) = @_; 898 my ($iow, $revents) = @_;
645 # $revents must be 1 here, no need to check 899 # $revents must be 1 here, no need to check
646 sysread $term->{socket}, my $buf, 8192 900 sysread $term->{socket}, my $buf, 8192
647 or end-of-file; 901 or end-of-file;
648 }); 902 });
649 903
650 $iow = new urxvt::iow 904 $iow = new urxvt::iow
651 Create a new io watcher object in stopped state. 905 Create a new io watcher object in stopped state.
652 906
653 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 907 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
654 Set the callback to be called when io events are triggered. 908 Set the callback to be called when io events are triggered.
655 $reventmask is a bitset as described in the "events" method. 909 $reventmask is a bitset as described in the "events" method.
656 910
657 $iow = $iow->fd ($fd) 911 $iow = $iow->fd ($fd)
658 Set the filedescriptor (not handle) to watch. 912 Set the filedescriptor (not handle) to watch.
659 913
660 $iow = $iow->events ($eventmask) 914 $iow = $iow->events ($eventmask)
661 Set the event mask to watch. Bit #0 (value 1) enables watching 915 Set the event mask to watch. The only allowed values are
662 for read data, Bit #1 (value 2) enables watching for write data. 916 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
917 together, or "urxvt::EVENT_NONE".
663 918
664 $iow = $iow->start 919 $iow = $iow->start
665 Start watching for requested events on the given handle. 920 Start watching for requested events on the given handle.
666 921
667 $iow = $iow->stop 922 $iow = $iow->stop
668 Stop watching for events on the given filehandle. 923 Stop watching for events on the given filehandle.
669 924
670ENVIRONMENT 925ENVIRONMENT
671 URXVT_PERL_VERBOSITY 926 URXVT_PERL_VERBOSITY
672 This variable controls the verbosity level of the perl extension. 927 This variable controls the verbosity level of the perl extension. Higher
673 Higher numbers indicate more verbose output. 928 numbers indicate more verbose output.
674 929
675 =0 - only fatal messages 930 == 0 - fatal messages
676 =3 - script loading and management 931 >= 3 - script loading and management
677 =10 - all events received 932 >=10 - all called hooks
933 >=11 - hook reutrn values
678 934
679AUTHOR 935AUTHOR
680 Marc Lehmann <pcg@goof.com> 936 Marc Lehmann <pcg@goof.com>
681 http://software.schmorp.de/pkg/rxvt-unicode 937 http://software.schmorp.de/pkg/rxvt-unicode
682 938

Diff Legend

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