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.178 by root, Sat Dec 26 09:02:42 2009 UTC vs.
Revision 1.195 by sf-exg, Wed Jun 29 22:18:11 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
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})
1143 ->start
1144 ->cb ($argv{interval} ? $cb : sub { 1160 ->cb ($arg{interval} ? $cb : sub {
1145 $_[0]->stop; # need to cancel manually 1161 $_[0]->stop; # need to cancel manually
1146 $cb->(); 1162 $cb->();
1147 }) 1163 })
1148} 1164}
1149 1165
1292C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1308C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1293 1309
1294Here is a likely non-exhaustive list of option names, please see the 1310Here is a likely non-exhaustive list of option names, please see the
1295source file F</src/optinc.h> to see the actual list: 1311source file F</src/optinc.h> to see the actual list:
1296 1312
1297 borderLess console cursorBlink cursorUnderline hold iconic insecure 1313 borderLess buffered console cursorBlink cursorUnderline hold iconic
1298 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1314 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1299 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1315 mapAlert meta8 mouseWheelScrollPage override-redirect pastableTabs
1300 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput 1316 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1301 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs 1317 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1302 transparent tripleclickwords utmpInhibit visualBell 1318 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1319 urgentOnBell utmpInhibit visualBell
1303 1320
1304=item $value = $term->resource ($name[, $newval]) 1321=item $value = $term->resource ($name[, $newval])
1305 1322
1306Returns the current resource value associated with a given name and 1323Returns the current resource value associated with a given name and
1307optionally sets a new value. Setting values is most useful in the C<init> 1324optionally sets a new value. Setting values is most useful in the C<init>
1320 1337
1321Here is a likely non-exhaustive list of resource names, not all of which 1338Here is a likely non-exhaustive list of resource names, not all of which
1322are supported in every build, please see the source file F</src/rsinc.h> 1339are supported in every build, please see the source file F</src/rsinc.h>
1323to see the actual list: 1340to see the actual list:
1324 1341
1325 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1342 answerbackstring backgroundPixmap backspace_key blendtype blurradius
1326 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key 1343 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1327 display_name embed ext_bwidth fade font geometry hold iconName 1344 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1328 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1345 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1329 italicFont jumpScroll lineSpace letterSpace loginShell mapAlert meta8 1346 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
1347 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
1330 modifier mouseWheelScrollPage name override_redirect pastableTabs path 1348 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1331 perl_eval perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1349 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1332 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1350 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1333 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1351 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1334 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1352 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1335 secondaryScreen secondaryScroll shade term_name title 1353 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1336 transient_for transparent transparent_all tripleclickwords utmpInhibit 1354 term_name title transient_for transparent tripleclickwords urgentOnBell
1337 visualBell 1355 utmpInhibit visualBell
1338 1356
1339=cut 1357=cut
1340 1358
1341sub resource($$;$) { 1359sub resource($$;$) {
1342 my ($self, $name) = (shift, shift); 1360 my ($self, $name) = (shift, shift);
1374 1392
1375=item ($row, $col) = $term->selection_beg ([$row, $col]) 1393=item ($row, $col) = $term->selection_beg ([$row, $col])
1376 1394
1377=item ($row, $col) = $term->selection_end ([$row, $col]) 1395=item ($row, $col) = $term->selection_end ([$row, $col])
1378 1396
1379Return the current values of the selection mark, begin or end positions, 1397Return the current values of the selection mark, begin or end positions.
1380and optionally set them to new values. 1398
1399When arguments are given, then the selection coordinates are set to
1400C<$row> and C<$col>, and the selection screen is set to the current
1401screen.
1402
1403=item $screen = $term->selection_screen ([$screen])
1404
1405Returns the current selection screen, and then optionally sets it.
1381 1406
1382=item $term->selection_make ($eventtime[, $rectangular]) 1407=item $term->selection_make ($eventtime[, $rectangular])
1383 1408
1384Tries to make a selection as set by C<selection_beg> and 1409Tries to make a selection as set by C<selection_beg> and
1385C<selection_end>. If C<$rectangular> is true (default: false), a 1410C<selection_end>. If C<$rectangular> is true (default: false), a
1386rectangular selection will be made. This is the prefered function to make 1411rectangular selection will be made. This is the preferred function to make
1387a selection. 1412a selection.
1388 1413
1389=item $success = $term->selection_grab ($eventtime) 1414=item $success = $term->selection_grab ($eventtime[, $clipboard])
1390 1415
1391Try to request the primary selection text from the server (for example, as 1416Try to acquire ownership of the primary (clipboard if C<$clipboard> is
1417true) selection from the server. The corresponding text can be set
1392set by the next method). No visual feedback will be given. This function 1418with the next method. No visual feedback will be given. This function
1393is mostly useful from within C<on_sel_grab> hooks. 1419is mostly useful from within C<on_sel_grab> hooks.
1394 1420
1395=item $oldtext = $term->selection ([$newtext]) 1421=item $oldtext = $term->selection ([$newtext, $clipboard])
1396 1422
1397Return the current selection text and optionally replace it by C<$newtext>. 1423Return the current selection (clipboard if C<$clipboard> is true) text
1424and optionally replace it by C<$newtext>.
1425
1426=item $term->selection_clear ([$clipboard])
1427
1428Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
1398 1429
1399=item $term->overlay_simple ($x, $y, $text) 1430=item $term->overlay_simple ($x, $y, $text)
1400 1431
1401Create a simple multi-line overlay box. See the next method for details. 1432Create a simple multi-line overlay box. See the next method for details.
1402 1433
1530locale-specific encoding of the terminal and can contain command sequences 1561locale-specific encoding of the terminal and can contain command sequences
1531(escape codes) that will be interpreted. 1562(escape codes) that will be interpreted.
1532 1563
1533=item $term->tt_write ($octets) 1564=item $term->tt_write ($octets)
1534 1565
1535Write the octets given in C<$data> to the tty (i.e. as program input). To 1566Write the octets given in C<$octets> to the tty (i.e. as program input). To
1536pass characters instead of octets, you should convert your strings first 1567pass characters instead of octets, you should convert your strings first
1537to the locale-specific encoding using C<< $term->locale_encode >>. 1568to the locale-specific encoding using C<< $term->locale_encode >>.
1569
1570=item $term->tt_paste ($octets)
1571
1572Write the octets given in C<$octets> to the tty as a paste, converting NL to
1573CR and bracketing the data with control sequences if bracketed paste mode
1574is set.
1538 1575
1539=item $old_events = $term->pty_ev_events ([$new_events]) 1576=item $old_events = $term->pty_ev_events ([$new_events])
1540 1577
1541Replaces the event mask of the pty watcher by the given event mask. Can 1578Replaces the event mask of the pty watcher by the given event mask. Can
1542be used to suppress input and output handling to the pty/tty. See the 1579be used to suppress input and output handling to the pty/tty. See the
1856Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most 1893Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1857recent grab. 1894recent grab.
1858 1895
1859=item $term->ungrab 1896=item $term->ungrab
1860 1897
1861Calls XUngrab for the most recent grab. Is called automatically on 1898Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1862evaluation errors, as it is better to lose the grab in the error case as 1899evaluation errors, as it is better to lose the grab in the error case as
1863the session. 1900the session.
1864 1901
1865=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists]) 1902=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1866 1903
1888 1925
1889=item $term->XChangeInput ($window, $add_events[, $del_events]) 1926=item $term->XChangeInput ($window, $add_events[, $del_events])
1890 1927
1891Various X or X-related functions. The C<$term> object only serves as 1928Various X or X-related functions. The C<$term> object only serves as
1892the source of the display, otherwise those functions map more-or-less 1929the source of the display, otherwise those functions map more-or-less
1893directory onto the X functions of the same name. 1930directly onto the X functions of the same name.
1894 1931
1895=back 1932=back
1896 1933
1897=cut 1934=cut
1898 1935
2055 2092
2056=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2093=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
2057 2094
2058Set the callback to be called when the timer triggers. 2095Set the callback to be called when the timer triggers.
2059 2096
2060=item $tstamp = $timer->at
2061
2062Return the time this watcher will fire next.
2063
2064=item $timer = $timer->set ($tstamp) 2097=item $timer = $timer->set ($tstamp[, $interval])
2065 2098
2066Set the time the event is generated to $tstamp. 2099Set the time the event is generated to $tstamp (and optionally specifies a
2100new $interval).
2067 2101
2068=item $timer = $timer->interval ($interval) 2102=item $timer = $timer->interval ($interval)
2069 2103
2070Normally (and when C<$interval> is C<0>), the timer will automatically 2104By default (and when C<$interval> is C<0>), the timer will automatically
2071stop after it has fired once. If C<$interval> is non-zero, then the timer 2105stop after it has fired once. If C<$interval> is non-zero, then the timer
2072is automatically rescheduled at the given intervals. 2106is automatically rescheduled at the given intervals.
2073 2107
2074=item $timer = $timer->start 2108=item $timer = $timer->start
2075 2109
2076Start the timer. 2110Start the timer.
2077 2111
2078=item $timer = $timer->start ($tstamp) 2112=item $timer = $timer->start ($tstamp[, $interval])
2079 2113
2080Set the event trigger time to C<$tstamp> and start the timer. 2114Set the event trigger time to C<$tstamp> and start the timer. Optionally
2115also replaces the interval.
2081 2116
2082=item $timer = $timer->after ($delay) 2117=item $timer = $timer->after ($delay[, $interval])
2083 2118
2084Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>. 2119Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
2085 2120
2086=item $timer = $timer->stop 2121=item $timer = $timer->stop
2087 2122
2218 2253
2219=back 2254=back
2220 2255
2221=head1 AUTHOR 2256=head1 AUTHOR
2222 2257
2223 Marc Lehmann <pcg@goof.com> 2258 Marc Lehmann <schmorp@schmorp.de>
2224 http://software.schmorp.de/pkg/rxvt-unicode 2259 http://software.schmorp.de/pkg/rxvt-unicode
2225 2260
2226=cut 2261=cut
2227 2262
22281 22631

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines