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.177 by root, Sat Jul 18 06:11:57 2009 UTC vs.
Revision 1.194 by sf-exg, Wed Jun 29 21:59:36 2011 UTC

… …
341 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection' 341 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
342 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection' 342 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
343 343
344=item selection-pastebin 344=item selection-pastebin
345 345
346This is a little rarely useful extension that Uploads the selection as 346This is a little rarely useful extension that uploads the selection as
347textfile to a remote site (or does other things). (The implementation is 347textfile to a remote site (or does other things). (The implementation is
348not currently secure for use in a multiuser environment as it writes to 348not currently secure for use in a multiuser environment as it writes to
349F</tmp> directly.). 349F</tmp> directly.).
350 350
351It listens to the C<selection-pastebin:remote-pastebin> keyboard command, 351It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
… …
370 370
371 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 371 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
372 372
373I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret 373I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
374the double C</> characters as comment start. Use C<\057\057> instead, 374the double C</> characters as comment start. Use C<\057\057> instead,
375which works regardless of wether xrdb is used to parse the resource file 375which works regardless of whether xrdb is used to parse the resource file
376or not. 376or not.
377 377
378=item macosx-pastebin and macosx-pastebin-native 378=item macosx-clipboard and macosx-clipboard-native
379 379
380These two modules implement an extended clipboard for Mac OS X. They are 380These two modules implement an extended clipboard for Mac OS X. They are
381used like this: 381used like this:
382 382
383 URxvt.perl-ext-common: default,macosx-clipboard 383 URxvt.perl-ext-common: default,macosx-clipboard
384 URxvt.keysym.M-c: perl:macosx-clipboard:copy 384 URxvt.keysym.M-c: perl:macosx-clipboard:copy
385 URxvt.keysym.M-v: perl:macosx-clipboard:paste 385 URxvt.keysym.M-v: perl:macosx-clipboard:paste
386 386
387The difference between them is that the native variant requires a 387The difference between them is that the native variant requires a
388perl from apple's devkit or so, and C<maxosx-pastebin> requires the 388perl from apple's devkit or so, and C<macosx-clipboard> requires the
389C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is 389C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
390simpler etc. etc. 390simpler etc. etc.
391 391
392=item example-refresh-hooks 392=item example-refresh-hooks
393 393
394Displays a very simple digital clock in the upper right corner of the 394Displays a very simple digital clock in the upper right corner of the
395window. Illustrates overwriting the refresh callbacks to create your own 395window. Illustrates overwriting the refresh callbacks to create your own
396overlays or changes. 396overlays or changes.
397
398=item confirm-paste
399
400Displays a confirmation dialog when a paste containing at least a full
401line is detected.
397 402
398=back 403=back
399 404
400=head1 API DOCUMENTATION 405=head1 API DOCUMENTATION
401 406
… …
417 422
418=over 4 423=over 4
419 424
420=item $text 425=item $text
421 426
422Rxvt-unicodes special way of encoding text, where one "unicode" character 427Rxvt-unicode's special way of encoding text, where one "unicode" character
423always represents one screen cell. See L<ROW_t> for a discussion of this format. 428always represents one screen cell. See L<ROW_t> for a discussion of this format.
424 429
425=item $string 430=item $string
426 431
427A perl text string, with an emphasis on I<text>. It can store all unicode 432A perl text string, with an emphasis on I<text>. It can store all unicode
… …
436=back 441=back
437 442
438=head2 Extension Objects 443=head2 Extension Objects
439 444
440Every perl extension is a perl class. A separate perl object is created 445Every perl extension is a perl class. A separate perl object is created
441for each terminal, and each terminal has its own set of extenion objects, 446for each terminal, and each terminal has its own set of extension objects,
442which are passed as the first parameter to hooks. So extensions can use 447which are passed as the first parameter to hooks. So extensions can use
443their C<$self> object without having to think about clashes with other 448their C<$self> object without having to think about clashes with other
444extensions or other terminals, with the exception of methods and members 449extensions or other terminals, with the exception of methods and members
445that begin with an underscore character C<_>: these are reserved for 450that begin with an underscore character C<_>: these are reserved for
446internal use. 451internal use.
… …
610=item on_tt_write $term, $octets 615=item on_tt_write $term, $octets
611 616
612Called whenever some data is written to the tty/pty and can be used to 617Called whenever some data is written to the tty/pty and can be used to
613suppress or filter tty input. 618suppress or filter tty input.
614 619
620=item on_tt_paste $term, $octets
621
622Called whenever text is about to be pasted, with the text as argument. You
623can filter/change and paste the text yourself by returning a true value
624and calling C<< $term->tt_paste >> yourself. C<$octets> is
625locale-encoded.
626
615=item on_line_update $term, $row 627=item on_line_update $term, $row
616 628
617Called whenever a line was updated or changed. Can be used to filter 629Called whenever a line was updated or changed. Can be used to filter
618screen output (e.g. underline urls or other useless stuff). Only lines 630screen output (e.g. underline urls or other useless stuff). Only lines
619that are being shown will be filtered, and, due to performance reasons, 631that are being shown will be filtered, and, due to performance reasons,
… …
644resource in the @@RXVT_NAME@@(1) manpage). 656resource in the @@RXVT_NAME@@(1) manpage).
645 657
646The event is simply the action string. This interface is assumed to change 658The event is simply the action string. This interface is assumed to change
647slightly in the future. 659slightly in the future.
648 660
649=item on_resize_all_windows $tern, $new_width, $new_height 661=item on_resize_all_windows $term, $new_width, $new_height
650 662
651Called just after the new window size has been calculated, but before 663Called just after the new window size has been calculated, but before
652windows are actually being resized or hints are being set. If this hook 664windows are actually being resized or hints are being set. If this hook
653returns TRUE, setting of the window hints is being skipped. 665returns TRUE, setting of the window hints is being skipped.
654 666
… …
688 700
689=item on_map_notify $term, $event 701=item on_map_notify $term, $event
690 702
691=item on_unmap_notify $term, $event 703=item on_unmap_notify $term, $event
692 704
693Called whenever the corresponding X event is received for the terminal If 705Called whenever the corresponding X event is received for the terminal. If
694the hook returns true, then the even will be ignored by rxvt-unicode. 706the hook returns true, then the event will be ignored by rxvt-unicode.
695 707
696The event is a hash with most values as named by Xlib (see the XEvent 708The event is a hash with most values as named by Xlib (see the XEvent
697manpage), with the additional members C<row> and C<col>, which are the 709manpage), with the additional members C<row> and C<col>, which are the
698(real, not screen-based) row and column under the mouse cursor. 710(real, not screen-based) row and column under the mouse cursor.
699 711
… …
708 720
709=item on_wm_delete_window $term, $event 721=item on_wm_delete_window $term, $event
710 722
711Called when various types of ClientMessage events are received (all with 723Called when various types of ClientMessage events are received (all with
712format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW). 724format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
725
726=item on_bell $term
727
728Called on receipt of a bell character.
713 729
714=back 730=back
715 731
716=cut 732=cut
717 733
… …
782 798
783=over 4 799=over 4
784 800
785=item urxvt::fatal $errormessage 801=item urxvt::fatal $errormessage
786 802
787Fatally aborts execution with the given error message. Avoid at all 803Fatally aborts execution with the given error message (which should
788costs! The only time this is acceptable is when the terminal process 804include a trailing newline). Avoid at all costs! The only time this
789starts up. 805is acceptable (and useful) is in the init hook, where it prevents the
806terminal from starting up.
790 807
791=item urxvt::warn $string 808=item urxvt::warn $string
792 809
793Calls C<rxvt_warn> with the given string which should not include a 810Calls C<rxvt_warn> with the given string which should include a trailing
794newline. The module also overwrites the C<warn> builtin with a function 811newline. The module also overwrites the C<warn> builtin with a function
795that calls this function. 812that calls this function.
796 813
797Using this function has the advantage that its output ends up in the 814Using this function has the advantage that its output ends up in the
798correct place, e.g. on stderr of the connecting urxvtc client. 815correct place, e.g. on stderr of the connecting urxvtc client.
… …
802=item @terms = urxvt::termlist 819=item @terms = urxvt::termlist
803 820
804Returns all urxvt::term objects that exist in this process, regardless of 821Returns all urxvt::term objects that exist in this process, regardless of
805whether they are started, being destroyed etc., so be careful. Only term 822whether they are started, being destroyed etc., so be careful. Only term
806objects that have perl extensions attached will be returned (because there 823objects that have perl extensions attached will be returned (because there
807is no urxvt::term objet associated with others). 824is no urxvt::term object associated with others).
808 825
809=item $time = urxvt::NOW 826=item $time = urxvt::NOW
810 827
811Returns the "current time" (as per the event loop). 828Returns the "current time" (as per the event loop).
812 829
… …
855 872
856=item $rend = urxvt::OVERLAY_RSTYLE 873=item $rend = urxvt::OVERLAY_RSTYLE
857 874
858Return the rendition mask used for overlays by default. 875Return the rendition mask used for overlays by default.
859 876
860=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 877=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
878urxvt::RS_RVid, urxvt::RS_Uline
861 879
862Return the bit that enabled bold, italic, blink, reverse-video and 880Return the bit that enabled bold, italic, blink, reverse-video and
863underline, respectively. To enable such a style, just logically OR it into 881underline, respectively. To enable such a style, just logically OR it into
864the bitset. 882the bitset.
865 883
… …
1124is that you cannot use blocking APIs, but the non-blocking variant should 1142is that you cannot use blocking APIs, but the non-blocking variant should
1125work. 1143work.
1126 1144
1127=cut 1145=cut
1128 1146
1129our $VERSION = '3.4'; 1147our $VERSION = '5.23';
1130 1148
1131$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1149$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1132push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1150push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1133 1151
1134sub timer { 1152sub timer {
… …
1136 1154
1137 my $cb = $arg{cb}; 1155 my $cb = $arg{cb};
1138 1156
1139 urxvt::timer 1157 urxvt::timer
1140 ->new 1158 ->new
1141 ->after ($arg{after}) 1159 ->after ($arg{after}, $arg{interval})
1142 ->interval ($arg{interval}) 1160 ->cb ($arg{interval} ? $cb : sub {
1143 ->start
1144 ->cb (sub {
1145 #TODO interval?
1146 $_[0]->stop; # need to cancel manually 1161 $_[0]->stop; # need to cancel manually
1147 $cb->(); 1162 $cb->();
1148 }) 1163 })
1149} 1164}
1150 1165
… …
1171 my $cb = $arg{cb}; 1186 my $cb = $arg{cb};
1172 1187
1173 urxvt::iw 1188 urxvt::iw
1174 ->new 1189 ->new
1175 ->start 1190 ->start
1176 ->cb (sub { 1191 ->cb ($cb)
1177 #TODO really cancel?
1178 $_[0]->stop; # need to cancel manually
1179 $cb->();
1180 })
1181} 1192}
1182 1193
1183sub child { 1194sub child {
1184 my ($class, %arg) = @_; 1195 my ($class, %arg) = @_;
1185 1196
… …
1187 1198
1188 urxvt::pw 1199 urxvt::pw
1189 ->new 1200 ->new
1190 ->start ($arg{pid}) 1201 ->start ($arg{pid})
1191 ->cb (sub { 1202 ->cb (sub {
1192 #TODO really cancel?
1193 $_[0]->stop; # need to cancel manually 1203 $_[0]->stop; # need to cancel manually
1194 $cb->($_[0]->rpid, $_[0]->rstatus); 1204 $cb->($_[0]->rpid, $_[0]->rstatus);
1195 }) 1205 })
1196} 1206}
1197 1207
… …
1326 1336
1327Here is a likely non-exhaustive list of resource names, not all of which 1337Here is a likely non-exhaustive list of resource names, not all of which
1328are supported in every build, please see the source file F</src/rsinc.h> 1338are supported in every build, please see the source file F</src/rsinc.h>
1329to see the actual list: 1339to see the actual list:
1330 1340
1331 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1341 answerbackstring backgroundPixmap backspace_key blendtype blurradius
1332 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key 1342 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1333 display_name embed ext_bwidth fade font geometry hold iconName 1343 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1334 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1344 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1335 italicFont jumpScroll lineSpace letterSpace loginShell mapAlert meta8 1345 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
1346 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
1336 modifier mouseWheelScrollPage name override_redirect pastableTabs path 1347 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1337 perl_eval perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1348 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1338 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1349 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1339 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1350 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1340 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1351 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1341 secondaryScreen secondaryScroll shade term_name title 1352 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1342 transient_for transparent transparent_all tripleclickwords utmpInhibit 1353 term_name title transient_for transparent tripleclickwords urgentOnBell
1343 visualBell 1354 utmpInhibit visualBell
1344 1355
1345=cut 1356=cut
1346 1357
1347sub resource($$;$) { 1358sub resource($$;$) {
1348 my ($self, $name) = (shift, shift); 1359 my ($self, $name) = (shift, shift);
… …
1380 1391
1381=item ($row, $col) = $term->selection_beg ([$row, $col]) 1392=item ($row, $col) = $term->selection_beg ([$row, $col])
1382 1393
1383=item ($row, $col) = $term->selection_end ([$row, $col]) 1394=item ($row, $col) = $term->selection_end ([$row, $col])
1384 1395
1385Return the current values of the selection mark, begin or end positions, 1396Return the current values of the selection mark, begin or end positions.
1386and optionally set them to new values. 1397
1398When arguments are given, then the selection coordinates are set to
1399C<$row> and C<$col>, and the selection screen is set to the current
1400screen.
1401
1402=item $screen = $term->selection_screen ([$screen])
1403
1404Returns the current selection screen, and then optionally sets it.
1387 1405
1388=item $term->selection_make ($eventtime[, $rectangular]) 1406=item $term->selection_make ($eventtime[, $rectangular])
1389 1407
1390Tries to make a selection as set by C<selection_beg> and 1408Tries to make a selection as set by C<selection_beg> and
1391C<selection_end>. If C<$rectangular> is true (default: false), a 1409C<selection_end>. If C<$rectangular> is true (default: false), a
1392rectangular selection will be made. This is the prefered function to make 1410rectangular selection will be made. This is the preferred function to make
1393a selection. 1411a selection.
1394 1412
1395=item $success = $term->selection_grab ($eventtime) 1413=item $success = $term->selection_grab ($eventtime[, $clipboard])
1396 1414
1397Try to request the primary selection text from the server (for example, as 1415Try to acquire ownership of the primary (clipboard if C<$clipboard> is
1416true) selection from the server. The corresponding text can be set
1398set by the next method). No visual feedback will be given. This function 1417with the next method. No visual feedback will be given. This function
1399is mostly useful from within C<on_sel_grab> hooks. 1418is mostly useful from within C<on_sel_grab> hooks.
1400 1419
1401=item $oldtext = $term->selection ([$newtext]) 1420=item $oldtext = $term->selection ([$newtext, $clipboard])
1402 1421
1403Return the current selection text and optionally replace it by C<$newtext>. 1422Return the current selection (clipboard if C<$clipboard> is true) text
1423and optionally replace it by C<$newtext>.
1424
1425=item $term->selection_clear ([$clipboard])
1426
1427Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
1404 1428
1405=item $term->overlay_simple ($x, $y, $text) 1429=item $term->overlay_simple ($x, $y, $text)
1406 1430
1407Create a simple multi-line overlay box. See the next method for details. 1431Create a simple multi-line overlay box. See the next method for details.
1408 1432
… …
1536locale-specific encoding of the terminal and can contain command sequences 1560locale-specific encoding of the terminal and can contain command sequences
1537(escape codes) that will be interpreted. 1561(escape codes) that will be interpreted.
1538 1562
1539=item $term->tt_write ($octets) 1563=item $term->tt_write ($octets)
1540 1564
1541Write the octets given in C<$data> to the tty (i.e. as program input). To 1565Write the octets given in C<$octets> to the tty (i.e. as program input). To
1542pass characters instead of octets, you should convert your strings first 1566pass characters instead of octets, you should convert your strings first
1543to the locale-specific encoding using C<< $term->locale_encode >>. 1567to the locale-specific encoding using C<< $term->locale_encode >>.
1568
1569=item $term->tt_paste ($octets)
1570
1571Write the octets given in C<$octets> to the tty as a paste, converting NL to
1572CR and bracketing the data with control sequences if bracketed paste mode
1573is set.
1544 1574
1545=item $old_events = $term->pty_ev_events ([$new_events]) 1575=item $old_events = $term->pty_ev_events ([$new_events])
1546 1576
1547Replaces the event mask of the pty watcher by the given event mask. Can 1577Replaces the event mask of the pty watcher by the given event mask. Can
1548be used to suppress input and output handling to the pty/tty. See the 1578be used to suppress input and output handling to the pty/tty. See the
… …
1862Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most 1892Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1863recent grab. 1893recent grab.
1864 1894
1865=item $term->ungrab 1895=item $term->ungrab
1866 1896
1867Calls XUngrab for the most recent grab. Is called automatically on 1897Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1868evaluation errors, as it is better to lose the grab in the error case as 1898evaluation errors, as it is better to lose the grab in the error case as
1869the session. 1899the session.
1870 1900
1871=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists]) 1901=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1872 1902
… …
1894 1924
1895=item $term->XChangeInput ($window, $add_events[, $del_events]) 1925=item $term->XChangeInput ($window, $add_events[, $del_events])
1896 1926
1897Various X or X-related functions. The C<$term> object only serves as 1927Various X or X-related functions. The C<$term> object only serves as
1898the source of the display, otherwise those functions map more-or-less 1928the source of the display, otherwise those functions map more-or-less
1899directory onto the X functions of the same name. 1929directly onto the X functions of the same name.
1900 1930
1901=back 1931=back
1902 1932
1903=cut 1933=cut
1904 1934
… …
2061 2091
2062=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2092=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
2063 2093
2064Set the callback to be called when the timer triggers. 2094Set the callback to be called when the timer triggers.
2065 2095
2066=item $tstamp = $timer->at
2067
2068Return the time this watcher will fire next.
2069
2070=item $timer = $timer->set ($tstamp) 2096=item $timer = $timer->set ($tstamp[, $interval])
2071 2097
2072Set the time the event is generated to $tstamp. 2098Set the time the event is generated to $tstamp (and optionally specifies a
2099new $interval).
2073 2100
2074=item $timer = $timer->interval ($interval) 2101=item $timer = $timer->interval ($interval)
2075 2102
2076Normally (and when C<$interval> is C<0>), the timer will automatically 2103By default (and when C<$interval> is C<0>), the timer will automatically
2077stop after it has fired once. If C<$interval> is non-zero, then the timer 2104stop after it has fired once. If C<$interval> is non-zero, then the timer
2078is automatically rescheduled at the given intervals. 2105is automatically rescheduled at the given intervals.
2079 2106
2080=item $timer = $timer->start 2107=item $timer = $timer->start
2081 2108
2082Start the timer. 2109Start the timer.
2083 2110
2084=item $timer = $timer->start ($tstamp) 2111=item $timer = $timer->start ($tstamp[, $interval])
2085 2112
2086Set the event trigger time to C<$tstamp> and start the timer. 2113Set the event trigger time to C<$tstamp> and start the timer. Optionally
2114also replaces the interval.
2087 2115
2088=item $timer = $timer->after ($delay) 2116=item $timer = $timer->after ($delay[, $interval])
2089 2117
2090Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>. 2118Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
2091 2119
2092=item $timer = $timer->stop 2120=item $timer = $timer->stop
2093 2121
… …
2224 2252
2225=back 2253=back
2226 2254
2227=head1 AUTHOR 2255=head1 AUTHOR
2228 2256
2229 Marc Lehmann <pcg@goof.com> 2257 Marc Lehmann <schmorp@schmorp.de>
2230 http://software.schmorp.de/pkg/rxvt-unicode 2258 http://software.schmorp.de/pkg/rxvt-unicode
2231 2259
2232=cut 2260=cut
2233 2261
22341 22621

Diff Legend

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