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.35 by root, Sun Jan 22 20:39:56 2006 UTC vs.
Revision 1.45 by root, Thu Nov 2 17:37:47 2006 UTC

… …
12 # start a rxvt using it: 12 # start a rxvt using it:
13 13
14 rxvt --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 Every time 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
… …
53 URxvt.selection.pattern-1: perl-regex 53 URxvt.selection.pattern-1: perl-regex
54 ... 54 ...
55 55
56 The index number (0, 1...) must not have any holes, and each regex 56 The index number (0, 1...) must not have any holes, and each regex
57 must contain at least one pair of capturing parentheses, which will 57 must contain at least one pair of capturing parentheses, which will
58 be used for the match. For example, the followign adds a regex that 58 be used for the match. For example, the following adds a regex that
59 matches everything between two vertical bars: 59 matches everything between two vertical bars:
60 60
61 URxvt.selection.pattern-0: \\|([^|]+)\\| 61 URxvt.selection.pattern-0: \\|([^|]+)\\|
62
63 Another example: Programs I use often output "absolute path: " at
64 the beginning of a line when they process multiple files. The
65 following pattern matches the filename (note, there is a single
66 space at the very end):
67
68 URxvt.selection.pattern-0: ^(/[^:]+):\
62 69
63 You can look at the source of the selection extension to see more 70 You can look at the source of the selection extension to see more
64 interesting uses, such as parsing a line from beginning to end. 71 interesting uses, such as parsing a line from beginning to end.
65 72
66 This extension also offers following bindable keyboard commands: 73 This extension also offers following bindable keyboard commands:
… …
71 URxvt.keysym.C-M-r: perl:selection:rot13 78 URxvt.keysym.C-M-r: perl:selection:rot13
72 79
73 option-popup (enabled by default) 80 option-popup (enabled by default)
74 Binds a popup menu to Ctrl-Button2 that lets you toggle (some) 81 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
75 options at runtime. 82 options at runtime.
83
84 Other extensions can extend this popup menu by pushing a code
85 reference onto "@{ $term-"{option_popup_hook} }>, which gets called
86 whenever the popup is being displayed.
87
88 It's sole argument is the popup menu, which can be modified. It
89 should either return nothing or a string, the initial boolean value
90 and a code reference. The string will be used as button text and the
91 code reference will be called when the toggle changes, with the new
92 boolean value as first argument.
93
94 The following will add an entry "myoption" that changes
95 "$self-"{myoption}>:
96
97 push @{ $self->{term}{option_popup_hook} }, sub {
98 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
99 };
76 100
77 selection-popup (enabled by default) 101 selection-popup (enabled by default)
78 Binds a popup menu to Ctrl-Button3 that lets you convert the 102 Binds a popup menu to Ctrl-Button3 that lets you convert the
79 selection text into various other formats/action (such as uri 103 selection text into various other formats/action (such as uri
80 unescaping, perl evaluation, web-browser starting etc.), depending 104 unescaping, perl evaluation, web-browser starting etc.), depending
81 on content. 105 on content.
82 106
83 Other extensions can extend this popup menu by pushing a code 107 Other extensions can extend this popup menu by pushing a code
84 reference onto "@{ $term-"{selection_popup_hook} }>, that is called 108 reference onto "@{ $term-"{selection_popup_hook} }>, which gets
85 whenever the popup is displayed. 109 called whenever the popup is being displayed.
86 110
87 It's sole argument is the popup menu, which can be modified. The 111 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 112 selection is in $_, which can be used to decide whether to add
89 something or not. It should either return nothing or a string and a 113 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 114 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 115 reference will be called when the button gets activated and should
92 transform $_. 116 transform $_.
93 117
… …
112 "End" jumps to the bottom. "Escape" leaves search mode and returns 136 "End" jumps to the bottom. "Escape" leaves search mode and returns
113 to the point where search was started, while "Enter" or "Return" 137 to the point where search was started, while "Enter" or "Return"
114 stay at the current position and additionally stores the first match 138 stay at the current position and additionally stores the first match
115 in the current line into the primary selection. 139 in the current line into the primary selection.
116 140
141 The regex defaults to "(?i)", resulting in a case-insensitive
142 search. To get a case-sensitive search you can delete this prefix
143 using "BackSpace" or simply use an uppercase character which removes
144 the "(?i)" prefix.
145
146 See perlre for more info about perl regular expression syntax.
147
117 readline (enabled by default) 148 readline (enabled by default)
118 A support package that tries to make editing with readline easier. 149 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 150 At the moment, it reacts to clicking shift-left mouse button by
120 trying to move the text cursor to this position. It does so by 151 trying to move the text cursor to this position. It does so by
121 generating as many cursor-left or cursor-right keypresses as 152 generating as many cursor-left or cursor-right keypresses as
122 required (the this only works for programs that correctly support 153 required (the this only works for programs that correctly support
123 wide characters). 154 wide characters).
124 155
… …
167 of every error message as a selection pattern, and the second line 198 of every error message as a selection pattern, and the second line
168 transforms the message into vi commands to load the file. 199 transforms the message into vi commands to load the file.
169 200
170 tabbed 201 tabbed
171 This transforms the terminal into a tabbar with additional 202 This transforms the terminal into a tabbar with additional
172 terminals, that is, it implements what is commonly refered to as 203 terminals, that is, it implements what is commonly referred to as
173 "tabbed terminal". The topmost line displays a "[NEW]" button, 204 "tabbed terminal". The topmost line displays a "[NEW]" button,
174 which, when clicked, will add a new tab, followed by one button per 205 which, when clicked, will add a new tab, followed by one button per
175 tab. 206 tab.
176 207
177 Clicking a button will activate that tab. Pressing Shift-Left and 208 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, 209 Shift-Right will switch to the tab left or right of the current one,
179 while Shift-Down creates a new tab. 210 while Shift-Down creates a new tab.
180 211
181 mark-urls 212 The tabbar itself can be configured similarly to a normal terminal,
213 but with a resource class of "URxvt.tabbed". In addition, it
214 supports the following four resources (shown with defaults):
215
216 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
217 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
218 URxvt.tabbed.tab-fg: <colour-index, default 0>
219 URxvt.tabbed.tab-bg: <colour-index, default 1>
220
221 See *COLOR AND GRAPHICS* in the rxvt(1) manpage for valid indices.
222
223 matcher
182 Uses per-line display filtering ("on_line_update") to underline urls 224 Uses per-line display filtering ("on_line_update") to underline text
183 and make them clickable. When middle-clicked, the program specified 225 matching a certain pattern and make it clickable. When clicked with
184 in the resource "urlLauncher" (default "x-www-browser") will be 226 the mouse button specified in the "matcher.button" resource (default
185 started with the URL as first argument. 227 2, or middle), the program specified in the "matcher.launcher"
228 resource (default, the "urlLauncher" resource, "sensible-browser")
229 will be started with the matched text as first argument. The default
230 configuration is suitable for matching URLs and launching a web
231 browser, like the former "mark-urls" extension.
232
233 The default pattern to match URLs can be overridden with the
234 "matcher.pattern.0" resource, and additional patterns can be
235 specified with numbered patterns, in a manner similar to the
236 "selection" extension. The launcher can also be overridden on a
237 per-pattern basis.
238
239 Example configuration:
240
241 URxvt.perl-ext: default,matcher
242 URxvt.urlLauncher: sensible-browser
243 URxvt.matcher.button: 1
244 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
245 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
246 URxvt.matcher.launcher.2: gvim +$2 $1
247
248 xim-onthespot
249 This (experimental) perl extension implements OnTheSpot editing. It
250 does not work perfectly, and some input methods don't seem to work
251 well with OnTheSpot editing in general, but it seems to work at
252 leats for SCIM and kinput2.
253
254 You enable it by specifying this extension and a preedit style of
255 "OnTheSpot", i.e.:
256
257 rxvt -pt OnTheSpot -pe xim-onthespot
258
259 kuake<hotkey>
260 A very primitive quake-console-like extension. It was inspired by a
261 description of how the programs "kuake" and "yakuake" work: Whenever
262 the user presses a global accelerator key (by default "F10"), the
263 terminal will show or hide itself. Another press of the accelerator
264 key will hide or show it again.
265
266 Initially, the window will not be shown when using this extension.
267
268 This is useful if you need a single terminal thats not using any
269 desktop space most of the time but is quickly available at the press
270 of a key.
271
272 The accelerator key is grabbed regardless of any modifiers, so this
273 extension will actually grab a physical key just for this function.
274
275 If you want a quake-like animation, tell your window manager to do
276 so (fvwm can do it).
186 277
187 automove-background 278 automove-background
188 This is basically a one-line extension that dynamically changes the 279 This is basically a very small extension that dynamically changes
189 background pixmap offset to the window position, in effect creating 280 the background pixmap offset to the window position, in effect
190 the same effect as pseudo transparency with a custom pixmap. No 281 creating the same effect as pseudo transparency with a custom
191 scaling is supported in this mode. Exmaple: 282 pixmap. No scaling is supported in this mode. Example:
192 283
193 rxvt -pixmap background.xpm -pe automove-background 284 rxvt -pixmap background.xpm -pe automove-background
194 285
195 block-graphics-to-ascii 286 block-graphics-to-ascii
196 A not very useful example of filtering all text output to the 287 A not very useful example of filtering all text output to the
197 terminal, by replacing all line-drawing characters (U+2500 .. 288 terminal by replacing all line-drawing characters (U+2500 .. U+259F)
198 U+259F) by a similar-looking ascii character. 289 by a similar-looking ascii character.
199 290
200 digital-clock 291 digital-clock
201 Displays a digital clock using the built-in overlay. 292 Displays a digital clock using the built-in overlay.
202 293
203 example-refresh-hooks 294 remote-clipboard
204 Displays a very simple digital clock in the upper right corner of 295 Somewhat of a misnomer, this extension adds two menu entries to the
205 the window. Illustrates overwriting the refresh callbacks to create 296 selection popup that allows one ti run external commands to store
206 your own overlays or changes. 297 the selection somewhere and fetch it again.
298
299 We use it to implement a "distributed selection mechanism", which
300 just means that one command uploads the file to a remote server, and
301 another reads it.
302
303 The commands can be set using the "URxvt.remote-selection.store" and
304 "URxvt.remote-selection.fetch" resources. The first should read the
305 selection to store from STDIN (always in UTF-8), the second should
306 provide the selection data on STDOUT (also in UTF-8).
307
308 The defaults (which are likely useless to you) use rsh and cat:
309
310 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
311 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
207 312
208 selection-pastebin 313 selection-pastebin
209 This is a little rarely useful extension that Uploads the selection 314 This is a little rarely useful extension that Uploads the selection
210 as textfile to a remote site (or does other things). (The 315 as textfile to a remote site (or does other things). (The
211 implementation is not currently secure for use in a multiuser 316 implementation is not currently secure for use in a multiuser
… …
230 After a successful upload the selection will be replaced by the text 335 After a successful upload the selection will be replaced by the text
231 given in the "selection-pastebin-url" resource (again, the % is the 336 given in the "selection-pastebin-url" resource (again, the % is the
232 placeholder for the filename): 337 placeholder for the filename):
233 338
234 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 339 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
340
341 *Note to xrdb users:* xrdb uses the C preprocessor, which might
342 interpret the double "/" characters as comment start. Use "\057\057"
343 instead, which works regardless of wether xrdb is used to parse the
344 resource file or not.
345
346 example-refresh-hooks
347 Displays a very simple digital clock in the upper right corner of
348 the window. Illustrates overwriting the refresh callbacks to create
349 your own overlays or changes.
235 350
236API DOCUMENTATION 351API DOCUMENTATION
237 General API Considerations 352 General API Considerations
238 All objects (such as terminals, time watchers etc.) are typical 353 All objects (such as terminals, time watchers etc.) are typical
239 reference-to-hash objects. The hash can be used to store anything you 354 reference-to-hash objects. The hash can be used to store anything you
… …
262 $octets 377 $octets
263 Either binary data or - more common - a text string encoded in a 378 Either binary data or - more common - a text string encoded in a
264 locale-specific way. 379 locale-specific way.
265 380
266 Extension Objects 381 Extension Objects
267 Very perl extension is a perl class. A separate perl object is created 382 Every perl extension is a perl class. A separate perl object is created
268 for each terminal and each extension and passed as the first parameter 383 for each terminal, and each terminal has its own set of extenion
269 to hooks. So extensions can use their $self object without having to 384 objects, which are passed as the first parameter to hooks. So extensions
270 think about other extensions, with the exception of methods and members 385 can use their $self object without having to think about clashes with
386 other extensions or other terminals, with the exception of methods and
271 that begin with an underscore character "_": these are reserved for 387 members that begin with an underscore character "_": these are reserved
272 internal use. 388 for internal use.
273 389
274 Although it isn't a "urxvt::term" object, you can call all methods of 390 Although it isn't a "urxvt::term" object, you can call all methods of
275 the "urxvt::term" class on this object. 391 the "urxvt::term" class on this object.
276 392
277 It has the following methods and data members: 393 It has the following methods and data members:
… …
290 406
291 Hooks 407 Hooks
292 The following subroutines can be declared in extension files, and will 408 The following subroutines can be declared in extension files, and will
293 be called whenever the relevant event happens. 409 be called whenever the relevant event happens.
294 410
295 The first argument passed to them is an extension oject as described in 411 The first argument passed to them is an extension object as described in
296 the in the "Extension Objects" section. 412 the in the "Extension Objects" section.
297 413
298 All of these hooks must return a boolean value. If any of the called 414 All of these hooks must return a boolean value. If any of the called
299 hooks returns true, then the event counts as being *consumed*, and the 415 hooks returns true, then the event counts as being *consumed*, and the
300 relevant action might not be carried out by the C++ code. 416 relevant action might not be carried out by the C++ code.
… …
310 "on_start" hook is a better place. 426 "on_start" hook is a better place.
311 427
312 on_start $term 428 on_start $term
313 Called at the very end of initialisation of a new terminal, just 429 Called at the very end of initialisation of a new terminal, just
314 before trying to map (display) the toplevel and returning to the 430 before trying to map (display) the toplevel and returning to the
315 mainloop. 431 main loop.
316 432
317 on_destroy $term 433 on_destroy $term
318 Called whenever something tries to destroy terminal, before doing 434 Called whenever something tries to destroy terminal, when the
319 anything yet. If this hook returns true, then destruction is 435 terminal is still fully functional (not for long, though).
320 skipped, but this is rarely a good idea.
321 436
322 on_reset $term 437 on_reset $term
323 Called after the screen is "reset" for any reason, such as resizing 438 Called after the screen is "reset" for any reason, such as resizing
324 or control sequences. Here is where you can react on changes to 439 or control sequences. Here is where you can react on changes to
325 size-related variables. 440 size-related variables.
… …
344 Called whenever a selection has been copied, but before the 459 Called whenever a selection has been copied, but before the
345 selection is requested from the server. The selection text can be 460 selection is requested from the server. The selection text can be
346 queried and changed by calling "$term->selection". 461 queried and changed by calling "$term->selection".
347 462
348 Returning a true value aborts selection grabbing. It will still be 463 Returning a true value aborts selection grabbing. It will still be
349 hilighted. 464 highlighted.
350 465
351 on_sel_extend $term 466 on_sel_extend $term
352 Called whenever the user tries to extend the selection (e.g. with a 467 Called whenever the user tries to extend the selection (e.g. with a
353 double click) and is either supposed to return false (normal 468 double click) and is either supposed to return false (normal
354 operation), or should extend the selection itelf and return true to 469 operation), or should extend the selection itself and return true to
355 suppress the built-in processing. This can happen multiple times, as 470 suppress the built-in processing. This can happen multiple times, as
356 long as the callback returns true, it will be called on every 471 long as the callback returns true, it will be called on every
357 further click by the user and is supposed to enlarge the selection 472 further click by the user and is supposed to enlarge the selection
358 more and more, if possible. 473 more and more, if possible.
359 474
360 See the selection example extension. 475 See the selection example extension.
361 476
362 on_view_change $term, $offset 477 on_view_change $term, $offset
363 Called whenever the view offset changes, i..e the user or program 478 Called whenever the view offset changes, i.e. the user or program
364 scrolls. Offset 0 means display the normal terminal, positive values 479 scrolls. Offset 0 means display the normal terminal, positive values
365 show this many lines of scrollback. 480 show this many lines of scrollback.
366 481
367 on_scroll_back $term, $lines, $saved 482 on_scroll_back $term, $lines, $saved
368 Called whenever lines scroll out of the terminal area into the 483 Called whenever lines scroll out of the terminal area into the
… …
371 486
372 It is called before lines are scrolled out (so rows 0 .. min ($lines 487 It is called before lines are scrolled out (so rows 0 .. min ($lines
373 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is 488 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
374 the total number of lines that will be in the scrollback buffer. 489 the total number of lines that will be in the scrollback buffer.
375 490
491 on_osc_seq $term, $op, $args
492 Called on every OSC sequence and can be used to suppress it or
493 modify its behaviour. The default should be to return an empty list.
494 A true value suppresses execution of the request completely. Make
495 sure you don't get confused by recursive invocations when you output
496 an osc sequence within this callback.
497
498 "on_osc_seq_perl" should be used for new behaviour.
499
376 on_osc_seq $term, $string 500 on_osc_seq_perl $term, $string
377 Called whenever the ESC ] 777 ; string ST command sequence (OSC = 501 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
378 operating system command) is processed. Cursor position and other 502 operating system command) is processed. Cursor position and other
379 state information is up-to-date when this happens. For 503 state information is up-to-date when this happens. For
380 interoperability, the string should start with the extension name 504 interoperability, the string should start with the extension name
381 and a colon, to distinguish it from commands for other extensions, 505 and a colon, to distinguish it from commands for other extensions,
382 and this might be enforced in the future. 506 and this might be enforced in the future.
383 507
384 Be careful not ever to trust (in a security sense) the data you 508 Be careful not ever to trust (in a security sense) the data you
385 receive, as its source can not easily be controleld (e-mail content, 509 receive, as its source can not easily be controlled (e-mail content,
386 messages from other users on the same system etc.). 510 messages from other users on the same system etc.).
387 511
388 on_add_lines $term, $string 512 on_add_lines $term, $string
389 Called whenever text is about to be output, with the text as 513 Called whenever text is about to be output, with the text as
390 argument. You can filter/change and output the text yourself by 514 argument. You can filter/change and output the text yourself by
… …
417 display code is run after this hook, and takes precedence. 541 display code is run after this hook, and takes precedence.
418 542
419 on_refresh_end $term 543 on_refresh_end $term
420 Called just after the screen gets redrawn. See "on_refresh_begin". 544 Called just after the screen gets redrawn. See "on_refresh_begin".
421 545
422 on_keyboard_command $term, $string 546 on_user_command $term, $string
423 Called whenever the user presses a key combination that has a 547 Called whenever a user-configured event is being activated (e.g. via
424 "perl:string" action bound to it (see description of the keysym 548 a "perl:string" action bound to a key, see description of the keysym
425 resource in the rxvt(1) manpage). 549 resource in the rxvt(1) manpage).
550
551 The event is simply the action string. This interface is assumed to
552 change slightly in the future.
553
554 on_resize_all_windows $tern, $new_width, $new_height
555 Called just after the new window size has been calculated, but
556 before windows are actually being resized or hints are being set. If
557 this hook returns TRUE, setting of the window hints is being
558 skipped.
426 559
427 on_x_event $term, $event 560 on_x_event $term, $event
428 Called on every X event received on the vt window (and possibly 561 Called on every X event received on the vt window (and possibly
429 other windows). Should only be used as a last resort. Most event 562 other windows). Should only be used as a last resort. Most event
430 structure members are not passed. 563 structure members are not passed.
431 564
565 on_root_event $term, $event
566 Like "on_x_event", but is called for events on the root window.
567
432 on_focus_in $term 568 on_focus_in $term
433 Called whenever the window gets the keyboard focus, before 569 Called whenever the window gets the keyboard focus, before
434 rxvt-unicode does focus in processing. 570 rxvt-unicode does focus in processing.
435 571
436 on_focus_out $term 572 on_focus_out $term
437 Called wheneever the window loses keyboard focus, before 573 Called whenever the window loses keyboard focus, before rxvt-unicode
438 rxvt-unicode does focus out processing. 574 does focus out processing.
439 575
440 on_configure_notify $term, $event 576 on_configure_notify $term, $event
441 on_property_notify $term, $event 577 on_property_notify $term, $event
442 on_key_press $term, $event, $keysym, $octets 578 on_key_press $term, $event, $keysym, $octets
443 on_key_release $term, $event, $keysym 579 on_key_release $term, $event, $keysym
… …
481 $urxvt::TERM 617 $urxvt::TERM
482 The current terminal. This variable stores the current "urxvt::term" 618 The current terminal. This variable stores the current "urxvt::term"
483 object, whenever a callback/hook is executing. 619 object, whenever a callback/hook is executing.
484 620
485 @urxvt::TERM_INIT 621 @urxvt::TERM_INIT
486 All coderefs in this array will be called as methods of the next 622 All code references in this array will be called as methods of the
487 newly created "urxvt::term" object (during the "on_init" phase). The 623 next newly created "urxvt::term" object (during the "on_init"
488 array gets cleared before the codereferences that were in it are 624 phase). The array gets cleared before the code references that were
489 being executed, so coderefs can push themselves onto it again if 625 in it are being executed, so references can push themselves onto it
490 they so desire. 626 again if they so desire.
491 627
492 This complements to the perl-eval commandline option, but gets 628 This complements to the perl-eval command line option, but gets
493 executed first. 629 executed first.
494 630
495 @urxvt::TERM_EXT 631 @urxvt::TERM_EXT
496 Works similar to @TERM_INIT, but contains perl package/class names, 632 Works similar to @TERM_INIT, but contains perl package/class names,
497 which get registered as normal extensions after calling the hooks in 633 which get registered as normal extensions after calling the hooks in
… …
511 647
512 Using this function has the advantage that its output ends up in the 648 Using this function has the advantage that its output ends up in the
513 correct place, e.g. on stderr of the connecting urxvtc client. 649 correct place, e.g. on stderr of the connecting urxvtc client.
514 650
515 Messages have a size limit of 1023 bytes currently. 651 Messages have a size limit of 1023 bytes currently.
652
653 @terms = urxvt::termlist
654 Returns all urxvt::term objects that exist in this process,
655 regardless of whether they are started, being destroyed etc., so be
656 careful. Only term objects that have perl extensions attached will
657 be returned (because there is no urxvt::term objet associated with
658 others).
516 659
517 $time = urxvt::NOW 660 $time = urxvt::NOW
518 Returns the "current time" (as per the event loop). 661 Returns the "current time" (as per the event loop).
519 662
520 urxvt::CurrentTime 663 urxvt::CurrentTime
… …
564 $background = urxvt::GET_BASEBG $rend 707 $background = urxvt::GET_BASEBG $rend
565 Return the foreground/background colour index, respectively. 708 Return the foreground/background colour index, respectively.
566 709
567 $rend = urxvt::SET_FGCOLOR $rend, $new_colour 710 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
568 $rend = urxvt::SET_BGCOLOR $rend, $new_colour 711 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
712 $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
569 Replace the foreground/background colour in the rendition mask with 713 Replace the foreground/background colour in the rendition mask with
570 the specified one. 714 the specified one.
571 715
572 $value = urxvt::GET_CUSTOM $rend 716 $value = urxvt::GET_CUSTOM $rend
573 Return the "custom" value: Every rendition has 5 bits for use by 717 Return the "custom" value: Every rendition has 5 bits for use by
… …
592 %ENV-like hash which defines the environment of the new terminal. 736 %ENV-like hash which defines the environment of the new terminal.
593 737
594 Croaks (and probably outputs an error message) if the new instance 738 Croaks (and probably outputs an error message) if the new instance
595 couldn't be created. Returns "undef" if the new instance didn't 739 couldn't be created. Returns "undef" if the new instance didn't
596 initialise perl, and the terminal object otherwise. The "init" and 740 initialise perl, and the terminal object otherwise. The "init" and
597 "start" hooks will be called during this call. 741 "start" hooks will be called before this call returns, and are free
742 to refer to global data (which is race free).
598 743
599 $term->destroy 744 $term->destroy
600 Destroy the terminal object (close the window, free resources etc.). 745 Destroy the terminal object (close the window, free resources etc.).
601 Please note that rxvt will not exit as long as any event watchers 746 Please note that rxvt will not exit as long as any event watchers
602 (timers, io watchers) are still active. 747 (timers, io watchers) are still active.
… …
614 Returns true if the option specified by $optval is enabled, and 759 Returns true if the option specified by $optval is enabled, and
615 optionally change it. All option values are stored by name in the 760 optionally change it. All option values are stored by name in the
616 hash %urxvt::OPTION. Options not enabled in this binary are not in 761 hash %urxvt::OPTION. Options not enabled in this binary are not in
617 the hash. 762 the hash.
618 763
619 Here is a a likely non-exhaustive list of option names, please see 764 Here is a likely non-exhaustive list of option names, please see the
620 the source file /src/optinc.h to see the actual list: 765 source file /src/optinc.h to see the actual list:
621 766
622 borderLess console cursorBlink cursorUnderline hold iconic insecure 767 borderLess console cursorBlink cursorUnderline hold iconic insecure
623 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 768 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
624 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 769 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
625 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput 770 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
… …
641 786
642 Please note that resource strings will currently only be freed when 787 Please note that resource strings will currently only be freed when
643 the terminal is destroyed, so changing options frequently will eat 788 the terminal is destroyed, so changing options frequently will eat
644 memory. 789 memory.
645 790
646 Here is a a likely non-exhaustive list of resource names, not all of 791 Here is a likely non-exhaustive list of resource names, not all of
647 which are supported in every build, please see the source file 792 which are supported in every build, please see the source file
648 /src/rsinc.h to see the actual list: 793 /src/rsinc.h to see the actual list:
649 794
650 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 795 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
651 borderLess color cursorBlink cursorUnderline cutchars delete_key 796 borderLess color cursorBlink cursorUnderline cutchars delete_key
… …
814 Adds the specified events to the vt event mask. Useful e.g. when you 959 Adds the specified events to the vt event mask. Useful e.g. when you
815 want to receive pointer events all the times: 960 want to receive pointer events all the times:
816 961
817 $term->vt_emask_add (urxvt::PointerMotionMask); 962 $term->vt_emask_add (urxvt::PointerMotionMask);
818 963
964 $term->focus_in
965 $term->focus_out
966 $term->key_press ($state, $keycode[, $time])
967 $term->key_release ($state, $keycode[, $time])
968 Deliver various fake events to to terminal.
969
819 $window_width = $term->width 970 $window_width = $term->width
820 $window_height = $term->height 971 $window_height = $term->height
821 $font_width = $term->fwidth 972 $font_width = $term->fwidth
822 $font_height = $term->fheight 973 $font_height = $term->fheight
823 $font_ascent = $term->fbase 974 $font_ascent = $term->fbase
… …
838 989
839 $env = $term->env 990 $env = $term->env
840 Returns a copy of the environment in effect for the terminal as a 991 Returns a copy of the environment in effect for the terminal as a
841 hashref similar to "\%ENV". 992 hashref similar to "\%ENV".
842 993
994 @envv = $term->envv
995 Returns the environment as array of strings of the form "VAR=VALUE".
996
997 @argv = $term->argv
998 Return the argument vector as this terminal, similar to @ARGV, but
999 includes the program name as first element.
1000
843 $modifiermask = $term->ModLevel3Mask 1001 $modifiermask = $term->ModLevel3Mask
844 $modifiermask = $term->ModMetaMask 1002 $modifiermask = $term->ModMetaMask
845 $modifiermask = $term->ModNumLockMask 1003 $modifiermask = $term->ModNumLockMask
846 Return the modifier masks corresponding to the "ISO Level 3 Shift" 1004 Return the modifier masks corresponding to the "ISO Level 3 Shift"
847 (often AltGr), the meta key (often Alt) and the num lock key, if 1005 (often AltGr), the meta key (often Alt) and the num lock key, if
… …
849 1007
850 $screen = $term->current_screen 1008 $screen = $term->current_screen
851 Returns the currently displayed screen (0 primary, 1 secondary). 1009 Returns the currently displayed screen (0 primary, 1 secondary).
852 1010
853 $cursor_is_hidden = $term->hidden_cursor 1011 $cursor_is_hidden = $term->hidden_cursor
854 Returns wether the cursor is currently hidden or not. 1012 Returns whether the cursor is currently hidden or not.
855 1013
856 $view_start = $term->view_start ([$newvalue]) 1014 $view_start = $term->view_start ([$newvalue])
857 Returns the row number of the topmost displayed line. Maximum value 1015 Returns the row number of the topmost displayed line. Maximum value
858 is 0, which displays the normal terminal contents. Lower values 1016 is 0, which displays the normal terminal contents. Lower values
859 scroll this many lines into the scrollback buffer. 1017 scroll this many lines into the scrollback buffer.
… …
943 Converts a perl string into the special encoding used by 1101 Converts a perl string into the special encoding used by
944 rxvt-unicode, where one character corresponds to one screen cell. 1102 rxvt-unicode, where one character corresponds to one screen cell.
945 See "$term->ROW_t" for details. 1103 See "$term->ROW_t" for details.
946 1104
947 $string = $term->special_decode $text 1105 $string = $term->special_decode $text
948 Converts rxvt-unicodes text reprsentation into a perl string. See 1106 Converts rxvt-unicodes text representation into a perl string. See
949 "$term->ROW_t" for details. 1107 "$term->ROW_t" for details.
950 1108
951 $success = $term->grab_button ($button, $modifiermask) 1109 $success = $term->grab_button ($button, $modifiermask[, $window =
1110 $term->vt])
1111 $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
952 Registers a synchronous button grab. See the XGrabButton manpage. 1112 Register/unregister a synchronous button grab. See the XGrabButton
1113 manpage.
953 1114
954 $success = $term->grab ($eventtime[, $sync]) 1115 $success = $term->grab ($eventtime[, $sync])
955 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1116 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
956 synchronous ($sync is true). Also remembers the grab timestampe. 1117 synchronous ($sync is true). Also remembers the grab timestamp.
957 1118
958 $term->allow_events_async 1119 $term->allow_events_async
959 Calls XAllowEvents with AsyncBoth for the most recent grab. 1120 Calls XAllowEvents with AsyncBoth for the most recent grab.
960 1121
961 $term->allow_events_sync 1122 $term->allow_events_sync
… …
999 1160
1000 $popup->add_button ($text, $cb) 1161 $popup->add_button ($text, $cb)
1001 Adds a clickable button to the popup. $cb is called whenever it is 1162 Adds a clickable button to the popup. $cb is called whenever it is
1002 selected. 1163 selected.
1003 1164
1004 $popup->add_toggle ($text, $cb, $initial_value) 1165 $popup->add_toggle ($text, $initial_value, $cb)
1005 Adds a toggle/checkbox item to the popup. Teh callback gets called 1166 Adds a toggle/checkbox item to the popup. The callback gets called
1006 whenever it gets toggled, with a boolean indicating its value as its 1167 whenever it gets toggled, with a boolean indicating its new value as
1007 first argument. 1168 its first argument.
1008 1169
1009 $popup->show 1170 $popup->show
1010 Displays the popup (which is initially hidden). 1171 Displays the popup (which is initially hidden).
1011 1172
1012 The "urxvt::timer" Class 1173 The "urxvt::timer" Class
… …
1074 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 1235 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1075 Set the callback to be called when io events are triggered. 1236 Set the callback to be called when io events are triggered.
1076 $reventmask is a bitset as described in the "events" method. 1237 $reventmask is a bitset as described in the "events" method.
1077 1238
1078 $iow = $iow->fd ($fd) 1239 $iow = $iow->fd ($fd)
1079 Set the filedescriptor (not handle) to watch. 1240 Set the file descriptor (not handle) to watch.
1080 1241
1081 $iow = $iow->events ($eventmask) 1242 $iow = $iow->events ($eventmask)
1082 Set the event mask to watch. The only allowed values are 1243 Set the event mask to watch. The only allowed values are
1083 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed 1244 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
1084 together, or "urxvt::EVENT_NONE". 1245 together, or "urxvt::EVENT_NONE".
1085 1246
1086 $iow = $iow->start 1247 $iow = $iow->start
1087 Start watching for requested events on the given handle. 1248 Start watching for requested events on the given handle.
1088 1249
1089 $iow = $iow->stop 1250 $iow = $iow->stop
1090 Stop watching for events on the given filehandle. 1251 Stop watching for events on the given file handle.
1091 1252
1092 The "urxvt::iw" Class 1253 The "urxvt::iw" Class
1093 This class implements idle watchers, that get called automatically when 1254 This class implements idle watchers, that get called automatically when
1094 the process is idle. They should return as fast as possible, after doing 1255 the process is idle. They should return as fast as possible, after doing
1095 some useful work. 1256 some useful work.
… …
1125 1286
1126 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... }) 1287 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1127 Set the callback to be called when the timer triggers. 1288 Set the callback to be called when the timer triggers.
1128 1289
1129 $pw = $timer->start ($pid) 1290 $pw = $timer->start ($pid)
1130 Tells the wqtcher to start watching for process $pid. 1291 Tells the watcher to start watching for process $pid.
1131 1292
1132 $pw = $pw->stop 1293 $pw = $pw->stop
1133 Stop the watcher. 1294 Stop the watcher.
1134 1295
1135ENVIRONMENT 1296ENVIRONMENT
… …
1138 numbers indicate more verbose output. 1299 numbers indicate more verbose output.
1139 1300
1140 == 0 - fatal messages 1301 == 0 - fatal messages
1141 >= 3 - script loading and management 1302 >= 3 - script loading and management
1142 >=10 - all called hooks 1303 >=10 - all called hooks
1143 >=11 - hook reutrn values 1304 >=11 - hook return values
1144 1305
1145AUTHOR 1306AUTHOR
1146 Marc Lehmann <pcg@goof.com> 1307 Marc Lehmann <pcg@goof.com>
1147 http://software.schmorp.de/pkg/rxvt-unicode 1308 http://software.schmorp.de/pkg/rxvt-unicode
1148 1309

Diff Legend

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