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.128 by root, Wed Jan 25 00:57:57 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
216 269
217=item xim-onthespot 270=item xim-onthespot
218 271
219This (experimental) perl extension implements OnTheSpot editing. It does 272This (experimental) perl extension implements OnTheSpot editing. It does
220not work perfectly, and some input methods don't seem to work well with 273not work perfectly, and some input methods don't seem to work well with
224You enable it by specifying this extension and a preedit style of 277You enable it by specifying this extension and a preedit style of
225C<OnTheSpot>, i.e.: 278C<OnTheSpot>, i.e.:
226 279
227 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot 280 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
228 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).
300
229=item automove-background 301=item automove-background
230 302
231This is basically a one-line extension that dynamically changes the background pixmap offset 303This is basically a very small extension that dynamically changes the
232to the window position, in effect creating the same effect as pseudo transparency with 304background pixmap offset to the window position, in effect creating the
233a 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:
234 307
235 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 308 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
236 309
237=item block-graphics-to-ascii 310=item block-graphics-to-ascii
238 311
239A 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
240by replacing all line-drawing characters (U+2500 .. U+259F) by a 313by replacing all line-drawing characters (U+2500 .. U+259F) by a
241similar-looking ascii character. 314similar-looking ascii character.
242 315
243=item digital-clock 316=item digital-clock
244 317
245Displays a digital clock using the built-in overlay. 318Displays a digital clock using the built-in overlay.
246 319
247=item example-refresh-hooks 320=item remote-clipboard
248 321
249Displays a very simple digital clock in the upper right corner of the 322Somewhat of a misnomer, this extension adds two menu entries to the
250window. Illustrates overwriting the refresh callbacks to create your own 323selection popup that allows one ti run external commands to store the
251overlays 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'
252 339
253=item selection-pastebin 340=item selection-pastebin
254 341
255This is a little rarely useful extension that Uploads the selection as 342This is a little rarely useful extension that Uploads the selection as
256textfile to a remote site (or does other things). (The implementation is 343textfile to a remote site (or does other things). (The implementation is
276After 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
277in the C<selection-pastebin-url> resource (again, the % is the placeholder 364in the C<selection-pastebin-url> resource (again, the % is the placeholder
278for the filename): 365for the filename):
279 366
280 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.
281 379
282=back 380=back
283 381
284=head1 API DOCUMENTATION 382=head1 API DOCUMENTATION
285 383
319 417
320=back 418=back
321 419
322=head2 Extension Objects 420=head2 Extension Objects
323 421
324Very 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
325for 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,
326hooks. 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
327about 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
328begin with an underscore character C<_>: these are reserved for internal 427that begin with an underscore character C<_>: these are reserved for
329use. 428internal use.
330 429
331Although 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
332C<urxvt::term> class on this object. 431C<urxvt::term> class on this object.
333 432
334It has the following methods and data members: 433It has the following methods and data members:
355=head2 Hooks 454=head2 Hooks
356 455
357The following subroutines can be declared in extension files, and will be 456The following subroutines can be declared in extension files, and will be
358called whenever the relevant event happens. 457called whenever the relevant event happens.
359 458
360The 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
361the in the C<Extension Objects> section. 460the in the C<Extension Objects> section.
362 461
363B<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
364hooks 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
365relevant action might not be carried out by the C++ code. 464relevant action might not be carried out by the C++ code.
378place. 477place.
379 478
380=item on_start $term 479=item on_start $term
381 480
382Called 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
383trying to map (display) the toplevel and returning to the mainloop. 482trying to map (display) the toplevel and returning to the main loop.
384 483
385=item on_destroy $term 484=item on_destroy $term
386 485
387Called whenever something tries to destroy terminal, when the terminal is 486Called whenever something tries to destroy terminal, when the terminal is
388still fully functional (not for long, though). 487still fully functional (not for long, though).
415 514
416Called whenever a selection has been copied, but before the selection is 515Called whenever a selection has been copied, but before the selection is
417requested from the server. The selection text can be queried and changed 516requested from the server. The selection text can be queried and changed
418by calling C<< $term->selection >>. 517by calling C<< $term->selection >>.
419 518
420Returning a true value aborts selection grabbing. It will still be hilighted. 519Returning a true value aborts selection grabbing. It will still be highlighted.
421 520
422=item on_sel_extend $term 521=item on_sel_extend $term
423 522
424Called 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
425click) and is either supposed to return false (normal operation), or 524click) and is either supposed to return false (normal operation), or
426should 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
427processing. This can happen multiple times, as long as the callback 526processing. This can happen multiple times, as long as the callback
428returns 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
429supposed to enlarge the selection more and more, if possible. 528supposed to enlarge the selection more and more, if possible.
430 529
431See the F<selection> example extension. 530See the F<selection> example extension.
432 531
433=item on_view_change $term, $offset 532=item on_view_change $term, $offset
434 533
435Called whenever the view offset changes, i..e the user or program 534Called whenever the view offset changes, i.e. the user or program
436scrolls. Offset C<0> means display the normal terminal, positive values 535scrolls. Offset C<0> means display the normal terminal, positive values
437show this many lines of scrollback. 536show this many lines of scrollback.
438 537
439=item on_scroll_back $term, $lines, $saved 538=item on_scroll_back $term, $lines, $saved
440 539
444 543
445It 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,
446$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
447number of lines that will be in the scrollback buffer. 546number of lines that will be in the scrollback buffer.
448 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
449=item on_osc_seq $term, $string 558=item on_osc_seq_perl $term, $string
450 559
451Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 560Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
452operating system command) is processed. Cursor position and other state 561operating system command) is processed. Cursor position and other state
453information is up-to-date when this happens. For interoperability, the 562information is up-to-date when this happens. For interoperability, the
454string should start with the extension name and a colon, to distinguish 563string should start with the extension name and a colon, to distinguish
455it 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
456future. 565future.
457 566
458Be 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,
459as 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
460other users on the same system etc.). 569other users on the same system etc.).
461 570
462=item on_add_lines $term, $string 571=item on_add_lines $term, $string
463 572
464Called 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
495 604
496=item on_refresh_end $term 605=item on_refresh_end $term
497 606
498Called just after the screen gets redrawn. See C<on_refresh_begin>. 607Called just after the screen gets redrawn. See C<on_refresh_begin>.
499 608
500=item on_keyboard_command $term, $string 609=item on_user_command $term, $string
501 610
502Called whenever the user presses a key combination that has a 611Called whenever a user-configured event is being activated (e.g. via
503C<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>
504resource 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.
505 623
506=item on_x_event $term, $event 624=item on_x_event $term, $event
507 625
508Called 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
509windows). Should only be used as a last resort. Most event structure 627windows). Should only be used as a last resort. Most event structure
510members are not passed. 628members are not passed.
511 629
630=item on_root_event $term, $event
631
632Like C<on_x_event>, but is called for events on the root window.
633
512=item on_focus_in $term 634=item on_focus_in $term
513 635
514Called whenever the window gets the keyboard focus, before rxvt-unicode 636Called whenever the window gets the keyboard focus, before rxvt-unicode
515does focus in processing. 637does focus in processing.
516 638
517=item on_focus_out $term 639=item on_focus_out $term
518 640
519Called wheneever the window loses keyboard focus, before rxvt-unicode does 641Called whenever the window loses keyboard focus, before rxvt-unicode does
520focus out processing. 642focus out processing.
521 643
522=item on_configure_notify $term, $event 644=item on_configure_notify $term, $event
523 645
524=item on_property_notify $term, $event 646=item on_property_notify $term, $event
607The current terminal. This variable stores the current C<urxvt::term> 729The current terminal. This variable stores the current C<urxvt::term>
608object, whenever a callback/hook is executing. 730object, whenever a callback/hook is executing.
609 731
610=item @urxvt::TERM_INIT 732=item @urxvt::TERM_INIT
611 733
612All 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
613created 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
614gets cleared before the codereferences that were in it are being executed, 736gets cleared before the code references that were in it are being executed,
615so coderefs can push themselves onto it again if they so desire. 737so references can push themselves onto it again if they so desire.
616 738
617This complements to the perl-eval commandline option, but gets executed 739This complements to the perl-eval command line option, but gets executed
618first. 740first.
619 741
620=item @urxvt::TERM_EXT 742=item @urxvt::TERM_EXT
621 743
622Works 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
643 765
644Using 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
645correct place, e.g. on stderr of the connecting urxvtc client. 767correct place, e.g. on stderr of the connecting urxvtc client.
646 768
647Messages 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).
648 777
649=item $time = urxvt::NOW 778=item $time = urxvt::NOW
650 779
651Returns the "current time" (as per the event loop). 780Returns the "current time" (as per the event loop).
652 781
710Return the foreground/background colour index, respectively. 839Return the foreground/background colour index, respectively.
711 840
712=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 841=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
713 842
714=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
715 846
716Replace the foreground/background colour in the rendition mask with the 847Replace the foreground/background colour in the rendition mask with the
717specified one. 848specified one.
718 849
719=item $value = urxvt::GET_CUSTOM $rend 850=item $value = urxvt::GET_CUSTOM $rend
810 } else { 941 } else {
811 $ext_arg{$_} ||= []; 942 $ext_arg{$_} ||= [];
812 } 943 }
813 } 944 }
814 945
815 while (my ($ext, $argv) = each %ext_arg) { 946 for my $ext (sort keys %ext_arg) {
816 my @files = grep -f $_, map "$_/$ext", @dirs; 947 my @files = grep -f $_, map "$_/$ext", @dirs;
817 948
818 if (@files) { 949 if (@files) {
819 $TERM->register_package (extension_package $files[0], $argv); 950 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
820 } else { 951 } else {
821 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";
822 } 953 }
823 } 954 }
824 955
830 961
831 if (my $cb = $TERM->{_hook}[$htype]) { 962 if (my $cb = $TERM->{_hook}[$htype]) {
832 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 963 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
833 if $verbosity >= 10; 964 if $verbosity >= 10;
834 965
835 keys %$cb; 966 for my $pkg (keys %$cb) {
836
837 while (my ($pkg, $cb) = each %$cb) {
838 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 967 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
839 $retval ||= $retval_; 968 $retval ||= $retval_;
840 969
841 if ($@) { 970 if ($@) {
842 $TERM->ungrab; # better to lose the grab than the session 971 $TERM->ungrab; # better to lose the grab than the session
843 warn $@; 972 warn $@;
855 # clear package 984 # clear package
856 %$TERM = (); 985 %$TERM = ();
857 } 986 }
858 987
859 $retval 988 $retval
989}
990
991sub SET_COLOR($$$) {
992 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
860} 993}
861 994
862# urxvt::term::extension 995# urxvt::term::extension
863 996
864package urxvt::term::extension; 997package urxvt::term::extension;
977sub DESTROY { 1110sub DESTROY {
978 $_[0][1]->stop; 1111 $_[0][1]->stop;
979} 1112}
980 1113
981sub condvar { 1114sub condvar {
982 bless \my $flag, urxvt::anyevent::condvar:: 1115 bless \my $flag, urxvt::anyevent::
983} 1116}
984 1117
985sub urxvt::anyevent::condvar::broadcast { 1118sub broadcast {
986 ${$_[0]}++; 1119 ${$_[0]}++;
987} 1120}
988 1121
989sub urxvt::anyevent::condvar::wait { 1122sub wait {
990 unless (${$_[0]}) { 1123 unless (${$_[0]}) {
991 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";
992 } 1125 }
1126}
1127
1128sub one_event {
1129 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
993} 1130}
994 1131
995package urxvt::term; 1132package urxvt::term;
996 1133
997=head2 The C<urxvt::term> Class 1134=head2 The C<urxvt::term> Class
1033hash which defines the environment of the new terminal. 1170hash which defines the environment of the new terminal.
1034 1171
1035Croaks (and probably outputs an error message) if the new instance 1172Croaks (and probably outputs an error message) if the new instance
1036couldn'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
1037initialise perl, and the terminal object otherwise. The C<init> and 1174initialise perl, and the terminal object otherwise. The C<init> and
1038C<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).
1039 1177
1040=cut 1178=cut
1041 1179
1042sub new { 1180sub new {
1043 my ($class, $env, @args) = @_; 1181 my ($class, $env, @args) = @_;
1044 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
1045 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1186 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1046} 1187}
1047 1188
1048=item $term->destroy 1189=item $term->destroy
1049 1190
1050Destroy the terminal object (close the window, free resources 1191Destroy the terminal object (close the window, free resources
1080 1221
1081Returns true if the option specified by C<$optval> is enabled, and 1222Returns true if the option specified by C<$optval> is enabled, and
1082optionally 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
1083C<%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.
1084 1225
1085Here 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
1086source file F</src/optinc.h> to see the actual list: 1227source file F</src/optinc.h> to see the actual list:
1087 1228
1088 borderLess console cursorBlink cursorUnderline hold iconic insecure 1229 borderLess console cursorBlink cursorUnderline hold iconic insecure
1089 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1230 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1090 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1231 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1107likely change). 1248likely change).
1108 1249
1109Please note that resource strings will currently only be freed when the 1250Please note that resource strings will currently only be freed when the
1110terminal is destroyed, so changing options frequently will eat memory. 1251terminal is destroyed, so changing options frequently will eat memory.
1111 1252
1112Here 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
1113are 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>
1114to see the actual list: 1255to see the actual list:
1115 1256
1116 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1257 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1117 borderLess color cursorBlink cursorUnderline cutchars delete_key 1258 borderLess color cursorBlink cursorUnderline cutchars delete_key
1350Adds 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
1351to receive pointer events all the times: 1492to receive pointer events all the times:
1352 1493
1353 $term->vt_emask_add (urxvt::PointerMotionMask); 1494 $term->vt_emask_add (urxvt::PointerMotionMask);
1354 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
1355=item $window_width = $term->width 1506=item $window_width = $term->width
1356 1507
1357=item $window_height = $term->height 1508=item $window_height = $term->height
1358 1509
1359=item $font_width = $term->fwidth 1510=item $font_width = $term->fwidth
1389=item $env = $term->env 1540=item $env = $term->env
1390 1541
1391Returns 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
1392similar to C<\%ENV>. 1543similar to C<\%ENV>.
1393 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
1394=cut 1554=cut
1395 1555
1396sub env { 1556sub env {
1397 if (my $env = $_[0]->_env) {
1398 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1557 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1399 } else {
1400 +{ %ENV }
1401 }
1402} 1558}
1403 1559
1404=item $modifiermask = $term->ModLevel3Mask 1560=item $modifiermask = $term->ModLevel3Mask
1405 1561
1406=item $modifiermask = $term->ModMetaMask 1562=item $modifiermask = $term->ModMetaMask
1414 1570
1415Returns the currently displayed screen (0 primary, 1 secondary). 1571Returns the currently displayed screen (0 primary, 1 secondary).
1416 1572
1417=item $cursor_is_hidden = $term->hidden_cursor 1573=item $cursor_is_hidden = $term->hidden_cursor
1418 1574
1419Returns wether the cursor is currently hidden or not. 1575Returns whether the cursor is currently hidden or not.
1420 1576
1421=item $view_start = $term->view_start ([$newvalue]) 1577=item $view_start = $term->view_start ([$newvalue])
1422 1578
1423Returns the row number of the topmost displayed line. Maximum value is 1579Returns the row number of the topmost displayed line. Maximum value is
1424C<0>, which displays the normal terminal contents. Lower values scroll 1580C<0>, which displays the normal terminal contents. Lower values scroll
1601where one character corresponds to one screen cell. See 1757where one character corresponds to one screen cell. See
1602C<< $term->ROW_t >> for details. 1758C<< $term->ROW_t >> for details.
1603 1759
1604=item $string = $term->special_decode $text 1760=item $string = $term->special_decode $text
1605 1761
1606Converts rxvt-unicodes text reprsentation into a perl string. See 1762Converts rxvt-unicodes text representation into a perl string. See
1607C<< $term->ROW_t >> for details. 1763C<< $term->ROW_t >> for details.
1608 1764
1609=item $success = $term->grab_button ($button, $modifiermask) 1765=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1610 1766
1767=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1768
1611Registers a synchronous button grab. See the XGrabButton manpage. 1769Register/unregister a synchronous button grab. See the XGrabButton
1770manpage.
1612 1771
1613=item $success = $term->grab ($eventtime[, $sync]) 1772=item $success = $term->grab ($eventtime[, $sync])
1614 1773
1615Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1774Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1616synchronous (C<$sync> is true). Also remembers the grab timestampe. 1775synchronous (C<$sync> is true). Also remembers the grab timestamp.
1617 1776
1618=item $term->allow_events_async 1777=item $term->allow_events_async
1619 1778
1620Calls XAllowEvents with AsyncBoth for the most recent grab. 1779Calls XAllowEvents with AsyncBoth for the most recent grab.
1621 1780
1734 my ($self, $text, $cb) = @_; 1893 my ($self, $text, $cb) = @_;
1735 1894
1736 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1895 $self->add_item ({ type => "button", text => $text, activate => $cb});
1737} 1896}
1738 1897
1739=item $popup->add_toggle ($text, $cb, $initial_value) 1898=item $popup->add_toggle ($text, $initial_value, $cb)
1740 1899
1741Adds a toggle/checkbox item to the popup. Teh callback gets called 1900Adds a toggle/checkbox item to the popup. The callback gets called
1742whenever 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
1743argument. 1902first argument.
1744 1903
1745=cut 1904=cut
1746 1905
1747sub add_toggle { 1906sub add_toggle {
1748 my ($self, $text, $cb, $value) = @_; 1907 my ($self, $text, $value, $cb) = @_;
1749 1908
1750 my $item; $item = { 1909 my $item; $item = {
1751 type => "button", 1910 type => "button",
1752 text => " $text", 1911 text => " $text",
1753 value => $value, 1912 value => $value,
1888Set 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>
1889is a bitset as described in the C<events> method. 2048is a bitset as described in the C<events> method.
1890 2049
1891=item $iow = $iow->fd ($fd) 2050=item $iow = $iow->fd ($fd)
1892 2051
1893Set the filedescriptor (not handle) to watch. 2052Set the file descriptor (not handle) to watch.
1894 2053
1895=item $iow = $iow->events ($eventmask) 2054=item $iow = $iow->events ($eventmask)
1896 2055
1897Set the event mask to watch. The only allowed values are 2056Set the event mask to watch. The only allowed values are
1898C<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
1902 2061
1903Start watching for requested events on the given handle. 2062Start watching for requested events on the given handle.
1904 2063
1905=item $iow = $iow->stop 2064=item $iow = $iow->stop
1906 2065
1907Stop watching for events on the given filehandle. 2066Stop watching for events on the given file handle.
1908 2067
1909=back 2068=back
1910 2069
1911=head2 The C<urxvt::iw> Class 2070=head2 The C<urxvt::iw> Class
1912 2071
1959 2118
1960Set the callback to be called when the timer triggers. 2119Set the callback to be called when the timer triggers.
1961 2120
1962=item $pw = $timer->start ($pid) 2121=item $pw = $timer->start ($pid)
1963 2122
1964Tells the wqtcher to start watching for process C<$pid>. 2123Tells the watcher to start watching for process C<$pid>.
1965 2124
1966=item $pw = $pw->stop 2125=item $pw = $pw->stop
1967 2126
1968Stop the watcher. 2127Stop the watcher.
1969 2128
1982 2141
1983=item >= 3 - script loading and management 2142=item >= 3 - script loading and management
1984 2143
1985=item >=10 - all called hooks 2144=item >=10 - all called hooks
1986 2145
1987=item >=11 - hook reutrn values 2146=item >=11 - hook return values
1988 2147
1989=back 2148=back
1990 2149
1991=head1 AUTHOR 2150=head1 AUTHOR
1992 2151

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines