ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.127 by root, Wed Jan 25 00:42:21 2006 UTC vs.
Revision 1.150 by root, Thu Dec 7 03:02:44 2006 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, extension scripts specified via 22Every time a terminal object gets created, extension scripts specified via
23the C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
62 URxvt.selection.pattern-1: perl-regex 62 URxvt.selection.pattern-1: perl-regex
63 ... 63 ...
64 64
65The index number (0, 1...) must not have any holes, and each regex must 65The index number (0, 1...) must not have any holes, and each regex must
66contain at least one pair of capturing parentheses, which will be used for 66contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything 67the match. For example, the following adds a regex that matches everything
68between two vertical bars: 68between two vertical bars:
69 69
70 URxvt.selection.pattern-0: \\|([^|]+)\\| 70 URxvt.selection.pattern-0: \\|([^|]+)\\|
71 71
72Another example: Programs I use often output "absolute path: " at the 72Another example: Programs I use often output "absolute path: " at the
94=item option-popup (enabled by default) 94=item option-popup (enabled by default)
95 95
96Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at 96Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
97runtime. 97runtime.
98 98
99Other extensions can extend this popup menu by pushing a code reference
100onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
101popup is being displayed.
102
103It's sole argument is the popup menu, which can be modified. It should
104either return nothing or a string, the initial boolean value and a code
105reference. The string will be used as button text and the code reference
106will be called when the toggle changes, with the new boolean value as
107first argument.
108
109The following will add an entry C<myoption> that changes
110C<$self->{myoption}>:
111
112 push @{ $self->{term}{option_popup_hook} }, sub {
113 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
114 };
115
99=item selection-popup (enabled by default) 116=item selection-popup (enabled by default)
100 117
101Binds a popup menu to Ctrl-Button3 that lets you convert the selection 118Binds a popup menu to Ctrl-Button3 that lets you convert the selection
102text into various other formats/action (such as uri unescaping, perl 119text into various other formats/action (such as uri unescaping, perl
103evaluation, web-browser starting etc.), depending on content. 120evaluation, web-browser starting etc.), depending on content.
104 121
105Other extensions can extend this popup menu by pushing a code reference 122Other extensions can extend this popup menu by pushing a code reference
106onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
107popup is displayed. 124popup is being displayed.
108 125
109It's sole argument is the popup menu, which can be modified. The selection 126It's sole argument is the popup menu, which can be modified. The selection
110is in C<$_>, which can be used to decide wether to add something or not. 127is in C<$_>, which can be used to decide whether to add something or not.
111It should either return nothing or a string and a code reference. The 128It should either return nothing or a string and a code reference. The
112string will be used as button text and the code reference will be called 129string will be used as button text and the code reference will be called
113when the button gets activated and should transform C<$_>. 130when the button gets activated and should transform C<$_>.
114 131
115The following will add an entry C<a to b> that transforms all C<a>s in 132The following will add an entry C<a to b> that transforms all C<a>s in
134bottom. C<Escape> leaves search mode and returns to the point where search 151bottom. C<Escape> leaves search mode and returns to the point where search
135was started, while C<Enter> or C<Return> stay at the current position and 152was started, while C<Enter> or C<Return> stay at the current position and
136additionally stores the first match in the current line into the primary 153additionally stores the first match in the current line into the primary
137selection. 154selection.
138 155
156The regex defaults to "(?i)", resulting in a case-insensitive search. To
157get a case-sensitive search you can delete this prefix using C<BackSpace>
158or simply use an uppercase character which removes the "(?i)" prefix.
159
160See L<perlre> for more info about perl regular expression syntax.
161
139=item readline (enabled by default) 162=item readline (enabled by default)
140 163
141A support package that tries to make editing with readline easier. At the 164A support package that tries to make editing with readline easier. At
142moment, it reacts to clicking with the left mouse button by trying to 165the moment, it reacts to clicking shift-left mouse button by trying to
143move the text cursor to this position. It does so by generating as many 166move the text cursor to this position. It does so by generating as many
144cursor-left or cursor-right keypresses as required (the this only works 167cursor-left or cursor-right keypresses as required (the this only works
145for programs that correctly support wide characters). 168for programs that correctly support wide characters).
146 169
147To avoid too many false positives, this is only done when: 170To avoid too many false positives, this is only done when:
197the message into vi commands to load the file. 220the message into vi commands to load the file.
198 221
199=item tabbed 222=item tabbed
200 223
201This transforms the terminal into a tabbar with additional terminals, that 224This transforms the terminal into a tabbar with additional terminals, that
202is, it implements what is commonly refered to as "tabbed terminal". The topmost line 225is, it implements what is commonly referred to as "tabbed terminal". The topmost line
203displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one 226displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
204button per tab. 227button per tab.
205 228
206Clicking a button will activate that tab. Pressing B<Shift-Left> and 229Clicking a button will activate that tab. Pressing B<Shift-Left> and
207B<Shift-Right> will switch to the tab left or right of the current one, 230B<Shift-Right> will switch to the tab left or right of the current one,
208while B<Shift-Down> creates a new tab. 231while B<Shift-Down> creates a new tab.
209 232
210=item mark-urls 233The tabbar itself can be configured similarly to a normal terminal, but
234with a resource class of C<URxvt.tabbed>. In addition, it supports the
235following four resources (shown with defaults):
211 236
237 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
238 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
239 URxvt.tabbed.tab-fg: <colour-index, default 0>
240 URxvt.tabbed.tab-bg: <colour-index, default 1>
241
242See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
243indices.
244
245=item matcher
246
212Uses per-line display filtering (C<on_line_update>) to underline urls and 247Uses per-line display filtering (C<on_line_update>) to underline text
213make them clickable. When middle-clicked, the program specified in the 248matching a certain pattern and make it clickable. When clicked with the
214resource C<urlLauncher> (default C<x-www-browser>) will be started with 249mouse button specified in the C<matcher.button> resource (default 2, or
215the URL as first argument. 250middle), the program specified in the C<matcher.launcher> resource
251(default, the C<urlLauncher> resource, C<sensible-browser>) will be started
252with the matched text as first argument. The default configuration is
253suitable for matching URLs and launching a web browser, like the
254former "mark-urls" extension.
255
256The default pattern to match URLs can be overridden with the
257C<matcher.pattern.0> resource, and additional patterns can be specified
258with numbered patterns, in a manner similar to the "selection" extension.
259The launcher can also be overridden on a per-pattern basis.
260
261Example configuration:
262
263 URxvt.perl-ext: default,matcher
264 URxvt.urlLauncher: sensible-browser
265 URxvt.matcher.button: 1
266 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
267 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
268 URxvt.matcher.launcher.2: gvim +$2 $1
269
270=item xim-onthespot
271
272This (experimental) perl extension implements OnTheSpot editing. It does
273not work perfectly, and some input methods don't seem to work well with
274OnTheSpot editing in general, but it seems to work at leats for SCIM and
275kinput2.
276
277You enable it by specifying this extension and a preedit style of
278C<OnTheSpot>, i.e.:
279
280 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
281
282=item kuake<hotkey>
283
284A very primitive quake-console-like extension. It was inspired by a
285description of how the programs C<kuake> and C<yakuake> work: Whenever the
286user presses a global accelerator key (by default C<F10>), the terminal
287will show or hide itself. Another press of the accelerator key will hide
288or show it again.
289
290Initially, the window will not be shown when using this extension.
291
292This is useful if you need a single terminal thats not using any desktop
293space most of the time but is quickly available at the press of a key.
294
295The accelerator key is grabbed regardless of any modifiers, so this
296extension will actually grab a physical key just for this function.
297
298If you want a quake-like animation, tell your window manager to do so
299(fvwm can do it).
216 300
217=item automove-background 301=item automove-background
218 302
219This is basically a one-line extension that dynamically changes the background pixmap offset 303This is basically a very small extension that dynamically changes the
220to the window position, in effect creating the same effect as pseudo transparency with 304background pixmap offset to the window position, in effect creating the
221a custom pixmap. No scaling is supported in this mode. Exmaple: 305same effect as pseudo transparency with a custom pixmap. No scaling is
306supported in this mode. Example:
222 307
223 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 308 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
224 309
225=item block-graphics-to-ascii 310=item block-graphics-to-ascii
226 311
227A not very useful example of filtering all text output to the terminal, 312A not very useful example of filtering all text output to the terminal
228by replacing all line-drawing characters (U+2500 .. U+259F) by a 313by replacing all line-drawing characters (U+2500 .. U+259F) by a
229similar-looking ascii character. 314similar-looking ascii character.
230 315
231=item digital-clock 316=item digital-clock
232 317
233Displays a digital clock using the built-in overlay. 318Displays a digital clock using the built-in overlay.
234 319
235=item example-refresh-hooks 320=item remote-clipboard
236 321
237Displays a very simple digital clock in the upper right corner of the 322Somewhat of a misnomer, this extension adds two menu entries to the
238window. Illustrates overwriting the refresh callbacks to create your own 323selection popup that allows one ti run external commands to store the
239overlays or changes. 324selection somewhere and fetch it again.
325
326We use it to implement a "distributed selection mechanism", which just
327means that one command uploads the file to a remote server, and another
328reads it.
329
330The commands can be set using the C<URxvt.remote-selection.store> and
331C<URxvt.remote-selection.fetch> resources. The first should read the
332selection to store from STDIN (always in UTF-8), the second should provide
333the selection data on STDOUT (also in UTF-8).
334
335The defaults (which are likely useless to you) use rsh and cat:
336
337 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
338 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
240 339
241=item selection-pastebin 340=item selection-pastebin
242 341
243This is a little rarely useful extension that Uploads the selection as 342This is a little rarely useful extension that Uploads the selection as
244textfile to a remote site (or does other things). (The implementation is 343textfile to a remote site (or does other things). (The implementation is
264After a successful upload the selection will be replaced by the text given 363After a successful upload the selection will be replaced by the text given
265in the C<selection-pastebin-url> resource (again, the % is the placeholder 364in the C<selection-pastebin-url> resource (again, the % is the placeholder
266for the filename): 365for the filename):
267 366
268 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 367 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
368
369I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
370the double C</> characters as comment start. Use C<\057\057> instead,
371which works regardless of wether xrdb is used to parse the resource file
372or not.
373
374=item example-refresh-hooks
375
376Displays a very simple digital clock in the upper right corner of the
377window. Illustrates overwriting the refresh callbacks to create your own
378overlays or changes.
269 379
270=back 380=back
271 381
272=head1 API DOCUMENTATION 382=head1 API DOCUMENTATION
273 383
307 417
308=back 418=back
309 419
310=head2 Extension Objects 420=head2 Extension Objects
311 421
312Very perl extension is a perl class. A separate perl object is created 422Every perl extension is a perl class. A separate perl object is created
313for each terminal and each extension and passed as the first parameter to 423for each terminal, and each terminal has its own set of extenion objects,
314hooks. So extensions can use their C<$self> object without having to think 424which are passed as the first parameter to hooks. So extensions can use
315about other extensions, with the exception of methods and members that 425their C<$self> object without having to think about clashes with other
426extensions or other terminals, with the exception of methods and members
316begin with an underscore character C<_>: these are reserved for internal 427that begin with an underscore character C<_>: these are reserved for
317use. 428internal use.
318 429
319Although it isn't a C<urxvt::term> object, you can call all methods of the 430Although it isn't a C<urxvt::term> object, you can call all methods of the
320C<urxvt::term> class on this object. 431C<urxvt::term> class on this object.
321 432
322It has the following methods and data members: 433It has the following methods and data members:
343=head2 Hooks 454=head2 Hooks
344 455
345The following subroutines can be declared in extension files, and will be 456The following subroutines can be declared in extension files, and will be
346called whenever the relevant event happens. 457called whenever the relevant event happens.
347 458
348The first argument passed to them is an extension oject as described in 459The first argument passed to them is an extension object as described in
349the in the C<Extension Objects> section. 460the in the C<Extension Objects> section.
350 461
351B<All> of these hooks must return a boolean value. If any of the called 462B<All> of these hooks must return a boolean value. If any of the called
352hooks returns true, then the event counts as being I<consumed>, and the 463hooks returns true, then the event counts as being I<consumed>, and the
353relevant action might not be carried out by the C++ code. 464relevant action might not be carried out by the C++ code.
366place. 477place.
367 478
368=item on_start $term 479=item on_start $term
369 480
370Called at the very end of initialisation of a new terminal, just before 481Called at the very end of initialisation of a new terminal, just before
371trying to map (display) the toplevel and returning to the mainloop. 482trying to map (display) the toplevel and returning to the main loop.
372 483
373=item on_destroy $term 484=item on_destroy $term
374 485
375Called whenever something tries to destroy terminal, when the terminal is 486Called whenever something tries to destroy terminal, when the terminal is
376still fully functional (not for long, though). 487still fully functional (not for long, though).
403 514
404Called whenever a selection has been copied, but before the selection is 515Called whenever a selection has been copied, but before the selection is
405requested from the server. The selection text can be queried and changed 516requested from the server. The selection text can be queried and changed
406by calling C<< $term->selection >>. 517by calling C<< $term->selection >>.
407 518
408Returning a true value aborts selection grabbing. It will still be hilighted. 519Returning a true value aborts selection grabbing. It will still be highlighted.
409 520
410=item on_sel_extend $term 521=item on_sel_extend $term
411 522
412Called whenever the user tries to extend the selection (e.g. with a double 523Called whenever the user tries to extend the selection (e.g. with a double
413click) and is either supposed to return false (normal operation), or 524click) and is either supposed to return false (normal operation), or
414should extend the selection itelf and return true to suppress the built-in 525should extend the selection itself and return true to suppress the built-in
415processing. This can happen multiple times, as long as the callback 526processing. This can happen multiple times, as long as the callback
416returns true, it will be called on every further click by the user and is 527returns true, it will be called on every further click by the user and is
417supposed to enlarge the selection more and more, if possible. 528supposed to enlarge the selection more and more, if possible.
418 529
419See the F<selection> example extension. 530See the F<selection> example extension.
420 531
421=item on_view_change $term, $offset 532=item on_view_change $term, $offset
422 533
423Called whenever the view offset changes, i..e the user or program 534Called whenever the view offset changes, i.e. the user or program
424scrolls. Offset C<0> means display the normal terminal, positive values 535scrolls. Offset C<0> means display the normal terminal, positive values
425show this many lines of scrollback. 536show this many lines of scrollback.
426 537
427=item on_scroll_back $term, $lines, $saved 538=item on_scroll_back $term, $lines, $saved
428 539
432 543
433It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 544It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
434$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 545$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
435number of lines that will be in the scrollback buffer. 546number of lines that will be in the scrollback buffer.
436 547
548=item on_osc_seq $term, $op, $args
549
550Called on every OSC sequence and can be used to suppress it or modify its
551behaviour. The default should be to return an empty list. A true value
552suppresses execution of the request completely. Make sure you don't get
553confused by recursive invocations when you output an osc sequence within
554this callback.
555
556C<on_osc_seq_perl> should be used for new behaviour.
557
437=item on_osc_seq $term, $string 558=item on_osc_seq_perl $term, $string
438 559
439Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 560Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
440operating system command) is processed. Cursor position and other state 561operating system command) is processed. Cursor position and other state
441information is up-to-date when this happens. For interoperability, the 562information is up-to-date when this happens. For interoperability, the
442string should start with the extension name and a colon, to distinguish 563string should start with the extension name and a colon, to distinguish
443it from commands for other extensions, and this might be enforced in the 564it from commands for other extensions, and this might be enforced in the
444future. 565future.
445 566
446Be careful not ever to trust (in a security sense) the data you receive, 567Be careful not ever to trust (in a security sense) the data you receive,
447as its source can not easily be controleld (e-mail content, messages from 568as its source can not easily be controlled (e-mail content, messages from
448other users on the same system etc.). 569other users on the same system etc.).
449 570
450=item on_add_lines $term, $string 571=item on_add_lines $term, $string
451 572
452Called whenever text is about to be output, with the text as argument. You 573Called whenever text is about to be output, with the text as argument. You
483 604
484=item on_refresh_end $term 605=item on_refresh_end $term
485 606
486Called just after the screen gets redrawn. See C<on_refresh_begin>. 607Called just after the screen gets redrawn. See C<on_refresh_begin>.
487 608
488=item on_keyboard_command $term, $string 609=item on_user_command $term, $string
489 610
490Called whenever the user presses a key combination that has a 611Called whenever a user-configured event is being activated (e.g. via
491C<perl:string> action bound to it (see description of the B<keysym> 612a C<perl:string> action bound to a key, see description of the B<keysym>
492resource in the @@RXVT_NAME@@(1) manpage). 613resource in the @@RXVT_NAME@@(1) manpage).
614
615The event is simply the action string. This interface is assumed to change
616slightly in the future.
617
618=item on_resize_all_windows $tern, $new_width, $new_height
619
620Called just after the new window size has been calculated, but before
621windows are actually being resized or hints are being set. If this hook
622returns TRUE, setting of the window hints is being skipped.
493 623
494=item on_x_event $term, $event 624=item on_x_event $term, $event
495 625
496Called on every X event received on the vt window (and possibly other 626Called on every X event received on the vt window (and possibly other
497windows). Should only be used as a last resort. Most event structure 627windows). Should only be used as a last resort. Most event structure
498members are not passed. 628members are not passed.
499 629
630=item on_root_event $term, $event
631
632Like C<on_x_event>, but is called for events on the root window.
633
500=item on_focus_in $term 634=item on_focus_in $term
501 635
502Called whenever the window gets the keyboard focus, before rxvt-unicode 636Called whenever the window gets the keyboard focus, before rxvt-unicode
503does focus in processing. 637does focus in processing.
504 638
505=item on_focus_out $term 639=item on_focus_out $term
506 640
507Called wheneever the window loses keyboard focus, before rxvt-unicode does 641Called whenever the window loses keyboard focus, before rxvt-unicode does
508focus out processing. 642focus out processing.
509 643
510=item on_configure_notify $term, $event 644=item on_configure_notify $term, $event
511 645
512=item on_property_notify $term, $event 646=item on_property_notify $term, $event
595The current terminal. This variable stores the current C<urxvt::term> 729The current terminal. This variable stores the current C<urxvt::term>
596object, whenever a callback/hook is executing. 730object, whenever a callback/hook is executing.
597 731
598=item @urxvt::TERM_INIT 732=item @urxvt::TERM_INIT
599 733
600All coderefs in this array will be called as methods of the next newly 734All code references in this array will be called as methods of the next newly
601created C<urxvt::term> object (during the C<on_init> phase). The array 735created C<urxvt::term> object (during the C<on_init> phase). The array
602gets cleared before the codereferences that were in it are being executed, 736gets cleared before the code references that were in it are being executed,
603so coderefs can push themselves onto it again if they so desire. 737so references can push themselves onto it again if they so desire.
604 738
605This complements to the perl-eval commandline option, but gets executed 739This complements to the perl-eval command line option, but gets executed
606first. 740first.
607 741
608=item @urxvt::TERM_EXT 742=item @urxvt::TERM_EXT
609 743
610Works similar to C<@TERM_INIT>, but contains perl package/class names, which 744Works similar to C<@TERM_INIT>, but contains perl package/class names, which
631 765
632Using this function has the advantage that its output ends up in the 766Using this function has the advantage that its output ends up in the
633correct place, e.g. on stderr of the connecting urxvtc client. 767correct place, e.g. on stderr of the connecting urxvtc client.
634 768
635Messages have a size limit of 1023 bytes currently. 769Messages have a size limit of 1023 bytes currently.
770
771=item @terms = urxvt::termlist
772
773Returns all urxvt::term objects that exist in this process, regardless of
774whether they are started, being destroyed etc., so be careful. Only term
775objects that have perl extensions attached will be returned (because there
776is no urxvt::term objet associated with others).
636 777
637=item $time = urxvt::NOW 778=item $time = urxvt::NOW
638 779
639Returns the "current time" (as per the event loop). 780Returns the "current time" (as per the event loop).
640 781
698Return the foreground/background colour index, respectively. 839Return the foreground/background colour index, respectively.
699 840
700=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 841=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
701 842
702=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 843=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
844
845=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
703 846
704Replace the foreground/background colour in the rendition mask with the 847Replace the foreground/background colour in the rendition mask with the
705specified one. 848specified one.
706 849
707=item $value = urxvt::GET_CUSTOM $rend 850=item $value = urxvt::GET_CUSTOM $rend
798 } else { 941 } else {
799 $ext_arg{$_} ||= []; 942 $ext_arg{$_} ||= [];
800 } 943 }
801 } 944 }
802 945
803 while (my ($ext, $argv) = each %ext_arg) { 946 for my $ext (sort keys %ext_arg) {
804 my @files = grep -f $_, map "$_/$ext", @dirs; 947 my @files = grep -f $_, map "$_/$ext", @dirs;
805 948
806 if (@files) { 949 if (@files) {
807 $TERM->register_package (extension_package $files[0], $argv); 950 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
808 } else { 951 } else {
809 warn "perl extension '$ext' not found in perl library search path\n"; 952 warn "perl extension '$ext' not found in perl library search path\n";
810 } 953 }
811 } 954 }
812 955
818 961
819 if (my $cb = $TERM->{_hook}[$htype]) { 962 if (my $cb = $TERM->{_hook}[$htype]) {
820 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 963 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
821 if $verbosity >= 10; 964 if $verbosity >= 10;
822 965
823 keys %$cb; 966 for my $pkg (keys %$cb) {
824
825 while (my ($pkg, $cb) = each %$cb) {
826 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 967 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
827 $retval ||= $retval_; 968 $retval ||= $retval_;
828 969
829 if ($@) { 970 if ($@) {
830 $TERM->ungrab; # better to lose the grab than the session 971 $TERM->ungrab; # better to lose the grab than the session
831 warn $@; 972 warn $@;
843 # clear package 984 # clear package
844 %$TERM = (); 985 %$TERM = ();
845 } 986 }
846 987
847 $retval 988 $retval
989}
990
991sub SET_COLOR($$$) {
992 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
848} 993}
849 994
850# urxvt::term::extension 995# urxvt::term::extension
851 996
852package urxvt::term::extension; 997package urxvt::term::extension;
965sub DESTROY { 1110sub DESTROY {
966 $_[0][1]->stop; 1111 $_[0][1]->stop;
967} 1112}
968 1113
969sub condvar { 1114sub condvar {
970 bless \my $flag, urxvt::anyevent::condvar:: 1115 bless \my $flag, urxvt::anyevent::
971} 1116}
972 1117
973sub urxvt::anyevent::condvar::broadcast { 1118sub broadcast {
974 ${$_[0]}++; 1119 ${$_[0]}++;
975} 1120}
976 1121
977sub urxvt::anyevent::condvar::wait { 1122sub wait {
978 unless (${$_[0]}) { 1123 unless (${$_[0]}) {
979 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1124 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
980 } 1125 }
1126}
1127
1128sub one_event {
1129 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
981} 1130}
982 1131
983package urxvt::term; 1132package urxvt::term;
984 1133
985=head2 The C<urxvt::term> Class 1134=head2 The C<urxvt::term> Class
1021hash which defines the environment of the new terminal. 1170hash which defines the environment of the new terminal.
1022 1171
1023Croaks (and probably outputs an error message) if the new instance 1172Croaks (and probably outputs an error message) if the new instance
1024couldn't be created. Returns C<undef> if the new instance didn't 1173couldn't be created. Returns C<undef> if the new instance didn't
1025initialise perl, and the terminal object otherwise. The C<init> and 1174initialise perl, and the terminal object otherwise. The C<init> and
1026C<start> hooks will be called during this call. 1175C<start> hooks will be called before this call returns, and are free to
1176refer to global data (which is race free).
1027 1177
1028=cut 1178=cut
1029 1179
1030sub new { 1180sub new {
1031 my ($class, $env, @args) = @_; 1181 my ($class, $env, @args) = @_;
1032 1182
1183 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1184 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1185
1033 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1186 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1034} 1187}
1035 1188
1036=item $term->destroy 1189=item $term->destroy
1037 1190
1038Destroy the terminal object (close the window, free resources 1191Destroy the terminal object (close the window, free resources
1068 1221
1069Returns true if the option specified by C<$optval> is enabled, and 1222Returns true if the option specified by C<$optval> is enabled, and
1070optionally change it. All option values are stored by name in the hash 1223optionally change it. All option values are stored by name in the hash
1071C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1224C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1072 1225
1073Here is a a likely non-exhaustive list of option names, please see the 1226Here is a likely non-exhaustive list of option names, please see the
1074source file F</src/optinc.h> to see the actual list: 1227source file F</src/optinc.h> to see the actual list:
1075 1228
1076 borderLess console cursorBlink cursorUnderline hold iconic insecure 1229 borderLess console cursorBlink cursorUnderline hold iconic insecure
1077 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1230 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1078 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1231 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1095likely change). 1248likely change).
1096 1249
1097Please note that resource strings will currently only be freed when the 1250Please note that resource strings will currently only be freed when the
1098terminal is destroyed, so changing options frequently will eat memory. 1251terminal is destroyed, so changing options frequently will eat memory.
1099 1252
1100Here is a a likely non-exhaustive list of resource names, not all of which 1253Here is a likely non-exhaustive list of resource names, not all of which
1101are supported in every build, please see the source file F</src/rsinc.h> 1254are supported in every build, please see the source file F</src/rsinc.h>
1102to see the actual list: 1255to see the actual list:
1103 1256
1104 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1257 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1105 borderLess color cursorBlink cursorUnderline cutchars delete_key 1258 borderLess color cursorBlink cursorUnderline cutchars delete_key
1338Adds the specified events to the vt event mask. Useful e.g. when you want 1491Adds the specified events to the vt event mask. Useful e.g. when you want
1339to receive pointer events all the times: 1492to receive pointer events all the times:
1340 1493
1341 $term->vt_emask_add (urxvt::PointerMotionMask); 1494 $term->vt_emask_add (urxvt::PointerMotionMask);
1342 1495
1496=item $term->focus_in
1497
1498=item $term->focus_out
1499
1500=item $term->key_press ($state, $keycode[, $time])
1501
1502=item $term->key_release ($state, $keycode[, $time])
1503
1504Deliver various fake events to to terminal.
1505
1343=item $window_width = $term->width 1506=item $window_width = $term->width
1344 1507
1345=item $window_height = $term->height 1508=item $window_height = $term->height
1346 1509
1347=item $font_width = $term->fwidth 1510=item $font_width = $term->fwidth
1377=item $env = $term->env 1540=item $env = $term->env
1378 1541
1379Returns a copy of the environment in effect for the terminal as a hashref 1542Returns a copy of the environment in effect for the terminal as a hashref
1380similar to C<\%ENV>. 1543similar to C<\%ENV>.
1381 1544
1545=item @envv = $term->envv
1546
1547Returns the environment as array of strings of the form C<VAR=VALUE>.
1548
1549=item @argv = $term->argv
1550
1551Return the argument vector as this terminal, similar to @ARGV, but
1552includes the program name as first element.
1553
1382=cut 1554=cut
1383 1555
1384sub env { 1556sub env {
1385 if (my $env = $_[0]->_env) {
1386 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1557 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1387 } else {
1388 +{ %ENV }
1389 }
1390} 1558}
1391 1559
1392=item $modifiermask = $term->ModLevel3Mask 1560=item $modifiermask = $term->ModLevel3Mask
1393 1561
1394=item $modifiermask = $term->ModMetaMask 1562=item $modifiermask = $term->ModMetaMask
1402 1570
1403Returns the currently displayed screen (0 primary, 1 secondary). 1571Returns the currently displayed screen (0 primary, 1 secondary).
1404 1572
1405=item $cursor_is_hidden = $term->hidden_cursor 1573=item $cursor_is_hidden = $term->hidden_cursor
1406 1574
1407Returns wether the cursor is currently hidden or not. 1575Returns whether the cursor is currently hidden or not.
1408 1576
1409=item $view_start = $term->view_start ([$newvalue]) 1577=item $view_start = $term->view_start ([$newvalue])
1410 1578
1411Returns the row number of the topmost displayed line. Maximum value is 1579Returns the row number of the topmost displayed line. Maximum value is
1412C<0>, which displays the normal terminal contents. Lower values scroll 1580C<0>, which displays the normal terminal contents. Lower values scroll
1589where one character corresponds to one screen cell. See 1757where one character corresponds to one screen cell. See
1590C<< $term->ROW_t >> for details. 1758C<< $term->ROW_t >> for details.
1591 1759
1592=item $string = $term->special_decode $text 1760=item $string = $term->special_decode $text
1593 1761
1594Converts rxvt-unicodes text reprsentation into a perl string. See 1762Converts rxvt-unicodes text representation into a perl string. See
1595C<< $term->ROW_t >> for details. 1763C<< $term->ROW_t >> for details.
1596 1764
1597=item $success = $term->grab_button ($button, $modifiermask) 1765=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1598 1766
1767=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1768
1599Registers a synchronous button grab. See the XGrabButton manpage. 1769Register/unregister a synchronous button grab. See the XGrabButton
1770manpage.
1600 1771
1601=item $success = $term->grab ($eventtime[, $sync]) 1772=item $success = $term->grab ($eventtime[, $sync])
1602 1773
1603Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1774Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1604synchronous (C<$sync> is true). Also remembers the grab timestampe. 1775synchronous (C<$sync> is true). Also remembers the grab timestamp.
1605 1776
1606=item $term->allow_events_async 1777=item $term->allow_events_async
1607 1778
1608Calls XAllowEvents with AsyncBoth for the most recent grab. 1779Calls XAllowEvents with AsyncBoth for the most recent grab.
1609 1780
1722 my ($self, $text, $cb) = @_; 1893 my ($self, $text, $cb) = @_;
1723 1894
1724 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1895 $self->add_item ({ type => "button", text => $text, activate => $cb});
1725} 1896}
1726 1897
1727=item $popup->add_toggle ($text, $cb, $initial_value) 1898=item $popup->add_toggle ($text, $initial_value, $cb)
1728 1899
1729Adds a toggle/checkbox item to the popup. Teh callback gets called 1900Adds a toggle/checkbox item to the popup. The callback gets called
1730whenever it gets toggled, with a boolean indicating its value as its first 1901whenever it gets toggled, with a boolean indicating its new value as its
1731argument. 1902first argument.
1732 1903
1733=cut 1904=cut
1734 1905
1735sub add_toggle { 1906sub add_toggle {
1736 my ($self, $text, $cb, $value) = @_; 1907 my ($self, $text, $value, $cb) = @_;
1737 1908
1738 my $item; $item = { 1909 my $item; $item = {
1739 type => "button", 1910 type => "button",
1740 text => " $text", 1911 text => " $text",
1741 value => $value, 1912 value => $value,
1876Set the callback to be called when io events are triggered. C<$reventmask> 2047Set the callback to be called when io events are triggered. C<$reventmask>
1877is a bitset as described in the C<events> method. 2048is a bitset as described in the C<events> method.
1878 2049
1879=item $iow = $iow->fd ($fd) 2050=item $iow = $iow->fd ($fd)
1880 2051
1881Set the filedescriptor (not handle) to watch. 2052Set the file descriptor (not handle) to watch.
1882 2053
1883=item $iow = $iow->events ($eventmask) 2054=item $iow = $iow->events ($eventmask)
1884 2055
1885Set the event mask to watch. The only allowed values are 2056Set the event mask to watch. The only allowed values are
1886C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2057C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1890 2061
1891Start watching for requested events on the given handle. 2062Start watching for requested events on the given handle.
1892 2063
1893=item $iow = $iow->stop 2064=item $iow = $iow->stop
1894 2065
1895Stop watching for events on the given filehandle. 2066Stop watching for events on the given file handle.
1896 2067
1897=back 2068=back
1898 2069
1899=head2 The C<urxvt::iw> Class 2070=head2 The C<urxvt::iw> Class
1900 2071
1947 2118
1948Set the callback to be called when the timer triggers. 2119Set the callback to be called when the timer triggers.
1949 2120
1950=item $pw = $timer->start ($pid) 2121=item $pw = $timer->start ($pid)
1951 2122
1952Tells the wqtcher to start watching for process C<$pid>. 2123Tells the watcher to start watching for process C<$pid>.
1953 2124
1954=item $pw = $pw->stop 2125=item $pw = $pw->stop
1955 2126
1956Stop the watcher. 2127Stop the watcher.
1957 2128
1970 2141
1971=item >= 3 - script loading and management 2142=item >= 3 - script loading and management
1972 2143
1973=item >=10 - all called hooks 2144=item >=10 - all called hooks
1974 2145
1975=item >=11 - hook reutrn values 2146=item >=11 - hook return values
1976 2147
1977=back 2148=back
1978 2149
1979=head1 AUTHOR 2150=head1 AUTHOR
1980 2151

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines