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.235 by sf-exg, Sat May 17 15:33:24 2014 UTC vs.
Revision 1.261 by root, Fri Jun 18 12:35:38 2021 UTC

43 43
44Or by adding them to the resource for extensions loaded by default: 44Or by adding them to the resource for extensions loaded by default:
45 45
46 URxvt.perl-ext-common: default,selection-autotransform 46 URxvt.perl-ext-common: default,selection-autotransform
47 47
48Extensions that add command line parameters or resources on their own are 48Extensions may add additional resources and C<actions>, i.e., methods
49loaded automatically when used. 49which can be bound to a key and invoked by the user. An extension can
50define the resources it support using so called META comments,
51described below. Similarly to builtin resources, extension resources
52can also be specified on the command line as long options (with C<.>
53replaced by C<->), in which case the corresponding extension is loaded
54automatically. For this to work the extension B<must> define META
55comments for its resources.
50 56
51=head1 API DOCUMENTATION 57=head1 API DOCUMENTATION
52 58
53=head2 General API Considerations 59=head2 General API Considerations
54 60
106C<urxvt::term> class on this object. 112C<urxvt::term> class on this object.
107 113
108Additional methods only supported for extension objects are described in 114Additional methods only supported for extension objects are described in
109the C<urxvt::extension> section below. 115the C<urxvt::extension> section below.
110 116
117=head2 META comments
118
119Rxvt-unicode recognizes special meta comments in extensions that define
120different types of metadata. These comments are scanned whenever a
121terminal is created and are typically used to autoload extensions when
122their resources or command line parameters are used.
123
124Currently, it recognises only one such comment:
125
126=over 4
127
128=item #:META:RESOURCE:name:type:desc
129
130The RESOURCE comment defines a resource used by the extension, where
131C<name> is the resource name, C<type> is the resource type, C<boolean>
132or C<string>, and C<desc> is the resource description.
133
134The extension will be autoloaded when this resource is specified or used
135as a command line parameter.
136
137=back
138
111=head2 Hooks 139=head2 Hooks
112 140
113The following subroutines can be declared in extension files, and will be 141The following subroutines can be declared in extension files, and will be
114called whenever the relevant event happens. 142called whenever the relevant event happens.
115 143
280code is run after this hook, and takes precedence. 308code is run after this hook, and takes precedence.
281 309
282=item on_refresh_end $term 310=item on_refresh_end $term
283 311
284Called just after the screen gets redrawn. See C<on_refresh_begin>. 312Called just after the screen gets redrawn. See C<on_refresh_begin>.
313
314=item on_action $term, $string
315
316Called whenever an action is invoked for the corresponding extension
317(e.g. via a C<extension:string> builtin action bound to a key, see
318description of the B<keysym> resource in the urxvt(1) manpage). The
319event is simply the action string. Note that an action event is always
320associated to a single extension.
285 321
286=item on_user_command $term, $string *DEPRECATED* 322=item on_user_command $term, $string *DEPRECATED*
287 323
288Called whenever a user-configured event is being activated (e.g. via 324Called whenever a user-configured event is being activated (e.g. via
289a C<perl:string> action bound to a key, see description of the B<keysym> 325a C<perl:string> action bound to a key, see description of the B<keysym>
480ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify, 516ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
481CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest, 517CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
482SelectionNotify, ColormapNotify, ClientMessage, MappingNotify 518SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
483 519
484Various constants for use in X calls and event processing. 520Various constants for use in X calls and event processing.
521
522=item urxvt::PrivMode_132, PrivMode_132OK, PrivMode_rVideo, PrivMode_relOrigin,
523PrivMode_Screen, PrivMode_Autowrap, PrivMode_aplCUR, PrivMode_aplKP,
524PrivMode_HaveBackSpace, PrivMode_BackSpace, PrivMode_ShiftKeys,
525PrivMode_VisibleCursor, PrivMode_MouseX10, PrivMode_MouseX11,
526PrivMode_scrollBar, PrivMode_TtyOutputInh, PrivMode_Keypress,
527PrivMode_smoothScroll, PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent,
528PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtMouseUTF8,
529PrivMode_ExtMouseUrxvt, PrivMode_BlinkingCursor, PrivMode_mouse_report,
530PrivMode_Default
531
532Constants for checking DEC private modes.
485 533
486=back 534=back
487 535
488=head2 RENDITION 536=head2 RENDITION
489 537
555no warnings 'utf8'; 603no warnings 'utf8';
556 604
557sub parse_resource { 605sub parse_resource {
558 my ($term, $name, $isarg, $longopt, $flag, $value) = @_; 606 my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
559 607
560 $name =~ y/-/./ if $isarg;
561
562 $term->scan_extensions; 608 $term->scan_extensions;
563 609
610 # iterating over all resources has quadratic time overhead
611 # overall, maybe this could be optimised?
564 my $r = $term->{meta}{resource}; 612 my $r = $term->{meta}{resource};
565 keys %$r; # reset iterator 613 keys %$r; # reset iterator
566 while (my ($pattern, $v) = each %$r) { 614 while (my ($k, $v) = each %$r) {
567 if ( 615 my $pattern = $k;
616 $pattern =~ y/./-/ if $isarg;
617 my $prefix = $name;
618 my $suffix;
568 $pattern =~ /\.$/ 619 if ($pattern =~ /\-$/) {
569 ? $pattern eq substr $name, 0, length $pattern 620 $prefix = substr $name, 0, length $pattern;
570 : $pattern eq $name 621 $suffix = substr $name, length $pattern;
571 ) { 622 }
623 if ($pattern eq $prefix) {
572 $name = "$urxvt::RESCLASS.$name"; 624 $name = "$urxvt::RESCLASS.$k$suffix";
573 625
574 push @{ $term->{perl_ext_3} }, $v->[0]; 626 push @{ $term->{perl_ext_3} }, $v->[0];
627
628 return 1 unless $isarg;
575 629
576 if ($v->[1] eq "boolean") { 630 if ($v->[1] eq "boolean") {
577 $term->put_option_db ($name, $flag ? "true" : "false"); 631 $term->put_option_db ($name, $flag ? "true" : "false");
578 return 1; 632 return 1;
579 } else { 633 } else {
676 $TERM->register_package ($_) for @pkg; 730 $TERM->register_package ($_) for @pkg;
677 } 731 }
678 732
679 for ( 733 for (
680 @{ delete $TERM->{perl_ext_3} }, 734 @{ delete $TERM->{perl_ext_3} },
681 grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2 735 (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2),
682 ) { 736 ) {
683 if ($_ eq "default") { 737 if ($_ eq "default") {
738
739 $ext_arg{$_} = []
684 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline); 740 for qw(selection option-popup selection-popup readline searchable-scrollback confirm-paste);
741
742 for ($TERM->_keysym_resources) {
743 next if /^(?:string|command|builtin|builtin-string|perl)/;
744 next unless /^([A-Za-z0-9_\-]+):/;
745
746 my $ext = $1;
747
748 $ext_arg{$ext} = [];
749 }
750
685 } elsif (/^-(.*)$/) { 751 } elsif (/^-(.*)$/) {
686 delete $ext_arg{$1}; 752 delete $ext_arg{$1};
753
687 } elsif (/^([^<]+)<(.*)>$/) { 754 } elsif (/^([^<]+)<(.*)>$/) {
688 push @{ $ext_arg{$1} }, $2; 755 push @{ $ext_arg{$1} }, $2;
756
689 } else { 757 } else {
690 $ext_arg{$_} ||= []; 758 $ext_arg{$_} ||= [];
691 } 759 }
692 } 760 }
693 761
918 } 986 }
919 987
920 bless \%disable, "urxvt::extension::on_disable" 988 bless \%disable, "urxvt::extension::on_disable"
921} 989}
922 990
991=item $self->bind_action ($hotkey, $action)
992
923=item $self->x_resource ($pattern) 993=item $self->x_resource ($pattern)
924 994
925=item $self->x_resource_boolean ($pattern) 995=item $self->x_resource_boolean ($pattern)
926 996
927These methods support an additional C<%> prefix when called on an 997These methods support an additional C<%> prefix for C<$action> or
928extension object - see the description of these methods in the 998C<$pattern> when called on an extension object, compared to the
999C<urxvt::term> methods of the same name - see the description of these
929C<urxvt::term> class for details. 1000methods in the C<urxvt::term> class for details.
930 1001
931=cut 1002=cut
1003
1004sub bind_action {
1005 my ($self, $hotkey, $action) = @_;
1006 $action =~ s/^%:/$_[0]{_name}:/;
1007 $self->{term}->bind_action ($hotkey, $action)
1008}
932 1009
933sub x_resource { 1010sub x_resource {
934 my ($self, $name) = @_; 1011 my ($self, $name) = @_;
935 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 1012 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
936 $self->{term}->x_resource ($name) 1013 $self->{term}->x_resource ($name)
1077sub scan_extensions { 1154sub scan_extensions {
1078 my ($self) = @_; 1155 my ($self) = @_;
1079 1156
1080 return if exists $self->{meta}; 1157 return if exists $self->{meta};
1081 1158
1082 my @libdirs = perl_libdirs $self; 1159 my @urxvtdirs = perl_libdirs $self;
1160# my @cpandirs = grep -d, map "$_/URxvt/Ext", @INC;
1083 1161
1084 return if $self->{meta_libdirs} eq join "\x00", @libdirs;
1085
1086 my %meta;
1087
1088 $self->{meta_libdirs} = join "\x00", @libdirs;
1089 $self->{meta} = \%meta; 1162 $self->{meta} = \my %meta;
1090
1091 my %ext;
1092 1163
1093 # first gather extensions 1164 # first gather extensions
1094 for my $dir (reverse @libdirs) { 1165
1166 my $gather = sub {
1167 my ($dir, $core) = @_;
1168
1095 opendir my $fh, $dir 1169 opendir my $fh, $dir
1096 or next; 1170 or return;
1171
1097 for my $ext (readdir $fh) { 1172 for my $ext (readdir $fh) {
1098 $ext !~ /^\./ 1173 $ext !~ /^\./
1174 or next;
1175
1099 and open my $fh, "<", "$dir/$ext" 1176 open my $fh, "<", "$dir/$ext"
1177 or next;
1178
1179 -f $fh
1180 or next;
1181
1182 $ext =~ s/\.uext$// or $core
1100 or next; 1183 or next;
1101 1184
1102 my %ext = (dir => $dir); 1185 my %ext = (dir => $dir);
1103 1186
1104 while (<$fh>) { 1187 while (<$fh>) {
1108 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) { 1191 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) {
1109 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n"; 1192 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n";
1110 } else { 1193 } else {
1111 $ext{resource}{$pattern} = [$ext, $type, $desc]; 1194 $ext{resource}{$pattern} = [$ext, $type, $desc];
1112 } 1195 }
1113 } elsif (/^#:META:BINDING:(.*)/) {
1114 my ($keysym, $action) = split /:/, $1;
1115 $ext{binding}{$keysym} = $action;
1116 } elsif (/^\s*(?:#|$)/) { 1196 } elsif (/^\s*(?:#|$)/) {
1117 # skip other comments and empty lines 1197 # skip other comments and empty lines
1118 } else { 1198 } else {
1119 last; # stop parsing on first non-empty non-comment line 1199 last; # stop parsing on first non-empty non-comment line
1120 } 1200 }
1121 } 1201 }
1122 1202
1123 $meta{$ext} = \%ext; 1203 $meta{ext}{$ext} = \%ext;
1124 } 1204 }
1125 } 1205 };
1126 1206
1207# $gather->($_, 0) for @cpandirs;
1208 $gather->($_, 1) for @urxvtdirs;
1209
1127 # and now merge resources and bindings 1210 # and now merge resources
1211
1212 $meta{resource} = \my %resource;
1213
1128 while (my ($k, $v) = each %ext) { 1214 while (my ($k, $v) = each %{ $meta{ext} }) {
1129 #TODO: should check for extensions overriding each other 1215 #TODO: should check for extensions overriding each other
1130 %{ $meta{resource} } = (%{ $meta{resource} }, %{ $v->{resource} }); 1216 %resource = (%resource, %{ $v->{resource} });
1131 %{ $meta{binding} } = (%{ $meta{binding} }, %{ $v->{binding} });
1132 } 1217 }
1133} 1218}
1134 1219
1135=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1220=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1136 1221
1252Returns the X-Resource for the given pattern, excluding the program or 1337Returns the X-Resource for the given pattern, excluding the program or
1253class name, i.e. C<< $term->x_resource ("boldFont") >> should return the 1338class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1254same value as used by this instance of rxvt-unicode. Returns C<undef> if no 1339same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1255resource with that pattern exists. 1340resource with that pattern exists.
1256 1341
1257Extensions that define extra resource or command line arguments also need 1342Extensions that define extra resources also need to call this method
1258to call this method to access their values. 1343to access their values.
1259 1344
1260If the method is called on an extension object (basically, from an 1345If the method is called on an extension object (basically, from an
1261extension), then the special prefix C<%.> will be replaced by the name of 1346extension), then the special prefix C<%.> will be replaced by the name of
1262the extension and a dot, and the lone string C<%> will be replaced by the 1347the extension and a dot, and the lone string C<%> will be replaced by the
1263extension name itself. This makes it possible to code extensions so you 1348extension name itself. This makes it possible to code extensions so you
1264can rename them and get a new set of commandline switches and resources 1349can rename them and get a new set of resources without having to change
1265without having to change the actual code. 1350the actual code.
1266 1351
1267This method should only be called during the C<on_start> hook, as there is 1352This method should only be called during the C<on_start> hook, as there is
1268only one resource database per display, and later invocations might return 1353only one resource database per display, and later invocations might return
1269the wrong resources. 1354the wrong resources.
1270 1355
1282 my $res = &x_resource; 1367 my $res = &x_resource;
1283 1368
1284 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0 1369 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1285} 1370}
1286 1371
1372=item $action = $term->lookup_keysym ($keysym, $state)
1373
1374Returns the action bound to key combination C<($keysym, $state)>,
1375if a binding for it exists, and C<undef> otherwise.
1376
1287=item $success = $term->bind_action ($key, $octets) 1377=item $success = $term->bind_action ($key, $action)
1288 1378
1289Adds a key binding exactly as specified via a C<keysym> resource. See the 1379Adds a key binding exactly as specified via a C<keysym> resource. See the
1290C<keysym> resource in the urxvt(1) manpage. 1380C<keysym> resource in the urxvt(1) manpage.
1381
1382To add default bindings for actions, an extension should call C<<
1383->bind_action >> in its C<init> hook for every such binding. Doing it
1384in the C<init> hook allows users to override or remove the binding
1385again.
1386
1387Example: the C<searchable-scrollback> by default binds itself
1388on C<Meta-s>, using C<< $self->bind_action >>, which calls C<<
1389$term->bind_action >>.
1390
1391 sub init {
1392 my ($self) = @_;
1393
1394 $self->bind_action ("M-s" => "%:start");
1395 }
1291 1396
1292=item $rend = $term->rstyle ([$new_rstyle]) 1397=item $rend = $term->rstyle ([$new_rstyle])
1293 1398
1294Return and optionally change the current rendition. Text that is output by 1399Return and optionally change the current rendition. Text that is output by
1295the terminal application will use this style. 1400the terminal application will use this style.
1453 1558
1454=item $term->scr_add_lines ($string) 1559=item $term->scr_add_lines ($string)
1455 1560
1456Write the given text string to the screen, as if output by the application 1561Write the given text string to the screen, as if output by the application
1457running inside the terminal. It may not contain command sequences (escape 1562running inside the terminal. It may not contain command sequences (escape
1458codes), but is free to use line feeds, carriage returns and tabs. The 1563codes - see C<cmd_parse> for that), but is free to use line feeds,
1459string is a normal text string, not in locale-dependent encoding. 1564carriage returns and tabs. The string is a normal text string, not in
1565locale-dependent encoding.
1460 1566
1461Normally its not a good idea to use this function, as programs might be 1567Normally its not a good idea to use this function, as programs might be
1462confused by changes in cursor position or scrolling. Its useful inside a 1568confused by changes in cursor position or scrolling. Its useful inside a
1463C<on_add_lines> hook, though. 1569C<on_add_lines> hook, though.
1464 1570
1472locale-specific encoding of the terminal and can contain command sequences 1578locale-specific encoding of the terminal and can contain command sequences
1473(escape codes) that will be interpreted. 1579(escape codes) that will be interpreted.
1474 1580
1475=item $term->tt_write ($octets) 1581=item $term->tt_write ($octets)
1476 1582
1477Write the octets given in C<$octets> to the tty (i.e. as program input). To 1583Write the octets given in C<$octets> to the tty (i.e. as user input
1584to the program, see C<cmd_parse> for the opposite direction). To pass
1478pass characters instead of octets, you should convert your strings first 1585characters instead of octets, you should convert your strings first to the
1479to the locale-specific encoding using C<< $term->locale_encode >>. 1586locale-specific encoding using C<< $term->locale_encode >>.
1480 1587
1481=item $term->tt_write_user_input ($octets) 1588=item $term->tt_write_user_input ($octets)
1482 1589
1483Like C<tt_write>, but should be used when writing strings in response to 1590Like C<tt_write>, but should be used when writing strings in response to
1484the user pressing a key, to invokes the additional actions requested by 1591the user pressing a key, to invoke the additional actions requested by
1485the user for that case (C<tt_write> doesn't do that). 1592the user for that case (C<tt_write> doesn't do that).
1486 1593
1487The typical use case would be inside C<on_action> hooks. 1594The typical use case would be inside C<on_action> hooks.
1488 1595
1489=item $term->tt_paste ($octets) 1596=item $term->tt_paste ($octets)
1531 1638
1532=item $term->key_release ($state, $keycode[, $time]) 1639=item $term->key_release ($state, $keycode[, $time])
1533 1640
1534Deliver various fake events to to terminal. 1641Deliver various fake events to to terminal.
1535 1642
1536=item $window_width = $term->width 1643=item $window_width = $term->width ([$new_value])
1537 1644
1538=item $window_height = $term->height 1645=item $window_height = $term->height ([$new_value])
1539 1646
1540=item $font_width = $term->fwidth 1647=item $font_width = $term->fwidth ([$new_value])
1541 1648
1542=item $font_height = $term->fheight 1649=item $font_height = $term->fheight ([$new_value])
1543 1650
1544=item $font_ascent = $term->fbase 1651=item $font_ascent = $term->fbase ([$new_value])
1545 1652
1546=item $terminal_rows = $term->nrow 1653=item $terminal_rows = $term->nrow ([$new_value])
1547 1654
1548=item $terminal_columns = $term->ncol 1655=item $terminal_columns = $term->ncol ([$new_value])
1549 1656
1550=item $has_focus = $term->focus 1657=item $has_focus = $term->focus ([$new_value])
1551 1658
1552=item $is_mapped = $term->mapped 1659=item $is_mapped = $term->mapped ([$new_value])
1553 1660
1554=item $max_scrollback = $term->saveLines 1661=item $max_scrollback = $term->saveLines ([$new_value])
1555 1662
1556=item $nrow_plus_saveLines = $term->total_rows 1663=item $nrow_plus_saveLines = $term->total_rows ([$new_value])
1557 1664
1558=item $topmost_scrollback_row = $term->top_row 1665=item $topmost_scrollback_row = $term->top_row ([$new_value])
1559 1666
1560Return various integers describing terminal characteristics. 1667Return various integers describing terminal characteristics. If an
1668argument is given, changes the value and returns the previous one.
1561 1669
1562=item $x_display = $term->display_id 1670=item $x_display = $term->display_id
1563 1671
1564Return the DISPLAY used by rxvt-unicode. 1672Return the DISPLAY used by rxvt-unicode.
1565 1673
1601Returns the currently displayed screen (0 primary, 1 secondary). 1709Returns the currently displayed screen (0 primary, 1 secondary).
1602 1710
1603=item $cursor_is_hidden = $term->hidden_cursor 1711=item $cursor_is_hidden = $term->hidden_cursor
1604 1712
1605Returns whether the cursor is currently hidden or not. 1713Returns whether the cursor is currently hidden or not.
1714
1715=item $priv_modes = $term->priv_modes
1716
1717Returns a bitset with the state of DEC private modes.
1718
1719Example:
1720
1721 if ($term->priv_modes & urxvt::PrivMode_mouse_report) {
1722 # mouse reporting is turned on
1723 }
1606 1724
1607=item $view_start = $term->view_start ([$newvalue]) 1725=item $view_start = $term->view_start ([$newvalue])
1608 1726
1609Returns the row number of the topmost displayed line. Maximum value is 1727Returns the row number of the topmost displayed line. Maximum value is
1610C<0>, which displays the normal terminal contents. Lower values scroll 1728C<0>, which displays the normal terminal contents. Lower values scroll
1615Requests a screen refresh. At the next opportunity, rxvt-unicode will 1733Requests a screen refresh. At the next opportunity, rxvt-unicode will
1616compare the on-screen display with its stored representation. If they 1734compare the on-screen display with its stored representation. If they
1617differ, it redraws the differences. 1735differ, it redraws the differences.
1618 1736
1619Used after changing terminal contents to display them. 1737Used after changing terminal contents to display them.
1738
1739=item $term->refresh_check
1740
1741Checks if a refresh has been requested and, if so, schedules one.
1620 1742
1621=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1743=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1622 1744
1623Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >> 1745Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1624is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost 1746is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines