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.16 by root, Mon Jan 9 07:17:24 2006 UTC vs.
Revision 1.29 by root, Tue Jan 17 16:22:41 2006 UTC

… …
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 rxvtd, 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 /opt/rxvt/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 rxvt -pe <extensionname>
33 33
34 selection (enabled by default) 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
40 It also offers the following bindable event: 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
62 This extension also offers following bindable keyboard commands:
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
68
69 remote-pastebin
70 Upload the selection as textfile to a remote site.
71
72 URxvt.keysym.C-M-e: perl:selection:remote-pastebin
73
74 To set the command to upload the file set this resource:
75
76 URxvt.selection-pastebin-cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
77
78 The % is the placeholder for the textfile. The name of the
79 textfile is the hex encoded md5 sum of the selection. After an
80 successful upload the selection will be replaced by the
81 following url (the % is the placeholder for the filename):
82
83 URxvt.selection-pastebin-url: http://www.ta-sa.org/files/txt/%
46 84
47 option-popup (enabled by default) 85 option-popup (enabled by default)
48 Binds a popup menu to Ctrl-Button2 that lets you toggle (some) 86 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
49 options at runtime. 87 options at runtime.
50 88
51 selection-popup (enabled by default) 89 selection-popup (enabled by default)
52 Binds a popup menu to Ctrl-Button3 that lets you convert the 90 Binds a popup menu to Ctrl-Button3 that lets you convert the
53 selection text into various other formats/action. 91 selection text into various other formats/action (such as uri
92 unescaping, perl evalution, web-browser starting etc.), depending on
93 content.
54 94
55 digital-clock 95 searchable-scrollback<hotkey> (enabled by default)
56 Displays a digital clock using the built-in overlay. 96 Adds regex search functionality to the scrollback buffer, triggered
97 by a hotkey (default: "M-s"). While in search mode, normal terminal
98 input/output is suspended and a regex is displayed at the bottom of
99 the screen.
100
101 Inputting characters appends them to the regex and continues
102 incremental search. "BackSpace" removes a character from the regex,
103 "Up" and "Down" search upwards/downwards in the scrollback buffer,
104 "End" jumps to the bottom. "Escape" leaves search mode and returns
105 to the point where search was started, while "Enter" or "Return"
106 stay at the current position and additionally stores the first match
107 in the current line into the primary selection.
108
109 selection-autotransform
110 This selection allows you to do automatic transforms on a selection
111 whenever a selection is made.
112
113 It works by specifying perl snippets (most useful is a single "s///"
114 operator) that modify $_ as resources:
115
116 URxvt.selection-autotransform.0: transform
117 URxvt.selection-autotransform.1: transform
118 ...
119
120 For example, the following will transform selections of the form
121 "filename:number", often seen in compiler messages, into "vi
122 +$filename $word":
123
124 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
125
126 And this example matches the same,but replaces it with vi-commands
127 you can paste directly into your (vi :) editor:
128
129 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
130
131 Of course, this can be modified to suit your needs and your editor
132 :)
133
134 To expand the example above to typical perl error messages ("XXX at
135 FILENAME line YYY."), you need a slightly more elaborate solution:
136
137 URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
138 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
139
140 The first line tells the selection code to treat the unchanging part
141 of every error message as a selection pattern, and the second line
142 transforms the message into vi commands to load the file.
57 143
58 mark-urls 144 mark-urls
59 Uses per-line display filtering ("on_line_update") to underline 145 Uses per-line display filtering ("on_line_update") to underline urls
60 urls. 146 and make them clickable. When middle-clicked, the program specified
147 in the resource "urlLauncher" (default "x-www-browser") will be
148 started with the URL as first argument.
61 149
62 block-graphics-to-ascii 150 block-graphics-to-ascii
63 A not very useful example of filtering all text output to the 151 A not very useful example of filtering all text output to the
64 terminal, by replacing all line-drawing characters (U+2500 .. 152 terminal, by replacing all line-drawing characters (U+2500 ..
65 U+259F) by a similar-looking ascii character. 153 U+259F) by a similar-looking ascii character.
66 154
155 digital-clock
156 Displays a digital clock using the built-in overlay.
157
67 example-refresh-hooks 158 example-refresh-hooks
68 Displays a very simple digital clock in the upper right corner of 159 Displays a very simple digital clock in the upper right corner of
69 the window. Illustrates overwriting the refresh callbacks to create 160 the window. Illustrates overwriting the refresh callbacks to create
70 your own overlays or changes. 161 your own overlays or changes.
71 162
163API DOCUMENTATION
72 General API Considerations 164 General API Considerations
73 All objects (such as terminals, time watchers etc.) are typical 165 All objects (such as terminals, time watchers etc.) are typical
74 reference-to-hash objects. The hash can be used to store anything you 166 reference-to-hash objects. The hash can be used to store anything you
75 like. All members starting with an underscore (such as "_ptr" or 167 like. All members starting with an underscore (such as "_ptr" or
76 "_hook") are reserved for internal uses and MUST NOT be accessed or 168 "_hook") are reserved for internal uses and MUST NOT be accessed or
… …
84 Argument names also often indicate the type of a parameter. Here are 176 Argument names also often indicate the type of a parameter. Here are
85 some hints on what they mean: 177 some hints on what they mean:
86 178
87 $text 179 $text
88 Rxvt-unicodes special way of encoding text, where one "unicode" 180 Rxvt-unicodes special way of encoding text, where one "unicode"
89 character always represents one screen cell. See row_t for a 181 character always represents one screen cell. See ROW_t for a
90 discussion of this format. 182 discussion of this format.
91 183
92 $string 184 $string
93 A perl text string, with an emphasis on *text*. It can store all 185 A perl text string, with an emphasis on *text*. It can store all
94 unicode characters and is to be distinguished with text encoded in a 186 unicode characters and is to be distinguished with text encoded in a
… …
96 188
97 $octets 189 $octets
98 Either binary data or - more common - a text string encoded in a 190 Either binary data or - more common - a text string encoded in a
99 locale-specific way. 191 locale-specific way.
100 192
193 Extension Objects
194 Very perl extension is a perl class. A separate perl object is created
195 for each terminal and each extension and passed as the first parameter
196 to hooks. So extensions can use their $self object without having to
197 think about other extensions, with the exception of methods and members
198 that begin with an underscore character "_": these are reserved for
199 internal use.
200
201 Although it isn't a "urxvt::term" object, you can call all methods of
202 the "urxvt::term" class on this object.
203
204 It has the following methods and data members:
205
206 $urxvt_term = $self->{term}
207 Returns the "urxvt::term" object associated with this instance of
208 the extension. This member *must not* be changed in any way.
209
210 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
211 Dynamically enable the given hooks (named without the "on_" prefix)
212 for this extension, replacing any previous hook. This is useful when
213 you want to overwrite time-critical hooks only temporarily.
214
215 $self->disable ($hook_name[, $hook_name..])
216 Dynamically disable the given hooks.
217
101 Hooks 218 Hooks
102 The following subroutines can be declared in extension files, and will 219 The following subroutines can be declared in extension files, and will
103 be called whenever the relevant event happens. 220 be called whenever the relevant event happens.
104 221
105 The first argument passed to them is an object private to each terminal 222 The first argument passed to them is an extension oject as described in
106 and extension package. You can call all "urxvt::term" methods on it, but 223 the in the "Extension Objects" section.
107 its not a real "urxvt::term" object. Instead, the real "urxvt::term"
108 object that is shared between all packages is stored in the "term"
109 member. It is, however, blessed intot he package of the extension
110 script, so for all practical purposes you can treat an extension script
111 as a class.
112 224
113 All of them must return a boolean value. If it is true, then the event 225 All of these hooks must return a boolean value. If it is true, then the
114 counts as being *consumed*, and the invocation of other hooks is 226 event counts as being *consumed*, and the invocation of other hooks is
115 skipped, and the relevant action might not be carried out by the C++ 227 skipped, and the relevant action might not be carried out by the C++
116 code. 228 code.
117 229
118 When in doubt, return a false value (preferably "()"). 230 *When in doubt, return a false value (preferably "()").*
119 231
120 on_init $term 232 on_init $term
121 Called after a new terminal object has been initialized, but before 233 Called after a new terminal object has been initialized, but before
122 windows are created or the command gets run. Most methods are unsafe 234 windows are created or the command gets run. Most methods are unsafe
123 to call or deliver senseless data, as terminal size and other 235 to call or deliver senseless data, as terminal size and other
… …
152 264
153 on_sel_extend $term 265 on_sel_extend $term
154 Called whenever the user tries to extend the selection (e.g. with a 266 Called whenever the user tries to extend the selection (e.g. with a
155 double click) and is either supposed to return false (normal 267 double click) and is either supposed to return false (normal
156 operation), or should extend the selection itelf and return true to 268 operation), or should extend the selection itelf and return true to
157 suppress the built-in processing. 269 suppress the built-in processing. This can happen multiple times, as
270 long as the callback returns true, it will be called on every
271 further click by the user and is supposed to enlarge the selection
272 more and more, if possible.
158 273
159 See the selection example extension. 274 See the selection example extension.
160 275
161 on_view_change $term, $offset 276 on_view_change $term, $offset
162 Called whenever the view offset changes, i..e the user or program 277 Called whenever the view offset changes, i..e the user or program
… …
189 argument. You can filter/change and output the text yourself by 304 argument. You can filter/change and output the text yourself by
190 returning a true value and calling "$term->scr_add_lines" yourself. 305 returning a true value and calling "$term->scr_add_lines" yourself.
191 Please note that this might be very slow, however, as your hook is 306 Please note that this might be very slow, however, as your hook is
192 called for all text being output. 307 called for all text being output.
193 308
309 on_tt_write $term, $octets
310 Called whenever some data is written to the tty/pty and can be used
311 to suppress or filter tty input.
312
194 on_line_update $term, $row 313 on_line_update $term, $row
195 Called whenever a line was updated or changed. Can be used to filter 314 Called whenever a line was updated or changed. Can be used to filter
196 screen output (e.g. underline urls or other useless stuff). Only 315 screen output (e.g. underline urls or other useless stuff). Only
197 lines that are being shown will be filtered, and, due to performance 316 lines that are being shown will be filtered, and, due to performance
198 reasons, not always immediately. 317 reasons, not always immediately.
… …
217 on_keyboard_command $term, $string 336 on_keyboard_command $term, $string
218 Called whenever the user presses a key combination that has a 337 Called whenever the user presses a key combination that has a
219 "perl:string" action bound to it (see description of the keysym 338 "perl:string" action bound to it (see description of the keysym
220 resource in the rxvt(1) manpage). 339 resource in the rxvt(1) manpage).
221 340
341 on_x_event $term, $event
342 Called on every X event received on the vt window (and possibly
343 other windows). Should only be used as a last resort. Most event
344 structure members are not passed.
345
222 on_focus_in $term 346 on_focus_in $term
223 Called whenever the window gets the keyboard focus, before 347 Called whenever the window gets the keyboard focus, before
224 rxvt-unicode does focus in processing. 348 rxvt-unicode does focus in processing.
225 349
226 on_focus_out $term 350 on_focus_out $term
227 Called wheneever the window loses keyboard focus, before 351 Called wheneever the window loses keyboard focus, before
228 rxvt-unicode does focus out processing. 352 rxvt-unicode does focus out processing.
229 353
230 on_key_press $term, $event, $octets 354 on_key_press $term, $event, $keysym, $octets
231 on_key_release $term, $event 355 on_key_release $term, $event, $keysym
232 on_button_press $term, $event 356 on_button_press $term, $event
233 on_button_release $term, $event 357 on_button_release $term, $event
234 on_motion_notify $term, $event 358 on_motion_notify $term, $event
235 on_map_notify $term, $event 359 on_map_notify $term, $event
236 on_unmap_notify $term, $event 360 on_unmap_notify $term, $event
… …
246 output, if any, in locale-specific encoding. 370 output, if any, in locale-specific encoding.
247 371
248 subwindow. 372 subwindow.
249 373
250 Variables in the "urxvt" Package 374 Variables in the "urxvt" Package
375 $urxvt::LIBDIR
376 The rxvt-unicode library directory, where, among other things, the
377 perl modules and scripts are stored.
378
379 $urxvt::RESCLASS, $urxvt::RESCLASS
380 The resource class and name rxvt-unicode uses to look up X
381 resources.
382
383 $urxvt::RXVTNAME
384 The basename of the installed binaries, usually "urxvt".
385
251 $urxvt::TERM 386 $urxvt::TERM
252 The current terminal. This variable stores the current "urxvt::term" 387 The current terminal. This variable stores the current "urxvt::term"
253 object, whenever a callback/hook is executing. 388 object, whenever a callback/hook is executing.
254 389
255 Functions in the "urxvt" Package 390 Functions in the "urxvt" Package
256 $term = new urxvt [arg...]
257 Creates a new terminal, very similar as if you had started it with
258 "system $binfile, arg...". Croaks (and probably outputs an error
259 message) if the new instance couldn't be created. Returns "undef" if
260 the new instance didn't initialise perl, and the terminal object
261 otherwise. The "init" and "start" hooks will be called during the
262 call.
263
264 urxvt::fatal $errormessage 391 urxvt::fatal $errormessage
265 Fatally aborts execution with the given error message. Avoid at all 392 Fatally aborts execution with the given error message. Avoid at all
266 costs! The only time this is acceptable is when the terminal process 393 costs! The only time this is acceptable is when the terminal process
267 starts up. 394 starts up.
268 395
… …
272 function that calls this function. 399 function that calls this function.
273 400
274 Using this function has the advantage that its output ends up in the 401 Using this function has the advantage that its output ends up in the
275 correct place, e.g. on stderr of the connecting urxvtc client. 402 correct place, e.g. on stderr of the connecting urxvtc client.
276 403
277 $is_safe = urxvt::safe 404 Messages have a size limit of 1023 bytes currently.
278 Returns true when it is safe to do potentially unsafe things, such
279 as evaluating perl code specified by the user. This is true when
280 urxvt was started setuid or setgid.
281 405
282 $time = urxvt::NOW 406 $time = urxvt::NOW
283 Returns the "current time" (as per the event loop). 407 Returns the "current time" (as per the event loop).
284 408
285 urxvt::CurrentTime 409 urxvt::CurrentTime
286 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, 410 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
287 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, 411 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
288 Button5Mask, AnyModifier 412 Button5Mask, AnyModifier
413 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
414 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
415 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
416 Button3MotionMask, Button4MotionMask, Button5MotionMask,
417 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
418 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
419 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
420 ColormapChangeMask, OwnerGrabButtonMask
421 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
422 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
423 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
424 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
425 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
426 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
427 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
289 Various constants for use in X calls and event processing. 428 Various constants for use in X calls and event processing.
290 429
291 RENDITION 430 RENDITION
292 Rendition bitsets contain information about colour, font, font styles 431 Rendition bitsets contain information about colour, font, font styles
293 and similar information for each screen cell. 432 and similar information for each screen cell.
… …
312 451
313 $foreground = urxvt::GET_BASEFG $rend 452 $foreground = urxvt::GET_BASEFG $rend
314 $background = urxvt::GET_BASEBG $rend 453 $background = urxvt::GET_BASEBG $rend
315 Return the foreground/background colour index, respectively. 454 Return the foreground/background colour index, respectively.
316 455
317 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 456 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
318 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 457 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
319 Replace the foreground/background colour in the rendition mask with 458 Replace the foreground/background colour in the rendition mask with
320 the specified one. 459 the specified one.
321 460
322 $value = urxvt::GET_CUSTOM ($rend) 461 $value = urxvt::GET_CUSTOM $rend
323 Return the "custom" value: Every rendition has 5 bits for use by 462 Return the "custom" value: Every rendition has 5 bits for use by
324 extensions. They can be set and changed as you like and are 463 extensions. They can be set and changed as you like and are
325 initially zero. 464 initially zero.
326 465
327 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 466 $rend = urxvt::SET_CUSTOM $rend, $new_value
328 Change the custom value. 467 Change the custom value.
329 468
330 The "urxvt::anyevent" Class 469 The "urxvt::anyevent" Class
331 The sole purpose of this class is to deliver an interface to the 470 The sole purpose of this class is to deliver an interface to the
332 "AnyEvent" module - any module using it will work inside urxvt without 471 "AnyEvent" module - any module using it will work inside urxvt without
333 further work. The only exception is that you cannot wait on condition 472 further programming. The only exception is that you cannot wait on
334 variables, but non-blocking condvar use is ok. What this means is that 473 condition variables, but non-blocking condvar use is ok. What this means
335 you cannot use blocking APIs, but the non-blocking variant should work. 474 is that you cannot use blocking APIs, but the non-blocking variant
475 should work.
336 476
337 The "urxvt::term" Class 477 The "urxvt::term" Class
478 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
479 Creates a new terminal, very similar as if you had started it with
480 system "$rxvtname, arg...". $envhashref must be a reference to a
481 %ENV-like hash which defines the environment of the new terminal.
482
483 Croaks (and probably outputs an error message) if the new instance
484 couldn't be created. Returns "undef" if the new instance didn't
485 initialise perl, and the terminal object otherwise. The "init" and
486 "start" hooks will be called during this call.
487
338 $term->destroy 488 $term->destroy
339 Destroy the terminal object (close the window, free resources etc.). 489 Destroy the terminal object (close the window, free resources etc.).
490 Please note that rxvt will not exit as long as any event watchers
491 (timers, io watchers) are still active.
340 492
341 $isset = $term->option ($optval[, $set]) 493 $isset = $term->option ($optval[, $set])
342 Returns true if the option specified by $optval is enabled, and 494 Returns true if the option specified by $optval is enabled, and
343 optionally change it. All option values are stored by name in the 495 optionally change it. All option values are stored by name in the
344 hash %urxvt::OPTION. Options not enabled in this binary are not in 496 hash %urxvt::OPTION. Options not enabled in this binary are not in
… …
386 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 538 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
387 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 539 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
388 shade term_name title transparent transparent_all tripleclickwords 540 shade term_name title transparent transparent_all tripleclickwords
389 utmpInhibit visualBell 541 utmpInhibit visualBell
390 542
543 $value = $term->x_resource ($pattern)
544 Returns the X-Resource for the given pattern, excluding the program
545 or class name, i.e. "$term->x_resource ("boldFont")" should return
546 the same value as used by this instance of rxvt-unicode. Returns
547 "undef" if no resource with that pattern exists.
548
549 This method should only be called during the "on_start" hook, as
550 there is only one resource database per display, and later
551 invocations might return the wrong resources.
552
553 $success = $term->parse_keysym ($keysym_spec, $command_string)
554 Adds a keymap translation exactly as specified via a resource. See
555 the "keysym" resource in the rxvt(1) manpage.
556
391 $rend = $term->rstyle ([$new_rstyle]) 557 $rend = $term->rstyle ([$new_rstyle])
392 Return and optionally change the current rendition. Text that is 558 Return and optionally change the current rendition. Text that is
393 output by the terminal application will use this style. 559 output by the terminal application will use this style.
394 560
395 ($row, $col) = $term->screen_cur ([$row, $col]) 561 ($row, $col) = $term->screen_cur ([$row, $col])
… …
401 ($row, $col) = $term->selection_beg ([$row, $col]) 567 ($row, $col) = $term->selection_beg ([$row, $col])
402 ($row, $col) = $term->selection_end ([$row, $col]) 568 ($row, $col) = $term->selection_end ([$row, $col])
403 Return the current values of the selection mark, begin or end 569 Return the current values of the selection mark, begin or end
404 positions, and optionally set them to new values. 570 positions, and optionally set them to new values.
405 571
572 $term->selection_make ($eventtime[, $rectangular])
573 Tries to make a selection as set by "selection_beg" and
574 "selection_end". If $rectangular is true (default: false), a
575 rectangular selection will be made. This is the prefered function to
576 make a selection.
577
406 $success = $term->selection_grab ($eventtime) 578 $success = $term->selection_grab ($eventtime)
407 Try to request the primary selection from the server (for example, 579 Try to request the primary selection text from the server (for
408 as set by the next method). 580 example, as set by the next method). No visual feedback will be
581 given. This function is mostly useful from within "on_sel_grab"
582 hooks.
409 583
410 $oldtext = $term->selection ([$newtext]) 584 $oldtext = $term->selection ([$newtext])
411 Return the current selection text and optionally replace it by 585 Return the current selection text and optionally replace it by
412 $newtext. 586 $newtext.
413 587
414 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 588 $term->overlay_simple ($x, $y, $text)
415 overlay box. See the next method for details. # #=cut # #sub 589 Create a simple multi-line overlay box. See the next method for
416 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my 590 details.
417 @lines = split /\n/, $text; # # my $w = 0; # for (map
418 $self->strwidth ($_), @lines) { # $w = $_ if $w < $_; # } # #
419 $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
420 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
421 591
422 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 592 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
423 Create a new (empty) overlay at the given position with the given 593 Create a new (empty) overlay at the given position with the given
424 width/height. $rstyle defines the initial rendition style (default: 594 width/height. $rstyle defines the initial rendition style (default:
425 "OVERLAY_RSTYLE"). 595 "OVERLAY_RSTYLE").
… …
459 Convert the given text string into the corresponding locale 629 Convert the given text string into the corresponding locale
460 encoding. 630 encoding.
461 631
462 $string = $term->locale_decode ($octets) 632 $string = $term->locale_decode ($octets)
463 Convert the given locale-encoded octets into a perl string. 633 Convert the given locale-encoded octets into a perl string.
634
635 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
636 XORs the rendition values in the given span with the provided value
637 (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful
638 in refresh hooks to provide effects similar to the selection.
639
640 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
641 $rstyle2]])
642 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
643 whitespace will additionally be xored with the $rstyle2, which
644 defaults to "RS_RVid | RS_Uline", which removes reverse video again
645 and underlines it instead. Both styles *MUST NOT* contain font
646 styles.
647
648 $term->scr_bell
649 Ring the bell!
464 650
465 $term->scr_add_lines ($string) 651 $term->scr_add_lines ($string)
466 Write the given text string to the screen, as if output by the 652 Write the given text string to the screen, as if output by the
467 application running inside the terminal. It may not contain command 653 application running inside the terminal. It may not contain command
468 sequences (escape codes), but is free to use line feeds, carriage 654 sequences (escape codes), but is free to use line feeds, carriage
… …
482 Write the octets given in $data to the tty (i.e. as program input). 668 Write the octets given in $data to the tty (i.e. as program input).
483 To pass characters instead of octets, you should convert your 669 To pass characters instead of octets, you should convert your
484 strings first to the locale-specific encoding using 670 strings first to the locale-specific encoding using
485 "$term->locale_encode". 671 "$term->locale_encode".
486 672
673 $old_events = $term->pty_ev_events ([$new_events])
674 Replaces the event mask of the pty watcher by the given event mask.
675 Can be used to suppress input and output handling to the pty/tty.
676 See the description of "urxvt::timer->events". Make sure to always
677 restore the previous value.
678
487 $windowid = $term->parent 679 $windowid = $term->parent
488 Return the window id of the toplevel window. 680 Return the window id of the toplevel window.
489 681
490 $windowid = $term->vt 682 $windowid = $term->vt
491 Return the window id of the terminal window. 683 Return the window id of the terminal window.
684
685 $term->vt_emask_add ($x_event_mask)
686 Adds the specified events to the vt event mask. Useful e.g. when you
687 want to receive pointer events all the times:
688
689 $term->vt_emask_add (urxvt::PointerMotionMask);
492 690
493 $window_width = $term->width 691 $window_width = $term->width
494 $window_height = $term->height 692 $window_height = $term->height
495 $font_width = $term->fwidth 693 $font_width = $term->fwidth
496 $font_height = $term->fheight 694 $font_height = $term->fheight
… …
499 $terminal_columns = $term->ncol 697 $terminal_columns = $term->ncol
500 $has_focus = $term->focus 698 $has_focus = $term->focus
501 $is_mapped = $term->mapped 699 $is_mapped = $term->mapped
502 $max_scrollback = $term->saveLines 700 $max_scrollback = $term->saveLines
503 $nrow_plus_saveLines = $term->total_rows 701 $nrow_plus_saveLines = $term->total_rows
504 $lines_in_scrollback = $term->nsaved 702 $topmost_scrollback_row = $term->top_row
505 Return various integers describing terminal characteristics. 703 Return various integers describing terminal characteristics.
704
705 $x_display = $term->display_id
706 Return the DISPLAY used by rxvt-unicode.
707
708 $lc_ctype = $term->locale
709 Returns the LC_CTYPE category string used by this rxvt-unicode.
710
711 $env = $term->env
712 Returns a copy of the environment in effect for the terminal as a
713 hashref similar to "\%ENV".
506 714
507 $modifiermask = $term->ModLevel3Mask 715 $modifiermask = $term->ModLevel3Mask
508 $modifiermask = $term->ModMetaMask 716 $modifiermask = $term->ModMetaMask
509 $modifiermask = $term->ModNumLockMask 717 $modifiermask = $term->ModNumLockMask
510 Return the modifier masks corresponding to the "ISO Level 3 Shift" 718 Return the modifier masks corresponding to the "ISO Level 3 Shift"
511 (often AltGr), the meta key (often Alt) and the num lock key, if 719 (often AltGr), the meta key (often Alt) and the num lock key, if
512 applicable. 720 applicable.
513 721
514 $view_start = $term->view_start ([$newvalue]) 722 $view_start = $term->view_start ([$newvalue])
515 Returns the negative row number of the topmost line. Minimum value 723 Returns the row number of the topmost displayed line. Maximum value
516 is 0, which displays the normal terminal contents. Larger values 724 is 0, which displays the normal terminal contents. Lower values
517 scroll this many lines into the scrollback buffer. 725 scroll this many lines into the scrollback buffer.
518 726
519 $term->want_refresh 727 $term->want_refresh
520 Requests a screen refresh. At the next opportunity, rxvt-unicode 728 Requests a screen refresh. At the next opportunity, rxvt-unicode
521 will compare the on-screen display with its stored representation. 729 will compare the on-screen display with its stored representation.
… …
589 Return the row number of the first/last row of the line, 797 Return the row number of the first/last row of the line,
590 respectively. 798 respectively.
591 799
592 $offset = $line->offset_of ($row, $col) 800 $offset = $line->offset_of ($row, $col)
593 Returns the character offset of the given row|col pair within 801 Returns the character offset of the given row|col pair within
594 the logical line. 802 the logical line. Works for rows outside the line, too, and
803 returns corresponding offsets outside the string.
595 804
596 ($row, $col) = $line->coord_of ($offset) 805 ($row, $col) = $line->coord_of ($offset)
597 Translates a string offset into terminal coordinates again. 806 Translates a string offset into terminal coordinates again.
598 807
599 $text = $term->special_encode $string 808 $text = $term->special_encode $string
… …
626 Calls XUngrab for the most recent grab. Is called automatically on 835 Calls XUngrab for the most recent grab. Is called automatically on
627 evaluation errors, as it is better to lose the grab in the error 836 evaluation errors, as it is better to lose the grab in the error
628 case as the session. 837 case as the session.
629 838
630 The "urxvt::popup" Class 839 The "urxvt::popup" Class
840 $popup->add_title ($title)
841 Adds a non-clickable title to the popup.
842
843 $popup->add_separator ([$sepchr])
844 Creates a separator, optionally using the character given as
845 $sepchr.
846
847 $popup->add_button ($text, $cb)
848 Adds a clickable button to the popup. $cb is called whenever it is
849 selected.
850
851 $popup->add_toggle ($text, $cb, $initial_value)
852 Adds a toggle/checkbox item to the popup. Teh callback gets called
853 whenever it gets toggled, with a boolean indicating its value as its
854 first argument.
855
856 $popup->show
857 Displays the popup (which is initially hidden).
858
631 The "urxvt::timer" Class 859 The "urxvt::timer" Class
632 This class implements timer watchers/events. Time is represented as 860 This class implements timer watchers/events. Time is represented as a
633 a fractional number of seconds since the epoch. Example: 861 fractional number of seconds since the epoch. Example:
634 862
635 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 863 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
636 $term->{timer} = urxvt::timer 864 $term->{timer} = urxvt::timer
637 ->new 865 ->new
638 ->interval (1) 866 ->interval (1)
639 ->cb (sub { 867 ->cb (sub {
640 $term->{overlay}->set (0, 0, 868 $term->{overlay}->set (0, 0,
641 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 869 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
642 }); 870 });
643 871
644 $timer = new urxvt::timer 872 $timer = new urxvt::timer
645 Create a new timer object in started state. It is scheduled to 873 Create a new timer object in started state. It is scheduled to fire
646 fire immediately. 874 immediately.
647 875
648 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 876 $timer = $timer->cb (sub { my ($timer) = @_; ... })
649 Set the callback to be called when the timer triggers. 877 Set the callback to be called when the timer triggers.
650 878
651 $tstamp = $timer->at 879 $tstamp = $timer->at
652 Return the time this watcher will fire next. 880 Return the time this watcher will fire next.
653 881
654 $timer = $timer->set ($tstamp) 882 $timer = $timer->set ($tstamp)
655 Set the time the event is generated to $tstamp. 883 Set the time the event is generated to $tstamp.
656 884
657 $timer = $timer->interval ($interval) 885 $timer = $timer->interval ($interval)
658 Normally (and when $interval is 0), the timer will automatically 886 Normally (and when $interval is 0), the timer will automatically
659 stop after it has fired once. If $interval is non-zero, then the 887 stop after it has fired once. If $interval is non-zero, then the
660 timer is automatically rescheduled at the given intervals. 888 timer is automatically rescheduled at the given intervals.
661 889
662 $timer = $timer->start 890 $timer = $timer->start
663 Start the timer. 891 Start the timer.
664 892
665 $timer = $timer->start ($tstamp) 893 $timer = $timer->start ($tstamp)
666 Set the event trigger time to $tstamp and start the timer. 894 Set the event trigger time to $tstamp and start the timer.
667 895
668 $timer = $timer->stop 896 $timer = $timer->stop
669 Stop the timer. 897 Stop the timer.
670 898
671 The "urxvt::iow" Class 899 The "urxvt::iow" Class
672 This class implements io watchers/events. Example: 900 This class implements io watchers/events. Example:
673 901
674 $term->{socket} = ... 902 $term->{socket} = ...
675 $term->{iow} = urxvt::iow 903 $term->{iow} = urxvt::iow
676 ->new 904 ->new
677 ->fd (fileno $term->{socket}) 905 ->fd (fileno $term->{socket})
678 ->events (1) # wait for read data 906 ->events (urxvt::EVENT_READ)
679 ->start 907 ->start
680 ->cb (sub { 908 ->cb (sub {
681 my ($iow, $revents) = @_; 909 my ($iow, $revents) = @_;
682 # $revents must be 1 here, no need to check 910 # $revents must be 1 here, no need to check
683 sysread $term->{socket}, my $buf, 8192 911 sysread $term->{socket}, my $buf, 8192
684 or end-of-file; 912 or end-of-file;
685 }); 913 });
686 914
687 $iow = new urxvt::iow 915 $iow = new urxvt::iow
688 Create a new io watcher object in stopped state. 916 Create a new io watcher object in stopped state.
689 917
690 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 918 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
691 Set the callback to be called when io events are triggered. 919 Set the callback to be called when io events are triggered.
692 $reventmask is a bitset as described in the "events" method. 920 $reventmask is a bitset as described in the "events" method.
693 921
694 $iow = $iow->fd ($fd) 922 $iow = $iow->fd ($fd)
695 Set the filedescriptor (not handle) to watch. 923 Set the filedescriptor (not handle) to watch.
696 924
697 $iow = $iow->events ($eventmask) 925 $iow = $iow->events ($eventmask)
698 Set the event mask to watch. Bit #0 (value 1) enables watching 926 Set the event mask to watch. The only allowed values are
699 for read data, Bit #1 (value 2) enables watching for write data. 927 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
928 together, or "urxvt::EVENT_NONE".
700 929
701 $iow = $iow->start 930 $iow = $iow->start
702 Start watching for requested events on the given handle. 931 Start watching for requested events on the given handle.
703 932
704 $iow = $iow->stop 933 $iow = $iow->stop
705 Stop watching for events on the given filehandle. 934 Stop watching for events on the given filehandle.
706 935
707ENVIRONMENT 936ENVIRONMENT
708 URXVT_PERL_VERBOSITY 937 URXVT_PERL_VERBOSITY
709 This variable controls the verbosity level of the perl extension. 938 This variable controls the verbosity level of the perl extension. Higher
710 Higher numbers indicate more verbose output. 939 numbers indicate more verbose output.
711 940
712 == 0 - fatal messages 941 == 0 - fatal messages
713 >= 3 - script loading and management 942 >= 3 - script loading and management
714 >=10 - all events received 943 >=10 - all called hooks
944 >=11 - hook reutrn values
715 945
716AUTHOR 946AUTHOR
717 Marc Lehmann <pcg@goof.com> 947 Marc Lehmann <pcg@goof.com>
718 http://software.schmorp.de/pkg/rxvt-unicode 948 http://software.schmorp.de/pkg/rxvt-unicode
719 949

Diff Legend

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