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.122 by root, Sat Jan 21 08:07:38 2006 UTC vs.
Revision 1.154 by root, Sat Jun 2 06:43:02 2007 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
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30
31You can disable the embedded perl interpreter by setting both "perl-ext"
32and "perl-ext-common" resources to the empty string.
30 33
31=head1 PREPACKAGED EXTENSIONS 34=head1 PREPACKAGED EXTENSIONS
32 35
33This section describes the extensions delivered with this release. You can 36This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 37find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
62 URxvt.selection.pattern-1: perl-regex 65 URxvt.selection.pattern-1: perl-regex
63 ... 66 ...
64 67
65The index number (0, 1...) must not have any holes, and each regex must 68The 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 69contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything 70the match. For example, the following adds a regex that matches everything
68between two vertical bars: 71between two vertical bars:
69 72
70 URxvt.selection.pattern-0: \\|([^|]+)\\| 73 URxvt.selection.pattern-0: \\|([^|]+)\\|
74
75Another example: Programs I use often output "absolute path: " at the
76beginning of a line when they process multiple files. The following
77pattern matches the filename (note, there is a single space at the very
78end):
79
80 URxvt.selection.pattern-0: ^(/[^:]+):\
71 81
72You can look at the source of the selection extension to see more 82You can look at the source of the selection extension to see more
73interesting uses, such as parsing a line from beginning to end. 83interesting uses, such as parsing a line from beginning to end.
74 84
75This extension also offers following bindable keyboard commands: 85This extension also offers following bindable keyboard commands:
86 96
87=item option-popup (enabled by default) 97=item option-popup (enabled by default)
88 98
89Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at 99Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
90runtime. 100runtime.
101
102Other extensions can extend this popup menu by pushing a code reference
103onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
104popup is being displayed.
105
106It's sole argument is the popup menu, which can be modified. It should
107either return nothing or a string, the initial boolean value and a code
108reference. The string will be used as button text and the code reference
109will be called when the toggle changes, with the new boolean value as
110first argument.
111
112The following will add an entry C<myoption> that changes
113C<$self->{myoption}>:
114
115 push @{ $self->{term}{option_popup_hook} }, sub {
116 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
117 };
91 118
92=item selection-popup (enabled by default) 119=item selection-popup (enabled by default)
93 120
94Binds a popup menu to Ctrl-Button3 that lets you convert the selection 121Binds a popup menu to Ctrl-Button3 that lets you convert the selection
95text into various other formats/action (such as uri unescaping, perl 122text into various other formats/action (such as uri unescaping, perl
96evaluation, web-browser starting etc.), depending on content. 123evaluation, web-browser starting etc.), depending on content.
97 124
98Other extensions can extend this popup menu by pushing a code reference 125Other extensions can extend this popup menu by pushing a code reference
99onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
100popup is displayed. 127popup is being displayed.
101 128
102It's sole argument is the popup menu, which can be modified. The selection 129It's sole argument is the popup menu, which can be modified. The selection
103is in C<$_>, which can be used to decide wether to add something or not. 130is in C<$_>, which can be used to decide whether to add something or not.
104It should either return nothing or a string and a code reference. The 131It should either return nothing or a string and a code reference. The
105string will be used as button text and the code reference will be called 132string will be used as button text and the code reference will be called
106when the button gets activated and should transform C<$_>. 133when the button gets activated and should transform C<$_>.
107 134
108The following will add an entry C<a to b> that transforms all C<a>s in 135The following will add an entry C<a to b> that transforms all C<a>s in
127bottom. C<Escape> leaves search mode and returns to the point where search 154bottom. C<Escape> leaves search mode and returns to the point where search
128was started, while C<Enter> or C<Return> stay at the current position and 155was started, while C<Enter> or C<Return> stay at the current position and
129additionally stores the first match in the current line into the primary 156additionally stores the first match in the current line into the primary
130selection. 157selection.
131 158
159The regex defaults to "(?i)", resulting in a case-insensitive search. To
160get a case-sensitive search you can delete this prefix using C<BackSpace>
161or simply use an uppercase character which removes the "(?i)" prefix.
162
163See L<perlre> for more info about perl regular expression syntax.
164
165=item readline (enabled by default)
166
167A support package that tries to make editing with readline easier. At
168the moment, it reacts to clicking shift-left mouse button by trying to
169move the text cursor to this position. It does so by generating as many
170cursor-left or cursor-right keypresses as required (the this only works
171for programs that correctly support wide characters).
172
173To avoid too many false positives, this is only done when:
174
175=over 4
176
177=item - the tty is in ICANON state.
178
179=item - the text cursor is visible.
180
181=item - the primary screen is currently being displayed.
182
183=item - the mouse is on the same (multi-row-) line as the text cursor.
184
185=back
186
187The normal selection mechanism isn't disabled, so quick successive clicks
188might interfere with selection creation in harmless ways.
189
132=item selection-autotransform 190=item selection-autotransform
133 191
134This selection allows you to do automatic transforms on a selection 192This selection allows you to do automatic transforms on a selection
135whenever a selection is made. 193whenever a selection is made.
136 194
162 220
163The first line tells the selection code to treat the unchanging part of 221The first line tells the selection code to treat the unchanging part of
164every error message as a selection pattern, and the second line transforms 222every error message as a selection pattern, and the second line transforms
165the message into vi commands to load the file. 223the message into vi commands to load the file.
166 224
167=item readline
168
169A support package that tries to make editing with readline easier. At the
170moment, it reacts to clicking with the left mouse button by trying to
171move the text cursor to this position. It does so by generating as many
172cursor-left or cursor-right keypresses as required (the this only works
173for programs that correctly support wide characters).
174
175To avoid too many false positives, this is only done when:
176
177=over 4
178
179=item - the mouse is on the same (multi-row-) line as the text cursor.
180
181=item - the primary screen is currently being displayed.
182
183=item - the text cursor is visible.
184
185=back
186
187The normal selection mechanism isn't disabled, so quick successive clicks
188might interfere with selection creation in harmless ways.
189
190=item tabbed 225=item tabbed
191 226
192This transforms the terminal into a tabbar with additional terminals, that 227This transforms the terminal into a tabbar with additional terminals, that
193is, it implements what is commonly refered to as "tabbed terminal". The topmost line 228is, it implements what is commonly referred to as "tabbed terminal". The topmost line
194displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one 229displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
195button per tab. 230button per tab.
196 231
197Clicking a button will activate that tab. Pressing B<Shift-Left> and 232Clicking a button will activate that tab. Pressing B<Shift-Left> and
198B<Shift-Right> will switch to the tab left or right of the current one, 233B<Shift-Right> will switch to the tab left or right of the current one,
199while B<Shift-Down> creates a new tab. 234while B<Shift-Down> creates a new tab.
200 235
201=item mark-urls 236The tabbar itself can be configured similarly to a normal terminal, but
237with a resource class of C<URxvt.tabbed>. In addition, it supports the
238following four resources (shown with defaults):
202 239
240 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
241 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
242 URxvt.tabbed.tab-fg: <colour-index, default 0>
243 URxvt.tabbed.tab-bg: <colour-index, default 1>
244
245See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
246indices.
247
248=item matcher
249
203Uses per-line display filtering (C<on_line_update>) to underline urls and 250Uses per-line display filtering (C<on_line_update>) to underline text
204make them clickable. When middle-clicked, the program specified in the 251matching a certain pattern and make it clickable. When clicked with the
205resource C<urlLauncher> (default C<x-www-browser>) will be started with 252mouse button specified in the C<matcher.button> resource (default 2, or
206the URL as first argument. 253middle), the program specified in the C<matcher.launcher> resource
254(default, the C<urlLauncher> resource, C<sensible-browser>) will be started
255with the matched text as first argument. The default configuration is
256suitable for matching URLs and launching a web browser, like the
257former "mark-urls" extension.
258
259The default pattern to match URLs can be overridden with the
260C<matcher.pattern.0> resource, and additional patterns can be specified
261with numbered patterns, in a manner similar to the "selection" extension.
262The launcher can also be overridden on a per-pattern basis.
263
264Example configuration:
265
266 URxvt.perl-ext: default,matcher
267 URxvt.urlLauncher: sensible-browser
268 URxvt.keysym.C-Delete: perl:matcher
269 URxvt.matcher.button: 1
270 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
271 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
272 URxvt.matcher.launcher.2: gvim +$2 $1
273
274=item xim-onthespot
275
276This (experimental) perl extension implements OnTheSpot editing. It does
277not work perfectly, and some input methods don't seem to work well with
278OnTheSpot editing in general, but it seems to work at leats for SCIM and
279kinput2.
280
281You enable it by specifying this extension and a preedit style of
282C<OnTheSpot>, i.e.:
283
284 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
285
286=item kuake<hotkey>
287
288A very primitive quake-console-like extension. It was inspired by a
289description of how the programs C<kuake> and C<yakuake> work: Whenever the
290user presses a global accelerator key (by default C<F10>), the terminal
291will show or hide itself. Another press of the accelerator key will hide
292or show it again.
293
294Initially, the window will not be shown when using this extension.
295
296This is useful if you need a single terminal thats not using any desktop
297space most of the time but is quickly available at the press of a key.
298
299The accelerator key is grabbed regardless of any modifiers, so this
300extension will actually grab a physical key just for this function.
301
302If you want a quake-like animation, tell your window manager to do so
303(fvwm can do it).
207 304
208=item automove-background 305=item automove-background
209 306
210This is basically a one-line extension that dynamically changes the background pixmap offset 307This is basically a very small extension that dynamically changes the
211to the window position, in effect creating the same effect as pseudo transparency with 308background pixmap offset to the window position, in effect creating the
212a custom pixmap. No scaling is supported in this mode. Exmaple: 309same effect as pseudo transparency with a custom pixmap. No scaling is
310supported in this mode. Example:
213 311
214 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 312 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
215 313
314L<http://wiki.archlinux.org/index.php/Perl_Background_Rotation/Extensions>
315shows how this extension can be used to implement an automatically blurred
316transparent background.
317
216=item block-graphics-to-ascii 318=item block-graphics-to-ascii
217 319
218A not very useful example of filtering all text output to the terminal, 320A not very useful example of filtering all text output to the terminal
219by replacing all line-drawing characters (U+2500 .. U+259F) by a 321by replacing all line-drawing characters (U+2500 .. U+259F) by a
220similar-looking ascii character. 322similar-looking ascii character.
221 323
222=item digital-clock 324=item digital-clock
223 325
224Displays a digital clock using the built-in overlay. 326Displays a digital clock using the built-in overlay.
225 327
226=item example-refresh-hooks 328=item remote-clipboard
227 329
228Displays a very simple digital clock in the upper right corner of the 330Somewhat of a misnomer, this extension adds two menu entries to the
229window. Illustrates overwriting the refresh callbacks to create your own 331selection popup that allows one ti run external commands to store the
230overlays or changes. 332selection somewhere and fetch it again.
333
334We use it to implement a "distributed selection mechanism", which just
335means that one command uploads the file to a remote server, and another
336reads it.
337
338The commands can be set using the C<URxvt.remote-selection.store> and
339C<URxvt.remote-selection.fetch> resources. The first should read the
340selection to store from STDIN (always in UTF-8), the second should provide
341the selection data on STDOUT (also in UTF-8).
342
343The defaults (which are likely useless to you) use rsh and cat:
344
345 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
346 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
231 347
232=item selection-pastebin 348=item selection-pastebin
233 349
234This is a little rarely useful extension that Uploads the selection as 350This is a little rarely useful extension that Uploads the selection as
235textfile to a remote site (or does other things). (The implementation is 351textfile to a remote site (or does other things). (The implementation is
255After a successful upload the selection will be replaced by the text given 371After a successful upload the selection will be replaced by the text given
256in the C<selection-pastebin-url> resource (again, the % is the placeholder 372in the C<selection-pastebin-url> resource (again, the % is the placeholder
257for the filename): 373for the filename):
258 374
259 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 375 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
376
377I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
378the double C</> characters as comment start. Use C<\057\057> instead,
379which works regardless of wether xrdb is used to parse the resource file
380or not.
381
382=item example-refresh-hooks
383
384Displays a very simple digital clock in the upper right corner of the
385window. Illustrates overwriting the refresh callbacks to create your own
386overlays or changes.
260 387
261=back 388=back
262 389
263=head1 API DOCUMENTATION 390=head1 API DOCUMENTATION
264 391
298 425
299=back 426=back
300 427
301=head2 Extension Objects 428=head2 Extension Objects
302 429
303Very perl extension is a perl class. A separate perl object is created 430Every perl extension is a perl class. A separate perl object is created
304for each terminal and each extension and passed as the first parameter to 431for each terminal, and each terminal has its own set of extenion objects,
305hooks. So extensions can use their C<$self> object without having to think 432which are passed as the first parameter to hooks. So extensions can use
306about other extensions, with the exception of methods and members that 433their C<$self> object without having to think about clashes with other
434extensions or other terminals, with the exception of methods and members
307begin with an underscore character C<_>: these are reserved for internal 435that begin with an underscore character C<_>: these are reserved for
308use. 436internal use.
309 437
310Although it isn't a C<urxvt::term> object, you can call all methods of the 438Although it isn't a C<urxvt::term> object, you can call all methods of the
311C<urxvt::term> class on this object. 439C<urxvt::term> class on this object.
312 440
313It has the following methods and data members: 441It has the following methods and data members:
334=head2 Hooks 462=head2 Hooks
335 463
336The following subroutines can be declared in extension files, and will be 464The following subroutines can be declared in extension files, and will be
337called whenever the relevant event happens. 465called whenever the relevant event happens.
338 466
339The first argument passed to them is an extension oject as described in 467The first argument passed to them is an extension object as described in
340the in the C<Extension Objects> section. 468the in the C<Extension Objects> section.
341 469
342B<All> of these hooks must return a boolean value. If any of the called 470B<All> of these hooks must return a boolean value. If any of the called
343hooks returns true, then the event counts as being I<consumed>, and the 471hooks returns true, then the event counts as being I<consumed>, and the
344relevant action might not be carried out by the C++ code. 472relevant action might not be carried out by the C++ code.
357place. 485place.
358 486
359=item on_start $term 487=item on_start $term
360 488
361Called at the very end of initialisation of a new terminal, just before 489Called at the very end of initialisation of a new terminal, just before
362trying to map (display) the toplevel and returning to the mainloop. 490trying to map (display) the toplevel and returning to the main loop.
363 491
364=item on_destroy $term 492=item on_destroy $term
365 493
366Called whenever something tries to destroy terminal, before doing anything 494Called whenever something tries to destroy terminal, when the terminal is
367yet. If this hook returns true, then destruction is skipped, but this is 495still fully functional (not for long, though).
368rarely a good idea.
369 496
370=item on_reset $term 497=item on_reset $term
371 498
372Called after the screen is "reset" for any reason, such as resizing or 499Called after the screen is "reset" for any reason, such as resizing or
373control sequences. Here is where you can react on changes to size-related 500control sequences. Here is where you can react on changes to size-related
395 522
396Called whenever a selection has been copied, but before the selection is 523Called whenever a selection has been copied, but before the selection is
397requested from the server. The selection text can be queried and changed 524requested from the server. The selection text can be queried and changed
398by calling C<< $term->selection >>. 525by calling C<< $term->selection >>.
399 526
400Returning a true value aborts selection grabbing. It will still be hilighted. 527Returning a true value aborts selection grabbing. It will still be highlighted.
401 528
402=item on_sel_extend $term 529=item on_sel_extend $term
403 530
404Called whenever the user tries to extend the selection (e.g. with a double 531Called whenever the user tries to extend the selection (e.g. with a double
405click) and is either supposed to return false (normal operation), or 532click) and is either supposed to return false (normal operation), or
406should extend the selection itelf and return true to suppress the built-in 533should extend the selection itself and return true to suppress the built-in
407processing. This can happen multiple times, as long as the callback 534processing. This can happen multiple times, as long as the callback
408returns true, it will be called on every further click by the user and is 535returns true, it will be called on every further click by the user and is
409supposed to enlarge the selection more and more, if possible. 536supposed to enlarge the selection more and more, if possible.
410 537
411See the F<selection> example extension. 538See the F<selection> example extension.
412 539
413=item on_view_change $term, $offset 540=item on_view_change $term, $offset
414 541
415Called whenever the view offset changes, i..e the user or program 542Called whenever the view offset changes, i.e. the user or program
416scrolls. Offset C<0> means display the normal terminal, positive values 543scrolls. Offset C<0> means display the normal terminal, positive values
417show this many lines of scrollback. 544show this many lines of scrollback.
418 545
419=item on_scroll_back $term, $lines, $saved 546=item on_scroll_back $term, $lines, $saved
420 547
424 551
425It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 552It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
426$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 553$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
427number of lines that will be in the scrollback buffer. 554number of lines that will be in the scrollback buffer.
428 555
556=item on_osc_seq $term, $op, $args
557
558Called on every OSC sequence and can be used to suppress it or modify its
559behaviour. The default should be to return an empty list. A true value
560suppresses execution of the request completely. Make sure you don't get
561confused by recursive invocations when you output an osc sequence within
562this callback.
563
564C<on_osc_seq_perl> should be used for new behaviour.
565
429=item on_osc_seq $term, $string 566=item on_osc_seq_perl $term, $string
430 567
431Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 568Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
432operating system command) is processed. Cursor position and other state 569operating system command) is processed. Cursor position and other state
433information is up-to-date when this happens. For interoperability, the 570information is up-to-date when this happens. For interoperability, the
434string should start with the extension name and a colon, to distinguish 571string should start with the extension name and a colon, to distinguish
435it from commands for other extensions, and this might be enforced in the 572it from commands for other extensions, and this might be enforced in the
436future. 573future.
437 574
438Be careful not ever to trust (in a security sense) the data you receive, 575Be careful not ever to trust (in a security sense) the data you receive,
439as its source can not easily be controleld (e-mail content, messages from 576as its source can not easily be controlled (e-mail content, messages from
440other users on the same system etc.). 577other users on the same system etc.).
441 578
442=item on_add_lines $term, $string 579=item on_add_lines $term, $string
443 580
444Called whenever text is about to be output, with the text as argument. You 581Called whenever text is about to be output, with the text as argument. You
475 612
476=item on_refresh_end $term 613=item on_refresh_end $term
477 614
478Called just after the screen gets redrawn. See C<on_refresh_begin>. 615Called just after the screen gets redrawn. See C<on_refresh_begin>.
479 616
480=item on_keyboard_command $term, $string 617=item on_user_command $term, $string
481 618
482Called whenever the user presses a key combination that has a 619Called whenever a user-configured event is being activated (e.g. via
483C<perl:string> action bound to it (see description of the B<keysym> 620a C<perl:string> action bound to a key, see description of the B<keysym>
484resource in the @@RXVT_NAME@@(1) manpage). 621resource in the @@RXVT_NAME@@(1) manpage).
622
623The event is simply the action string. This interface is assumed to change
624slightly in the future.
625
626=item on_resize_all_windows $tern, $new_width, $new_height
627
628Called just after the new window size has been calculated, but before
629windows are actually being resized or hints are being set. If this hook
630returns TRUE, setting of the window hints is being skipped.
485 631
486=item on_x_event $term, $event 632=item on_x_event $term, $event
487 633
488Called on every X event received on the vt window (and possibly other 634Called on every X event received on the vt window (and possibly other
489windows). Should only be used as a last resort. Most event structure 635windows). Should only be used as a last resort. Most event structure
490members are not passed. 636members are not passed.
491 637
638=item on_root_event $term, $event
639
640Like C<on_x_event>, but is called for events on the root window.
641
492=item on_focus_in $term 642=item on_focus_in $term
493 643
494Called whenever the window gets the keyboard focus, before rxvt-unicode 644Called whenever the window gets the keyboard focus, before rxvt-unicode
495does focus in processing. 645does focus in processing.
496 646
497=item on_focus_out $term 647=item on_focus_out $term
498 648
499Called wheneever the window loses keyboard focus, before rxvt-unicode does 649Called whenever the window loses keyboard focus, before rxvt-unicode does
500focus out processing. 650focus out processing.
501 651
502=item on_configure_notify $term, $event 652=item on_configure_notify $term, $event
503 653
504=item on_property_notify $term, $event 654=item on_property_notify $term, $event
561our $LIBDIR; 711our $LIBDIR;
562our $RESNAME; 712our $RESNAME;
563our $RESCLASS; 713our $RESCLASS;
564our $RXVTNAME; 714our $RXVTNAME;
565 715
566our $NOCHAR = chr 0xfffe; 716our $NOCHAR = chr 0xffff;
567 717
568=head2 Variables in the C<urxvt> Package 718=head2 Variables in the C<urxvt> Package
569 719
570=over 4 720=over 4
571 721
587The current terminal. This variable stores the current C<urxvt::term> 737The current terminal. This variable stores the current C<urxvt::term>
588object, whenever a callback/hook is executing. 738object, whenever a callback/hook is executing.
589 739
590=item @urxvt::TERM_INIT 740=item @urxvt::TERM_INIT
591 741
592All coderefs in this array will be called as methods of the next newly 742All code references in this array will be called as methods of the next newly
593created C<urxvt::term> object (during the C<on_init> phase). The array 743created C<urxvt::term> object (during the C<on_init> phase). The array
594gets cleared before the codereferences that were in it are being executed, 744gets cleared before the code references that were in it are being executed,
595so coderefs can push themselves onto it again if they so desire. 745so references can push themselves onto it again if they so desire.
596 746
597This complements to the perl-eval commandline option, but gets executed 747This complements to the perl-eval command line option, but gets executed
598first. 748first.
599 749
600=item @urxvt::TERM_EXT 750=item @urxvt::TERM_EXT
601 751
602Works similar to C<@TERM_INIT>, but contains perl package/class names, which 752Works similar to C<@TERM_INIT>, but contains perl package/class names, which
623 773
624Using this function has the advantage that its output ends up in the 774Using this function has the advantage that its output ends up in the
625correct place, e.g. on stderr of the connecting urxvtc client. 775correct place, e.g. on stderr of the connecting urxvtc client.
626 776
627Messages have a size limit of 1023 bytes currently. 777Messages have a size limit of 1023 bytes currently.
778
779=item @terms = urxvt::termlist
780
781Returns all urxvt::term objects that exist in this process, regardless of
782whether they are started, being destroyed etc., so be careful. Only term
783objects that have perl extensions attached will be returned (because there
784is no urxvt::term objet associated with others).
628 785
629=item $time = urxvt::NOW 786=item $time = urxvt::NOW
630 787
631Returns the "current time" (as per the event loop). 788Returns the "current time" (as per the event loop).
632 789
690Return the foreground/background colour index, respectively. 847Return the foreground/background colour index, respectively.
691 848
692=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 849=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
693 850
694=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 851=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
852
853=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
695 854
696Replace the foreground/background colour in the rendition mask with the 855Replace the foreground/background colour in the rendition mask with the
697specified one. 856specified one.
698 857
699=item $value = urxvt::GET_CUSTOM $rend 858=item $value = urxvt::GET_CUSTOM $rend
718 unless $msg =~ /\n$/; 877 unless $msg =~ /\n$/;
719 urxvt::warn ($msg); 878 urxvt::warn ($msg);
720 }; 879 };
721} 880}
722 881
882no warnings 'utf8';
883
723my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 884my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
724 885
725sub verbose { 886sub verbose {
726 my ($level, $msg) = @_; 887 my ($level, $msg) = @_;
727 warn "$msg\n" if $level <= $verbosity; 888 warn "$msg\n" if $level <= $verbosity;
743 904
744 open my $fh, "<:raw", $path 905 open my $fh, "<:raw", $path
745 or die "$path: $!"; 906 or die "$path: $!";
746 907
747 my $source = 908 my $source =
748 "package $pkg; use strict; use utf8;\n" 909 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
749 . "#line 1 \"$path\"\n{\n" 910 . "#line 1 \"$path\"\n{\n"
750 . (do { local $/; <$fh> }) 911 . (do { local $/; <$fh> })
751 . "\n};\n1"; 912 . "\n};\n1";
752 913
753 eval $source 914 eval $source
778 $TERM->register_package ($_) for @pkg; 939 $TERM->register_package ($_) for @pkg;
779 } 940 }
780 941
781 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 942 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
782 if ($_ eq "default") { 943 if ($_ eq "default") {
783 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 944 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
784 } elsif (/^-(.*)$/) { 945 } elsif (/^-(.*)$/) {
785 delete $ext_arg{$1}; 946 delete $ext_arg{$1};
786 } elsif (/^([^<]+)<(.*)>$/) { 947 } elsif (/^([^<]+)<(.*)>$/) {
787 push @{ $ext_arg{$1} }, $2; 948 push @{ $ext_arg{$1} }, $2;
788 } else { 949 } else {
789 $ext_arg{$_} ||= []; 950 $ext_arg{$_} ||= [];
790 } 951 }
791 } 952 }
792 953
793 while (my ($ext, $argv) = each %ext_arg) { 954 for my $ext (sort keys %ext_arg) {
794 my @files = grep -f $_, map "$_/$ext", @dirs; 955 my @files = grep -f $_, map "$_/$ext", @dirs;
795 956
796 if (@files) { 957 if (@files) {
797 $TERM->register_package (extension_package $files[0], $argv); 958 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
798 } else { 959 } else {
799 warn "perl extension '$ext' not found in perl library search path\n"; 960 warn "perl extension '$ext' not found in perl library search path\n";
800 } 961 }
801 } 962 }
802 963
808 969
809 if (my $cb = $TERM->{_hook}[$htype]) { 970 if (my $cb = $TERM->{_hook}[$htype]) {
810 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 971 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
811 if $verbosity >= 10; 972 if $verbosity >= 10;
812 973
813 keys %$cb; 974 for my $pkg (keys %$cb) {
814
815 while (my ($pkg, $cb) = each %$cb) {
816 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 975 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
817 $retval ||= $retval_; 976 $retval ||= $retval_;
818 977
819 if ($@) { 978 if ($@) {
820 $TERM->ungrab; # better to lose the grab than the session 979 $TERM->ungrab; # better to lose the grab than the session
821 warn $@; 980 warn $@;
833 # clear package 992 # clear package
834 %$TERM = (); 993 %$TERM = ();
835 } 994 }
836 995
837 $retval 996 $retval
997}
998
999sub SET_COLOR($$$) {
1000 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1001}
1002
1003sub rend2mask {
1004 no strict 'refs';
1005 my ($str, $mask) = (@_, 0);
1006 my %color = ( fg => undef, bg => undef );
1007 my @failed;
1008 for my $spec ( split /\s+/, $str ) {
1009 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1010 $color{lc($1)} = $2;
1011 } else {
1012 my $neg = $spec =~ s/^[-^]//;
1013 unless ( exists &{"RS_$spec"} ) {
1014 push @failed, $spec;
1015 next;
1016 }
1017 my $cur = &{"RS_$spec"};
1018 if ( $neg ) {
1019 $mask &= ~$cur;
1020 } else {
1021 $mask |= $cur;
1022 }
1023 }
1024 }
1025 ($mask, @color{qw(fg bg)}, \@failed)
838} 1026}
839 1027
840# urxvt::term::extension 1028# urxvt::term::extension
841 1029
842package urxvt::term::extension; 1030package urxvt::term::extension;
955sub DESTROY { 1143sub DESTROY {
956 $_[0][1]->stop; 1144 $_[0][1]->stop;
957} 1145}
958 1146
959sub condvar { 1147sub condvar {
960 bless \my $flag, urxvt::anyevent::condvar:: 1148 bless \my $flag, urxvt::anyevent::
961} 1149}
962 1150
963sub urxvt::anyevent::condvar::broadcast { 1151sub broadcast {
964 ${$_[0]}++; 1152 ${$_[0]}++;
965} 1153}
966 1154
967sub urxvt::anyevent::condvar::wait { 1155sub wait {
968 unless (${$_[0]}) { 1156 unless (${$_[0]}) {
969 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1157 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
970 } 1158 }
1159}
1160
1161sub one_event {
1162 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
971} 1163}
972 1164
973package urxvt::term; 1165package urxvt::term;
974 1166
975=head2 The C<urxvt::term> Class 1167=head2 The C<urxvt::term> Class
1011hash which defines the environment of the new terminal. 1203hash which defines the environment of the new terminal.
1012 1204
1013Croaks (and probably outputs an error message) if the new instance 1205Croaks (and probably outputs an error message) if the new instance
1014couldn't be created. Returns C<undef> if the new instance didn't 1206couldn't be created. Returns C<undef> if the new instance didn't
1015initialise perl, and the terminal object otherwise. The C<init> and 1207initialise perl, and the terminal object otherwise. The C<init> and
1016C<start> hooks will be called during this call. 1208C<start> hooks will be called before this call returns, and are free to
1209refer to global data (which is race free).
1017 1210
1018=cut 1211=cut
1019 1212
1020sub new { 1213sub new {
1021 my ($class, $env, @args) = @_; 1214 my ($class, $env, @args) = @_;
1022 1215
1216 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1217 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1218
1023 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1219 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1024} 1220}
1025 1221
1026=item $term->destroy 1222=item $term->destroy
1027 1223
1028Destroy the terminal object (close the window, free resources 1224Destroy the terminal object (close the window, free resources
1058 1254
1059Returns true if the option specified by C<$optval> is enabled, and 1255Returns true if the option specified by C<$optval> is enabled, and
1060optionally change it. All option values are stored by name in the hash 1256optionally change it. All option values are stored by name in the hash
1061C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1257C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1062 1258
1063Here is a a likely non-exhaustive list of option names, please see the 1259Here is a likely non-exhaustive list of option names, please see the
1064source file F</src/optinc.h> to see the actual list: 1260source file F</src/optinc.h> to see the actual list:
1065 1261
1066 borderLess console cursorBlink cursorUnderline hold iconic insecure 1262 borderLess console cursorBlink cursorUnderline hold iconic insecure
1067 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1263 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1068 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1264 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1085likely change). 1281likely change).
1086 1282
1087Please note that resource strings will currently only be freed when the 1283Please note that resource strings will currently only be freed when the
1088terminal is destroyed, so changing options frequently will eat memory. 1284terminal is destroyed, so changing options frequently will eat memory.
1089 1285
1090Here is a a likely non-exhaustive list of resource names, not all of which 1286Here is a likely non-exhaustive list of resource names, not all of which
1091are supported in every build, please see the source file F</src/rsinc.h> 1287are supported in every build, please see the source file F</src/rsinc.h>
1092to see the actual list: 1288to see the actual list:
1093 1289
1094 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1290 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1095 borderLess color cursorBlink cursorUnderline cutchars delete_key 1291 borderLess color cursorBlink cursorUnderline cutchars delete_key
1308Replaces the event mask of the pty watcher by the given event mask. Can 1504Replaces the event mask of the pty watcher by the given event mask. Can
1309be used to suppress input and output handling to the pty/tty. See the 1505be used to suppress input and output handling to the pty/tty. See the
1310description of C<< urxvt::timer->events >>. Make sure to always restore 1506description of C<< urxvt::timer->events >>. Make sure to always restore
1311the previous value. 1507the previous value.
1312 1508
1509=item $fd = $term->pty_fd
1510
1511Returns the master file descriptor for the pty in use, or C<-1> if no pty
1512is used.
1513
1313=item $windowid = $term->parent 1514=item $windowid = $term->parent
1314 1515
1315Return the window id of the toplevel window. 1516Return the window id of the toplevel window.
1316 1517
1317=item $windowid = $term->vt 1518=item $windowid = $term->vt
1323Adds the specified events to the vt event mask. Useful e.g. when you want 1524Adds the specified events to the vt event mask. Useful e.g. when you want
1324to receive pointer events all the times: 1525to receive pointer events all the times:
1325 1526
1326 $term->vt_emask_add (urxvt::PointerMotionMask); 1527 $term->vt_emask_add (urxvt::PointerMotionMask);
1327 1528
1529=item $term->focus_in
1530
1531=item $term->focus_out
1532
1533=item $term->key_press ($state, $keycode[, $time])
1534
1535=item $term->key_release ($state, $keycode[, $time])
1536
1537Deliver various fake events to to terminal.
1538
1328=item $window_width = $term->width 1539=item $window_width = $term->width
1329 1540
1330=item $window_height = $term->height 1541=item $window_height = $term->height
1331 1542
1332=item $font_width = $term->fwidth 1543=item $font_width = $term->fwidth
1362=item $env = $term->env 1573=item $env = $term->env
1363 1574
1364Returns a copy of the environment in effect for the terminal as a hashref 1575Returns a copy of the environment in effect for the terminal as a hashref
1365similar to C<\%ENV>. 1576similar to C<\%ENV>.
1366 1577
1578=item @envv = $term->envv
1579
1580Returns the environment as array of strings of the form C<VAR=VALUE>.
1581
1582=item @argv = $term->argv
1583
1584Return the argument vector as this terminal, similar to @ARGV, but
1585includes the program name as first element.
1586
1367=cut 1587=cut
1368 1588
1369sub env { 1589sub env {
1370 if (my $env = $_[0]->_env) {
1371 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1590 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1372 } else {
1373 +{ %ENV }
1374 }
1375} 1591}
1376 1592
1377=item $modifiermask = $term->ModLevel3Mask 1593=item $modifiermask = $term->ModLevel3Mask
1378 1594
1379=item $modifiermask = $term->ModMetaMask 1595=item $modifiermask = $term->ModMetaMask
1387 1603
1388Returns the currently displayed screen (0 primary, 1 secondary). 1604Returns the currently displayed screen (0 primary, 1 secondary).
1389 1605
1390=item $cursor_is_hidden = $term->hidden_cursor 1606=item $cursor_is_hidden = $term->hidden_cursor
1391 1607
1392Returns wether the cursor is currently hidden or not. 1608Returns whether the cursor is currently hidden or not.
1393 1609
1394=item $view_start = $term->view_start ([$newvalue]) 1610=item $view_start = $term->view_start ([$newvalue])
1395 1611
1396Returns the row number of the topmost displayed line. Maximum value is 1612Returns the row number of the topmost displayed line. Maximum value is
1397C<0>, which displays the normal terminal contents. Lower values scroll 1613C<0>, which displays the normal terminal contents. Lower values scroll
1416If C<$new_text> is specified, it will replace characters in the current 1632If C<$new_text> is specified, it will replace characters in the current
1417line, starting at column C<$start_col> (default C<0>), which is useful 1633line, starting at column C<$start_col> (default C<0>), which is useful
1418to replace only parts of a line. The font index in the rendition will 1634to replace only parts of a line. The font index in the rendition will
1419automatically be updated. 1635automatically be updated.
1420 1636
1421C<$text> is in a special encoding: tabs and wide characters that use 1637C<$text> is in a special encoding: tabs and wide characters that use more
1422more than one cell when displayed are padded with C<$urxvt::NOCHAR> 1638than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1423characters. Characters with combining characters and other characters that 1639characters. Characters with combining characters and other characters that
1424do not fit into the normal tetx encoding will be replaced with characters 1640do not fit into the normal tetx encoding will be replaced with characters
1425in the private use area. 1641in the private use area.
1426 1642
1427You have to obey this encoding when changing text. The advantage is 1643You have to obey this encoding when changing text. The advantage is
1574where one character corresponds to one screen cell. See 1790where one character corresponds to one screen cell. See
1575C<< $term->ROW_t >> for details. 1791C<< $term->ROW_t >> for details.
1576 1792
1577=item $string = $term->special_decode $text 1793=item $string = $term->special_decode $text
1578 1794
1579Converts rxvt-unicodes text reprsentation into a perl string. See 1795Converts rxvt-unicodes text representation into a perl string. See
1580C<< $term->ROW_t >> for details. 1796C<< $term->ROW_t >> for details.
1581 1797
1582=item $success = $term->grab_button ($button, $modifiermask) 1798=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1583 1799
1800=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1801
1584Registers a synchronous button grab. See the XGrabButton manpage. 1802Register/unregister a synchronous button grab. See the XGrabButton
1803manpage.
1585 1804
1586=item $success = $term->grab ($eventtime[, $sync]) 1805=item $success = $term->grab ($eventtime[, $sync])
1587 1806
1588Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1807Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1589synchronous (C<$sync> is true). Also remembers the grab timestampe. 1808synchronous (C<$sync> is true). Also remembers the grab timestamp.
1590 1809
1591=item $term->allow_events_async 1810=item $term->allow_events_async
1592 1811
1593Calls XAllowEvents with AsyncBoth for the most recent grab. 1812Calls XAllowEvents with AsyncBoth for the most recent grab.
1594 1813
1707 my ($self, $text, $cb) = @_; 1926 my ($self, $text, $cb) = @_;
1708 1927
1709 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1928 $self->add_item ({ type => "button", text => $text, activate => $cb});
1710} 1929}
1711 1930
1712=item $popup->add_toggle ($text, $cb, $initial_value) 1931=item $popup->add_toggle ($text, $initial_value, $cb)
1713 1932
1714Adds a toggle/checkbox item to the popup. Teh callback gets called 1933Adds a toggle/checkbox item to the popup. The callback gets called
1715whenever it gets toggled, with a boolean indicating its value as its first 1934whenever it gets toggled, with a boolean indicating its new value as its
1716argument. 1935first argument.
1717 1936
1718=cut 1937=cut
1719 1938
1720sub add_toggle { 1939sub add_toggle {
1721 my ($self, $text, $cb, $value) = @_; 1940 my ($self, $text, $value, $cb) = @_;
1722 1941
1723 my $item; $item = { 1942 my $item; $item = {
1724 type => "button", 1943 type => "button",
1725 text => " $text", 1944 text => " $text",
1726 value => $value, 1945 value => $value,
1767=back 1986=back
1768 1987
1769=cut 1988=cut
1770 1989
1771package urxvt::watcher; 1990package urxvt::watcher;
1772
1773@urxvt::timer::ISA = __PACKAGE__;
1774@urxvt::iow::ISA = __PACKAGE__;
1775@urxvt::pw::ISA = __PACKAGE__;
1776@urxvt::iw::ISA = __PACKAGE__;
1777 1991
1778=head2 The C<urxvt::timer> Class 1992=head2 The C<urxvt::timer> Class
1779 1993
1780This class implements timer watchers/events. Time is represented as a 1994This class implements timer watchers/events. Time is represented as a
1781fractional number of seconds since the epoch. Example: 1995fractional number of seconds since the epoch. Example:
1861Set the callback to be called when io events are triggered. C<$reventmask> 2075Set the callback to be called when io events are triggered. C<$reventmask>
1862is a bitset as described in the C<events> method. 2076is a bitset as described in the C<events> method.
1863 2077
1864=item $iow = $iow->fd ($fd) 2078=item $iow = $iow->fd ($fd)
1865 2079
1866Set the filedescriptor (not handle) to watch. 2080Set the file descriptor (not handle) to watch.
1867 2081
1868=item $iow = $iow->events ($eventmask) 2082=item $iow = $iow->events ($eventmask)
1869 2083
1870Set the event mask to watch. The only allowed values are 2084Set the event mask to watch. The only allowed values are
1871C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2085C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1875 2089
1876Start watching for requested events on the given handle. 2090Start watching for requested events on the given handle.
1877 2091
1878=item $iow = $iow->stop 2092=item $iow = $iow->stop
1879 2093
1880Stop watching for events on the given filehandle. 2094Stop watching for events on the given file handle.
1881 2095
1882=back 2096=back
1883 2097
1884=head2 The C<urxvt::iw> Class 2098=head2 The C<urxvt::iw> Class
1885 2099
1932 2146
1933Set the callback to be called when the timer triggers. 2147Set the callback to be called when the timer triggers.
1934 2148
1935=item $pw = $timer->start ($pid) 2149=item $pw = $timer->start ($pid)
1936 2150
1937Tells the wqtcher to start watching for process C<$pid>. 2151Tells the watcher to start watching for process C<$pid>.
1938 2152
1939=item $pw = $pw->stop 2153=item $pw = $pw->stop
1940 2154
1941Stop the watcher. 2155Stop the watcher.
1942 2156
1955 2169
1956=item >= 3 - script loading and management 2170=item >= 3 - script loading and management
1957 2171
1958=item >=10 - all called hooks 2172=item >=10 - all called hooks
1959 2173
1960=item >=11 - hook reutrn values 2174=item >=11 - hook return values
1961 2175
1962=back 2176=back
1963 2177
1964=head1 AUTHOR 2178=head1 AUTHOR
1965 2179
1967 http://software.schmorp.de/pkg/rxvt-unicode 2181 http://software.schmorp.de/pkg/rxvt-unicode
1968 2182
1969=cut 2183=cut
1970 2184
19711 21851
2186
2187# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines