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.27 by root, Fri Jan 13 12:40:46 2006 UTC vs.
Revision 1.35 by root, Sun Jan 22 20:39:56 2006 UTC

1NAME 1NAME
2 urxvtperl - rxvt-unicode's embedded perl interpreter 2 rxvtperl - 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 urxvt using it: 12 # start a rxvt using it:
13 13
14 urxvt --perl-lib $HOME -pe grab_test 14 rxvt --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 urxvtd, 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
26PREPACKAGED EXTENSIONS 26PREPACKAGED EXTENSIONS
27 This section describes the extensions delivered with this release. You 27 This section describes the extensions delivered with this release. You
28 can find them in /usr/local/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 urxvt -pe <extensionname> 32 rxvt -pe <extensionname>
33
34 Or by adding them to the resource for extensions loaded by default:
35
36 URxvt.perl-ext-common: default,automove-background,selection-autotransform
33 37
34 selection (enabled by default) 38 selection (enabled by default)
35 (More) intelligent selection. This extension tries to be more 39 (More) intelligent selection. This extension tries to be more
36 intelligent when the user extends selections (double-click and 40 intelligent when the user extends selections (double-click and
37 further clicks). Right now, it tries to select words, urls and 41 further clicks). Right now, it tries to select words, urls and
… …
57 URxvt.selection.pattern-0: \\|([^|]+)\\| 61 URxvt.selection.pattern-0: \\|([^|]+)\\|
58 62
59 You can look at the source of the selection extension to see more 63 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. 64 interesting uses, such as parsing a line from beginning to end.
61 65
62 This extension also offers the following bindable keyboard command: 66 This extension also offers following bindable keyboard commands:
63 67
64 rot13 68 rot13
65 Rot-13 the selection when activated. Used via keyboard trigger: 69 Rot-13 the selection when activated. Used via keyboard trigger:
66 70
67 URxvt.keysym.C-M-r: perl:selection:rot13 71 URxvt.keysym.C-M-r: perl:selection:rot13
… …
71 options at runtime. 75 options at runtime.
72 76
73 selection-popup (enabled by default) 77 selection-popup (enabled by default)
74 Binds a popup menu to Ctrl-Button3 that lets you convert the 78 Binds a popup menu to Ctrl-Button3 that lets you convert the
75 selection text into various other formats/action (such as uri 79 selection text into various other formats/action (such as uri
76 unescaping, perl evalution, web-browser starting etc.), depending on 80 unescaping, perl evaluation, web-browser starting etc.), depending
77 content. 81 on content.
82
83 Other extensions can extend this popup menu by pushing a code
84 reference onto "@{ $term-"{selection_popup_hook} }>, that is called
85 whenever the popup is displayed.
86
87 It's sole argument is the popup menu, which can be modified. The
88 selection is in $_, which can be used to decide wether to add
89 something or not. It should either return nothing or a string and a
90 code reference. The string will be used as button text and the code
91 reference will be called when the button gets activated and should
92 transform $_.
93
94 The following will add an entry "a to b" that transforms all "a"s in
95 the selection to "b"s, but only if the selection currently contains
96 any "a"s:
97
98 push @{ $self->{term}{selection_popup_hook} }, sub {
99 /a/ ? ("a to be" => sub { s/a/b/g }
100 : ()
101 };
78 102
79 searchable-scrollback<hotkey> (enabled by default) 103 searchable-scrollback<hotkey> (enabled by default)
80 Adds regex search functionality to the scrollback buffer, triggered 104 Adds regex search functionality to the scrollback buffer, triggered
81 by a hotkey (default: "M-s"). While in search mode, normal terminal 105 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 106 input/output is suspended and a regex is displayed at the bottom of
… …
88 "End" jumps to the bottom. "Escape" leaves search mode and returns 112 "End" jumps to the bottom. "Escape" leaves search mode and returns
89 to the point where search was started, while "Enter" or "Return" 113 to the point where search was started, while "Enter" or "Return"
90 stay at the current position and additionally stores the first match 114 stay at the current position and additionally stores the first match
91 in the current line into the primary selection. 115 in the current line into the primary selection.
92 116
117 readline (enabled by default)
118 A support package that tries to make editing with readline easier.
119 At the moment, it reacts to clicking with the left mouse button by
120 trying to move the text cursor to this position. It does so by
121 generating as many cursor-left or cursor-right keypresses as
122 required (the this only works for programs that correctly support
123 wide characters).
124
125 To avoid too many false positives, this is only done when:
126
127 - the tty is in ICANON state.
128 - the text cursor is visible.
129 - the primary screen is currently being displayed.
130 - the mouse is on the same (multi-row-) line as the text cursor.
131
132 The normal selection mechanism isn't disabled, so quick successive
133 clicks might interfere with selection creation in harmless ways.
134
93 selection-autotransform 135 selection-autotransform
94 This selection allows you to do automatic transforms on a selection 136 This selection allows you to do automatic transforms on a selection
95 whenever a selection is made. 137 whenever a selection is made.
96 138
97 It works by specifying perl snippets (most useful is a single "s///" 139 It works by specifying perl snippets (most useful is a single "s///"
… …
108 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/ 150 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
109 151
110 And this example matches the same,but replaces it with vi-commands 152 And this example matches the same,but replaces it with vi-commands
111 you can paste directly into your (vi :) editor: 153 you can paste directly into your (vi :) editor:
112 154
113 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/ 155 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
114 156
115 Of course, this can be modified to suit your needs and your editor 157 Of course, this can be modified to suit your needs and your editor
116 :) 158 :)
117 159
118 To expand the example above to typical perl error messages ("XXX at 160 To expand the example above to typical perl error messages ("XXX at
119 FILENAME line YYY."), you need a slightly more elaborate solution: 161 FILENAME line YYY."), you need a slightly more elaborate solution:
120 162
121 URxvt.selection.pattern-0: ( at .*? line \\d+\\.) 163 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
122 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/ 164 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
123 165
124 The first line tells the selection code to treat the unchanging part 166 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 167 of every error message as a selection pattern, and the second line
126 transforms the message into vi commands to load the file. 168 transforms the message into vi commands to load the file.
169
170 tabbed
171 This transforms the terminal into a tabbar with additional
172 terminals, that is, it implements what is commonly refered to as
173 "tabbed terminal". The topmost line displays a "[NEW]" button,
174 which, when clicked, will add a new tab, followed by one button per
175 tab.
176
177 Clicking a button will activate that tab. Pressing Shift-Left and
178 Shift-Right will switch to the tab left or right of the current one,
179 while Shift-Down creates a new tab.
127 180
128 mark-urls 181 mark-urls
129 Uses per-line display filtering ("on_line_update") to underline urls 182 Uses per-line display filtering ("on_line_update") to underline urls
130 and make them clickable. When middle-clicked, the program specified 183 and make them clickable. When middle-clicked, the program specified
131 in the resource "urlLauncher" (default "x-www-browser") will be 184 in the resource "urlLauncher" (default "x-www-browser") will be
132 started with the URL as first argument. 185 started with the URL as first argument.
133 186
187 automove-background
188 This is basically a one-line extension that dynamically changes the
189 background pixmap offset to the window position, in effect creating
190 the same effect as pseudo transparency with a custom pixmap. No
191 scaling is supported in this mode. Exmaple:
192
193 rxvt -pixmap background.xpm -pe automove-background
194
134 block-graphics-to-ascii 195 block-graphics-to-ascii
135 A not very useful example of filtering all text output to the 196 A not very useful example of filtering all text output to the
136 terminal, by replacing all line-drawing characters (U+2500 .. 197 terminal, by replacing all line-drawing characters (U+2500 ..
137 U+259F) by a similar-looking ascii character. 198 U+259F) by a similar-looking ascii character.
138 199
… …
141 202
142 example-refresh-hooks 203 example-refresh-hooks
143 Displays a very simple digital clock in the upper right corner of 204 Displays a very simple digital clock in the upper right corner of
144 the window. Illustrates overwriting the refresh callbacks to create 205 the window. Illustrates overwriting the refresh callbacks to create
145 your own overlays or changes. 206 your own overlays or changes.
207
208 selection-pastebin
209 This is a little rarely useful extension that Uploads the selection
210 as textfile to a remote site (or does other things). (The
211 implementation is not currently secure for use in a multiuser
212 environment as it writes to /tmp directly.).
213
214 It listens to the "selection-pastebin:remote-pastebin" keyboard
215 command, i.e.
216
217 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
218
219 Pressing this combination runs a command with "%" replaced by the
220 name of the textfile. This command can be set via a resource:
221
222 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
223
224 And the default is likely not useful to anybody but the few people
225 around here :)
226
227 The name of the textfile is the hex encoded md5 sum of the
228 selection, so the same content should lead to the same filename.
229
230 After a successful upload the selection will be replaced by the text
231 given in the "selection-pastebin-url" resource (again, the % is the
232 placeholder for the filename):
233
234 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
146 235
147API DOCUMENTATION 236API DOCUMENTATION
148 General API Considerations 237 General API Considerations
149 All objects (such as terminals, time watchers etc.) are typical 238 All objects (such as terminals, time watchers etc.) are typical
150 reference-to-hash objects. The hash can be used to store anything you 239 reference-to-hash objects. The hash can be used to store anything you
… …
204 be called whenever the relevant event happens. 293 be called whenever the relevant event happens.
205 294
206 The first argument passed to them is an extension oject as described in 295 The first argument passed to them is an extension oject as described in
207 the in the "Extension Objects" section. 296 the in the "Extension Objects" section.
208 297
209 All of these hooks must return a boolean value. If it is true, then the 298 All of these hooks must return a boolean value. If any of the called
210 event counts as being *consumed*, and the invocation of other hooks is 299 hooks returns true, then the event counts as being *consumed*, and the
211 skipped, and the relevant action might not be carried out by the C++ 300 relevant action might not be carried out by the C++ code.
212 code.
213 301
214 *When in doubt, return a false value (preferably "()").* 302 *When in doubt, return a false value (preferably "()").*
215 303
216 on_init $term 304 on_init $term
217 Called after a new terminal object has been initialized, but before 305 Called after a new terminal object has been initialized, but before
218 windows are created or the command gets run. Most methods are unsafe 306 windows are created or the command gets run. Most methods are unsafe
219 to call or deliver senseless data, as terminal size and other 307 to call or deliver senseless data, as terminal size and other
220 characteristics have not yet been determined. You can safely query 308 characteristics have not yet been determined. You can safely query
221 and change resources, though. 309 and change resources and options, though. For many purposes the
310 "on_start" hook is a better place.
311
312 on_start $term
313 Called at the very end of initialisation of a new terminal, just
314 before trying to map (display) the toplevel and returning to the
315 mainloop.
316
317 on_destroy $term
318 Called whenever something tries to destroy terminal, before doing
319 anything yet. If this hook returns true, then destruction is
320 skipped, but this is rarely a good idea.
222 321
223 on_reset $term 322 on_reset $term
224 Called after the screen is "reset" for any reason, such as resizing 323 Called after the screen is "reset" for any reason, such as resizing
225 or control sequences. Here is where you can react on changes to 324 or control sequences. Here is where you can react on changes to
226 size-related variables. 325 size-related variables.
227 326
228 on_start $term 327 on_child_start $term, $pid
229 Called at the very end of initialisation of a new terminal, just 328 Called just after the child process has been "fork"ed.
230 before returning to the mainloop. 329
330 on_child_exit $term, $status
331 Called just after the child process has exited. $status is the
332 status from "waitpid".
231 333
232 on_sel_make $term, $eventtime 334 on_sel_make $term, $eventtime
233 Called whenever a selection has been made by the user, but before 335 Called whenever a selection has been made by the user, but before
234 the selection text is copied, so changes to the beginning, end or 336 the selection text is copied, so changes to the beginning, end or
235 type of the selection will be honored. 337 type of the selection will be honored.
… …
318 Called just after the screen gets redrawn. See "on_refresh_begin". 420 Called just after the screen gets redrawn. See "on_refresh_begin".
319 421
320 on_keyboard_command $term, $string 422 on_keyboard_command $term, $string
321 Called whenever the user presses a key combination that has a 423 Called whenever the user presses a key combination that has a
322 "perl:string" action bound to it (see description of the keysym 424 "perl:string" action bound to it (see description of the keysym
323 resource in the urxvt(1) manpage). 425 resource in the rxvt(1) manpage).
324 426
325 on_x_event $term, $event 427 on_x_event $term, $event
326 Called on every X event received on the vt window (and possibly 428 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 429 other windows). Should only be used as a last resort. Most event
328 structure members are not passed. 430 structure members are not passed.
… …
333 435
334 on_focus_out $term 436 on_focus_out $term
335 Called wheneever the window loses keyboard focus, before 437 Called wheneever the window loses keyboard focus, before
336 rxvt-unicode does focus out processing. 438 rxvt-unicode does focus out processing.
337 439
440 on_configure_notify $term, $event
441 on_property_notify $term, $event
338 on_key_press $term, $event, $keysym, $octets 442 on_key_press $term, $event, $keysym, $octets
339 on_key_release $term, $event, $keysym 443 on_key_release $term, $event, $keysym
340 on_button_press $term, $event 444 on_button_press $term, $event
341 on_button_release $term, $event 445 on_button_release $term, $event
342 on_motion_notify $term, $event 446 on_motion_notify $term, $event
… …
346 terminal If the hook returns true, then the even will be ignored by 450 terminal If the hook returns true, then the even will be ignored by
347 rxvt-unicode. 451 rxvt-unicode.
348 452
349 The event is a hash with most values as named by Xlib (see the 453 The event is a hash with most values as named by Xlib (see the
350 XEvent manpage), with the additional members "row" and "col", which 454 XEvent manpage), with the additional members "row" and "col", which
351 are the row and column under the mouse cursor. 455 are the (real, not screen-based) row and column under the mouse
456 cursor.
352 457
353 "on_key_press" additionally receives the string rxvt-unicode would 458 "on_key_press" additionally receives the string rxvt-unicode would
354 output, if any, in locale-specific encoding. 459 output, if any, in locale-specific encoding.
355 460
356 subwindow. 461 subwindow.
462
463 on_client_message $term, $event
464 on_wm_protocols $term, $event
465 on_wm_delete_window $term, $event
466 Called when various types of ClientMessage events are received (all
467 with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
357 468
358 Variables in the "urxvt" Package 469 Variables in the "urxvt" Package
359 $urxvt::LIBDIR 470 $urxvt::LIBDIR
360 The rxvt-unicode library directory, where, among other things, the 471 The rxvt-unicode library directory, where, among other things, the
361 perl modules and scripts are stored. 472 perl modules and scripts are stored.
… …
368 The basename of the installed binaries, usually "urxvt". 479 The basename of the installed binaries, usually "urxvt".
369 480
370 $urxvt::TERM 481 $urxvt::TERM
371 The current terminal. This variable stores the current "urxvt::term" 482 The current terminal. This variable stores the current "urxvt::term"
372 object, whenever a callback/hook is executing. 483 object, whenever a callback/hook is executing.
484
485 @urxvt::TERM_INIT
486 All coderefs in this array will be called as methods of the next
487 newly created "urxvt::term" object (during the "on_init" phase). The
488 array gets cleared before the codereferences that were in it are
489 being executed, so coderefs can push themselves onto it again if
490 they so desire.
491
492 This complements to the perl-eval commandline option, but gets
493 executed first.
494
495 @urxvt::TERM_EXT
496 Works similar to @TERM_INIT, but contains perl package/class names,
497 which get registered as normal extensions after calling the hooks in
498 @TERM_INIT but before other extensions. Gets cleared just like
499 @TERM_INIT.
373 500
374 Functions in the "urxvt" Package 501 Functions in the "urxvt" Package
375 urxvt::fatal $errormessage 502 urxvt::fatal $errormessage
376 Fatally aborts execution with the given error message. Avoid at all 503 Fatally aborts execution with the given error message. Avoid at all
377 costs! The only time this is acceptable is when the terminal process 504 costs! The only time this is acceptable is when the terminal process
… …
384 511
385 Using this function has the advantage that its output ends up in the 512 Using this function has the advantage that its output ends up in the
386 correct place, e.g. on stderr of the connecting urxvtc client. 513 correct place, e.g. on stderr of the connecting urxvtc client.
387 514
388 Messages have a size limit of 1023 bytes currently. 515 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 516
395 $time = urxvt::NOW 517 $time = urxvt::NOW
396 Returns the "current time" (as per the event loop). 518 Returns the "current time" (as per the event loop).
397 519
398 urxvt::CurrentTime 520 urxvt::CurrentTime
… …
474 initialise perl, and the terminal object otherwise. The "init" and 596 initialise perl, and the terminal object otherwise. The "init" and
475 "start" hooks will be called during this call. 597 "start" hooks will be called during this call.
476 598
477 $term->destroy 599 $term->destroy
478 Destroy the terminal object (close the window, free resources etc.). 600 Destroy the terminal object (close the window, free resources etc.).
479 Please note that urxvt will not exit as long as any event watchers 601 Please note that rxvt will not exit as long as any event watchers
480 (timers, io watchers) are still active. 602 (timers, io watchers) are still active.
603
604 $term->exec_async ($cmd[, @args])
605 Works like the combination of the "fork"/"exec" builtins, which
606 executes ("starts") programs in the background. This function takes
607 care of setting the user environment before exec'ing the command
608 (e.g. "PATH") and should be preferred over explicit calls to "exec"
609 or "system".
610
611 Returns the pid of the subprocess or "undef" on error.
481 612
482 $isset = $term->option ($optval[, $set]) 613 $isset = $term->option ($optval[, $set])
483 Returns true if the option specified by $optval is enabled, and 614 Returns true if the option specified by $optval is enabled, and
484 optionally change it. All option values are stored by name in the 615 optionally change it. All option values are stored by name in the
485 hash %urxvt::OPTION. Options not enabled in this binary are not in 616 hash %urxvt::OPTION. Options not enabled in this binary are not in
… …
488 Here is a a likely non-exhaustive list of option names, please see 619 Here is a a likely non-exhaustive list of option names, please see
489 the source file /src/optinc.h to see the actual list: 620 the source file /src/optinc.h to see the actual list:
490 621
491 borderLess console cursorBlink cursorUnderline hold iconic insecure 622 borderLess console cursorBlink cursorUnderline hold iconic insecure
492 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 623 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
493 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 624 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
494 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 625 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
495 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 626 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
496 tripleclickwords utmpInhibit visualBell 627 transparent tripleclickwords utmpInhibit visualBell
497 628
498 $value = $term->resource ($name[, $newval]) 629 $value = $term->resource ($name[, $newval])
499 Returns the current resource value associated with a given name and 630 Returns the current resource value associated with a given name and
500 optionally sets a new value. Setting values is most useful in the 631 optionally sets a new value. Setting values is most useful in the
501 "init" hook. Unset resources are returned and accepted as "undef". 632 "init" hook. Unset resources are returned and accepted as "undef".
… …
518 649
519 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 650 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
520 borderLess color cursorBlink cursorUnderline cutchars delete_key 651 borderLess color cursorBlink cursorUnderline cutchars delete_key
521 display_name embed ext_bwidth fade font geometry hold iconName 652 display_name embed ext_bwidth fade font geometry hold iconName
522 imFont imLocale inputMethod insecure int_bwidth intensityStyles 653 imFont imLocale inputMethod insecure int_bwidth intensityStyles
523 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 654 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
524 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 655 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
525 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 656 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
526 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 657 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
527 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 658 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
528 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 659 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
660 secondaryScreen secondaryScroll selectstyle shade term_name title
529 shade term_name title transparent transparent_all tripleclickwords 661 transient_for transparent transparent_all tripleclickwords utmpInhibit
530 utmpInhibit visualBell 662 visualBell
531 663
532 $value = $term->x_resource ($pattern) 664 $value = $term->x_resource ($pattern)
533 Returns the X-Resource for the given pattern, excluding the program 665 Returns the X-Resource for the given pattern, excluding the program
534 or class name, i.e. "$term->x_resource ("boldFont")" should return 666 or class name, i.e. "$term->x_resource ("boldFont")" should return
535 the same value as used by this instance of rxvt-unicode. Returns 667 the same value as used by this instance of rxvt-unicode. Returns
… …
539 there is only one resource database per display, and later 671 there is only one resource database per display, and later
540 invocations might return the wrong resources. 672 invocations might return the wrong resources.
541 673
542 $success = $term->parse_keysym ($keysym_spec, $command_string) 674 $success = $term->parse_keysym ($keysym_spec, $command_string)
543 Adds a keymap translation exactly as specified via a resource. See 675 Adds a keymap translation exactly as specified via a resource. See
544 the "keysym" resource in the urxvt(1) manpage. 676 the "keysym" resource in the rxvt(1) manpage.
545 677
546 $rend = $term->rstyle ([$new_rstyle]) 678 $rend = $term->rstyle ([$new_rstyle])
547 Return and optionally change the current rendition. Text that is 679 Return and optionally change the current rendition. Text that is
548 output by the terminal application will use this style. 680 output by the terminal application will use this style.
549 681
… …
646 778
647 Normally its not a good idea to use this function, as programs might 779 Normally its not a good idea to use this function, as programs might
648 be confused by changes in cursor position or scrolling. Its useful 780 be confused by changes in cursor position or scrolling. Its useful
649 inside a "on_add_lines" hook, though. 781 inside a "on_add_lines" hook, though.
650 782
783 $term->scr_change_screen ($screen)
784 Switch to given screen - 0 primary, 1 secondary.
785
651 $term->cmd_parse ($octets) 786 $term->cmd_parse ($octets)
652 Similar to "scr_add_lines", but the argument must be in the 787 Similar to "scr_add_lines", but the argument must be in the
653 locale-specific encoding of the terminal and can contain command 788 locale-specific encoding of the terminal and can contain command
654 sequences (escape codes) that will be interpreted. 789 sequences (escape codes) that will be interpreted.
655 790
… …
662 $old_events = $term->pty_ev_events ([$new_events]) 797 $old_events = $term->pty_ev_events ([$new_events])
663 Replaces the event mask of the pty watcher by the given event mask. 798 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. 799 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 800 See the description of "urxvt::timer->events". Make sure to always
666 restore the previous value. 801 restore the previous value.
802
803 $fd = $term->pty_fd
804 Returns the master file descriptor for the pty in use, or -1 if no
805 pty is used.
667 806
668 $windowid = $term->parent 807 $windowid = $term->parent
669 Return the window id of the toplevel window. 808 Return the window id of the toplevel window.
670 809
671 $windowid = $term->vt 810 $windowid = $term->vt
… …
686 $terminal_columns = $term->ncol 825 $terminal_columns = $term->ncol
687 $has_focus = $term->focus 826 $has_focus = $term->focus
688 $is_mapped = $term->mapped 827 $is_mapped = $term->mapped
689 $max_scrollback = $term->saveLines 828 $max_scrollback = $term->saveLines
690 $nrow_plus_saveLines = $term->total_rows 829 $nrow_plus_saveLines = $term->total_rows
691 $lines_in_scrollback = $term->nsaved 830 $topmost_scrollback_row = $term->top_row
692 Return various integers describing terminal characteristics. 831 Return various integers describing terminal characteristics.
693 832
694 $x_display = $term->display_id 833 $x_display = $term->display_id
695 Return the DISPLAY used by rxvt-unicode. 834 Return the DISPLAY used by rxvt-unicode.
696 835
… …
706 $modifiermask = $term->ModNumLockMask 845 $modifiermask = $term->ModNumLockMask
707 Return the modifier masks corresponding to the "ISO Level 3 Shift" 846 Return the modifier masks corresponding to the "ISO Level 3 Shift"
708 (often AltGr), the meta key (often Alt) and the num lock key, if 847 (often AltGr), the meta key (often Alt) and the num lock key, if
709 applicable. 848 applicable.
710 849
850 $screen = $term->current_screen
851 Returns the currently displayed screen (0 primary, 1 secondary).
852
853 $cursor_is_hidden = $term->hidden_cursor
854 Returns wether the cursor is currently hidden or not.
855
711 $view_start = $term->view_start ([$newvalue]) 856 $view_start = $term->view_start ([$newvalue])
712 Returns the negative row number of the topmost line. Minimum value 857 Returns the row number of the topmost displayed line. Maximum value
713 is 0, which displays the normal terminal contents. Larger values 858 is 0, which displays the normal terminal contents. Lower values
714 scroll this many lines into the scrollback buffer. 859 scroll this many lines into the scrollback buffer.
715 860
716 $term->want_refresh 861 $term->want_refresh
717 Requests a screen refresh. At the next opportunity, rxvt-unicode 862 Requests a screen refresh. At the next opportunity, rxvt-unicode
718 will compare the on-screen display with its stored representation. 863 will compare the on-screen display with its stored representation.
… …
731 line, starting at column $start_col (default 0), which is useful to 876 line, starting at column $start_col (default 0), which is useful to
732 replace only parts of a line. The font index in the rendition will 877 replace only parts of a line. The font index in the rendition will
733 automatically be updated. 878 automatically be updated.
734 879
735 $text is in a special encoding: tabs and wide characters that use 880 $text is in a special encoding: tabs and wide characters that use
736 more than one cell when displayed are padded with urxvt::NOCHAR 881 more than one cell when displayed are padded with $urxvt::NOCHAR
737 characters ("chr 65535"). Characters with combining characters and 882 (chr 65535) characters. Characters with combining characters and
738 other characters that do not fit into the normal tetx encoding will 883 other characters that do not fit into the normal tetx encoding will
739 be replaced with characters in the private use area. 884 be replaced with characters in the private use area.
740 885
741 You have to obey this encoding when changing text. The advantage is 886 You have to obey this encoding when changing text. The advantage is
742 that "substr" and similar functions work on screen cells and not on 887 that "substr" and similar functions work on screen cells and not on
… …
822 967
823 $term->ungrab 968 $term->ungrab
824 Calls XUngrab for the most recent grab. Is called automatically on 969 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 970 evaluation errors, as it is better to lose the grab in the error
826 case as the session. 971 case as the session.
972
973 $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
974 $atom_name = $term->XGetAtomName ($atom)
975 @atoms = $term->XListProperties ($window)
976 ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
977 $term->XChangeWindowProperty ($window, $property, $type, $format,
978 $octets)
979 $term->XDeleteProperty ($window, $property)
980 $window = $term->DefaultRootWindow
981 $term->XReparentWindow ($window, $parent, [$x, $y])
982 $term->XMapWindow ($window)
983 $term->XUnmapWindow ($window)
984 $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
985 ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
986 $y)
987 $term->XChangeInput ($window, $add_events[, $del_events])
988 Various X or X-related functions. The $term object only serves as
989 the source of the display, otherwise those functions map
990 more-or-less directory onto the X functions of the same name.
827 991
828 The "urxvt::popup" Class 992 The "urxvt::popup" Class
829 $popup->add_title ($title) 993 $popup->add_title ($title)
830 Adds a non-clickable title to the popup. 994 Adds a non-clickable title to the popup.
831 995
… …
879 $timer = $timer->start 1043 $timer = $timer->start
880 Start the timer. 1044 Start the timer.
881 1045
882 $timer = $timer->start ($tstamp) 1046 $timer = $timer->start ($tstamp)
883 Set the event trigger time to $tstamp and start the timer. 1047 Set the event trigger time to $tstamp and start the timer.
1048
1049 $timer = $timer->after ($delay)
1050 Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
884 1051
885 $timer = $timer->stop 1052 $timer = $timer->stop
886 Stop the timer. 1053 Stop the timer.
887 1054
888 The "urxvt::iow" Class 1055 The "urxvt::iow" Class
… …
920 Start watching for requested events on the given handle. 1087 Start watching for requested events on the given handle.
921 1088
922 $iow = $iow->stop 1089 $iow = $iow->stop
923 Stop watching for events on the given filehandle. 1090 Stop watching for events on the given filehandle.
924 1091
1092 The "urxvt::iw" Class
1093 This class implements idle watchers, that get called automatically when
1094 the process is idle. They should return as fast as possible, after doing
1095 some useful work.
1096
1097 $iw = new urxvt::iw
1098 Create a new idle watcher object in stopped state.
1099
1100 $iw = $iw->cb (sub { my ($iw) = @_; ... })
1101 Set the callback to be called when the watcher triggers.
1102
1103 $timer = $timer->start
1104 Start the watcher.
1105
1106 $timer = $timer->stop
1107 Stop the watcher.
1108
1109 The "urxvt::pw" Class
1110 This class implements process watchers. They create an event whenever a
1111 process exits, after which they stop automatically.
1112
1113 my $pid = fork;
1114 ...
1115 $term->{pw} = urxvt::pw
1116 ->new
1117 ->start ($pid)
1118 ->cb (sub {
1119 my ($pw, $exit_status) = @_;
1120 ...
1121 });
1122
1123 $pw = new urxvt::pw
1124 Create a new process watcher in stopped state.
1125
1126 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1127 Set the callback to be called when the timer triggers.
1128
1129 $pw = $timer->start ($pid)
1130 Tells the wqtcher to start watching for process $pid.
1131
1132 $pw = $pw->stop
1133 Stop the watcher.
1134
925ENVIRONMENT 1135ENVIRONMENT
926 URXVT_PERL_VERBOSITY 1136 URXVT_PERL_VERBOSITY
927 This variable controls the verbosity level of the perl extension. Higher 1137 This variable controls the verbosity level of the perl extension. Higher
928 numbers indicate more verbose output. 1138 numbers indicate more verbose output.
929 1139

Diff Legend

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