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

Diff Legend

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