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.257 by root, Thu Jul 13 10:31:27 2017 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.
121
122Currently, it recognises only one such comment:
123
124=over 4
125
126=item #:META:RESOURCE:name:type:desc
127
128The RESOURCE comment defines a resource used by the extension, where
129C<name> is the resource name, C<type> is the resource type, C<boolean>
130or C<string>, and C<desc> is the resource description.
131
132=back
133
111=head2 Hooks 134=head2 Hooks
112 135
113The following subroutines can be declared in extension files, and will be 136The following subroutines can be declared in extension files, and will be
114called whenever the relevant event happens. 137called whenever the relevant event happens.
115 138
280code is run after this hook, and takes precedence. 303code is run after this hook, and takes precedence.
281 304
282=item on_refresh_end $term 305=item on_refresh_end $term
283 306
284Called just after the screen gets redrawn. See C<on_refresh_begin>. 307Called just after the screen gets redrawn. See C<on_refresh_begin>.
308
309=item on_action $term, $string
310
311Called whenever an action is invoked for the corresponding extension
312(e.g. via a C<extension:string> builtin action bound to a key, see
313description of the B<keysym> resource in the urxvt(1) manpage). The
314event is simply the action string. Note that an action event is always
315associated to a single extension.
285 316
286=item on_user_command $term, $string *DEPRECATED* 317=item on_user_command $term, $string *DEPRECATED*
287 318
288Called whenever a user-configured event is being activated (e.g. via 319Called 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> 320a C<perl:string> action bound to a key, see description of the B<keysym>
480ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify, 511ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
481CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest, 512CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
482SelectionNotify, ColormapNotify, ClientMessage, MappingNotify 513SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
483 514
484Various constants for use in X calls and event processing. 515Various constants for use in X calls and event processing.
516
517=item urxvt::PrivMode_132, PrivMode_132OK, PrivMode_rVideo, PrivMode_relOrigin,
518PrivMode_Screen, PrivMode_Autowrap, PrivMode_aplCUR, PrivMode_aplKP,
519PrivMode_HaveBackSpace, PrivMode_BackSpace, PrivMode_ShiftKeys,
520PrivMode_VisibleCursor, PrivMode_MouseX10, PrivMode_MouseX11,
521PrivMode_scrollBar, PrivMode_TtyOutputInh, PrivMode_Keypress,
522PrivMode_smoothScroll, PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent,
523PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtModeMouse,
524PrivMode_ExtMouseRight, PrivMode_BlinkingCursor, PrivMode_mouse_report,
525PrivMode_Default
526
527Constants for checking DEC private modes.
485 528
486=back 529=back
487 530
488=head2 RENDITION 531=head2 RENDITION
489 532
555no warnings 'utf8'; 598no warnings 'utf8';
556 599
557sub parse_resource { 600sub parse_resource {
558 my ($term, $name, $isarg, $longopt, $flag, $value) = @_; 601 my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
559 602
560 $name =~ y/-/./ if $isarg;
561
562 $term->scan_extensions; 603 $term->scan_extensions;
563 604
564 my $r = $term->{meta}{resource}; 605 my $r = $term->{meta}{resource};
565 keys %$r; # reset iterator 606 keys %$r; # reset iterator
566 while (my ($pattern, $v) = each %$r) { 607 while (my ($k, $v) = each %$r) {
567 if ( 608 my $pattern = $k;
609 $pattern =~ y/./-/ if $isarg;
610 my $prefix = $name;
611 my $suffix;
568 $pattern =~ /\.$/ 612 if ($pattern =~ /\-$/) {
569 ? $pattern eq substr $name, 0, length $pattern 613 $prefix = substr $name, 0, length $pattern;
570 : $pattern eq $name 614 $suffix = substr $name, length $pattern;
571 ) { 615 }
616 if ($pattern eq $prefix) {
572 $name = "$urxvt::RESCLASS.$name"; 617 $name = "$urxvt::RESCLASS.$k$suffix";
573 618
574 push @{ $term->{perl_ext_3} }, $v->[0]; 619 push @{ $term->{perl_ext_3} }, $v->[0];
620
621 return 1 unless $isarg;
575 622
576 if ($v->[1] eq "boolean") { 623 if ($v->[1] eq "boolean") {
577 $term->put_option_db ($name, $flag ? "true" : "false"); 624 $term->put_option_db ($name, $flag ? "true" : "false");
578 return 1; 625 return 1;
579 } else { 626 } else {
675 @TERM_EXT = (); 722 @TERM_EXT = ();
676 $TERM->register_package ($_) for @pkg; 723 $TERM->register_package ($_) for @pkg;
677 } 724 }
678 725
679 for ( 726 for (
727 (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2),
680 @{ delete $TERM->{perl_ext_3} }, 728 @{ delete $TERM->{perl_ext_3} }
681 grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2
682 ) { 729 ) {
683 if ($_ eq "default") { 730 if ($_ eq "default") {
731
732 $ext_arg{$_} = []
684 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline); 733 for qw(selection option-popup selection-popup readline searchable-scrollback);
734
735 for ($TERM->_keysym_resources) {
736 next if /^(?:string|command|builtin|builtin-string|perl)/;
737 next unless /^([A-Za-z0-9_\-]+):/;
738
739 my $ext = $1;
740
741 $ext_arg{$ext} = [];
742 }
743
685 } elsif (/^-(.*)$/) { 744 } elsif (/^-(.*)$/) {
686 delete $ext_arg{$1}; 745 delete $ext_arg{$1};
746
687 } elsif (/^([^<]+)<(.*)>$/) { 747 } elsif (/^([^<]+)<(.*)>$/) {
688 push @{ $ext_arg{$1} }, $2; 748 push @{ $ext_arg{$1} }, $2;
749
689 } else { 750 } else {
690 $ext_arg{$_} ||= []; 751 $ext_arg{$_} ||= [];
691 } 752 }
692 } 753 }
693 754
918 } 979 }
919 980
920 bless \%disable, "urxvt::extension::on_disable" 981 bless \%disable, "urxvt::extension::on_disable"
921} 982}
922 983
984=item $self->bind_action ($hotkey, $action)
985
923=item $self->x_resource ($pattern) 986=item $self->x_resource ($pattern)
924 987
925=item $self->x_resource_boolean ($pattern) 988=item $self->x_resource_boolean ($pattern)
926 989
927These methods support an additional C<%> prefix when called on an 990These methods support an additional C<%> prefix for C<$action> or
928extension object - see the description of these methods in the 991C<$pattern> when called on an extension object, compared to the
992C<urxvt::term> methods of the same name - see the description of these
929C<urxvt::term> class for details. 993methods in the C<urxvt::term> class for details.
930 994
931=cut 995=cut
996
997sub bind_action {
998 my ($self, $hotkey, $action) = @_;
999 $action =~ s/^%:/$_[0]{_name}:/;
1000 $self->{term}->bind_action ($hotkey, $action)
1001}
932 1002
933sub x_resource { 1003sub x_resource {
934 my ($self, $name) = @_; 1004 my ($self, $name) = @_;
935 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 1005 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
936 $self->{term}->x_resource ($name) 1006 $self->{term}->x_resource ($name)
1077sub scan_extensions { 1147sub scan_extensions {
1078 my ($self) = @_; 1148 my ($self) = @_;
1079 1149
1080 return if exists $self->{meta}; 1150 return if exists $self->{meta};
1081 1151
1082 my @libdirs = perl_libdirs $self; 1152 my @urxvtdirs = perl_libdirs $self;
1153# my @cpandirs = grep -d, map "$_/URxvt/Ext", @INC;
1083 1154
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; 1155 $self->{meta} = \my %meta;
1090
1091 my %ext;
1092 1156
1093 # first gather extensions 1157 # first gather extensions
1094 for my $dir (reverse @libdirs) { 1158
1159 my $gather = sub {
1160 my ($dir, $core) = @_;
1161
1095 opendir my $fh, $dir 1162 opendir my $fh, $dir
1096 or next; 1163 or return;
1164
1097 for my $ext (readdir $fh) { 1165 for my $ext (readdir $fh) {
1098 $ext !~ /^\./ 1166 $ext !~ /^\./
1167 or next;
1168
1099 and open my $fh, "<", "$dir/$ext" 1169 open my $fh, "<", "$dir/$ext"
1170 or next;
1171
1172 -f $fh
1173 or next;
1174
1175 $ext =~ s/\.uext$// or $core
1100 or next; 1176 or next;
1101 1177
1102 my %ext = (dir => $dir); 1178 my %ext = (dir => $dir);
1103 1179
1104 while (<$fh>) { 1180 while (<$fh>) {
1108 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) { 1184 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) {
1109 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n"; 1185 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n";
1110 } else { 1186 } else {
1111 $ext{resource}{$pattern} = [$ext, $type, $desc]; 1187 $ext{resource}{$pattern} = [$ext, $type, $desc];
1112 } 1188 }
1113 } elsif (/^#:META:BINDING:(.*)/) {
1114 my ($keysym, $action) = split /:/, $1;
1115 $ext{binding}{$keysym} = $action;
1116 } elsif (/^\s*(?:#|$)/) { 1189 } elsif (/^\s*(?:#|$)/) {
1117 # skip other comments and empty lines 1190 # skip other comments and empty lines
1118 } else { 1191 } else {
1119 last; # stop parsing on first non-empty non-comment line 1192 last; # stop parsing on first non-empty non-comment line
1120 } 1193 }
1121 } 1194 }
1122 1195
1123 $meta{$ext} = \%ext; 1196 $meta{ext}{$ext} = \%ext;
1124 } 1197 }
1125 } 1198 };
1126 1199
1200# $gather->($_, 0) for @cpandirs;
1201 $gather->($_, 1) for @urxvtdirs;
1202
1127 # and now merge resources and bindings 1203 # and now merge resources
1204
1205 $meta{resource} = \my %resource;
1206
1128 while (my ($k, $v) = each %ext) { 1207 while (my ($k, $v) = each %{ $meta{ext} }) {
1129 #TODO: should check for extensions overriding each other 1208 #TODO: should check for extensions overriding each other
1130 %{ $meta{resource} } = (%{ $meta{resource} }, %{ $v->{resource} }); 1209 %resource = (%resource, %{ $v->{resource} });
1131 %{ $meta{binding} } = (%{ $meta{binding} }, %{ $v->{binding} });
1132 } 1210 }
1133} 1211}
1134 1212
1135=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1213=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1136 1214
1252Returns the X-Resource for the given pattern, excluding the program or 1330Returns the X-Resource for the given pattern, excluding the program or
1253class name, i.e. C<< $term->x_resource ("boldFont") >> should return the 1331class 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 1332same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1255resource with that pattern exists. 1333resource with that pattern exists.
1256 1334
1257Extensions that define extra resource or command line arguments also need 1335Extensions that define extra resources also need to call this method
1258to call this method to access their values. 1336to access their values.
1259 1337
1260If the method is called on an extension object (basically, from an 1338If the method is called on an extension object (basically, from an
1261extension), then the special prefix C<%.> will be replaced by the name of 1339extension), 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 1340the 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 1341extension name itself. This makes it possible to code extensions so you
1264can rename them and get a new set of commandline switches and resources 1342can rename them and get a new set of resources without having to change
1265without having to change the actual code. 1343the actual code.
1266 1344
1267This method should only be called during the C<on_start> hook, as there is 1345This 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 1346only one resource database per display, and later invocations might return
1269the wrong resources. 1347the wrong resources.
1270 1348
1282 my $res = &x_resource; 1360 my $res = &x_resource;
1283 1361
1284 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0 1362 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1285} 1363}
1286 1364
1365=item $action = $term->lookup_keysym ($keysym, $state)
1366
1367Returns the action bound to key combination C<($keysym, $state)>,
1368if a binding for it exists, and C<undef> otherwise.
1369
1287=item $success = $term->bind_action ($key, $octets) 1370=item $success = $term->bind_action ($key, $action)
1288 1371
1289Adds a key binding exactly as specified via a C<keysym> resource. See the 1372Adds a key binding exactly as specified via a C<keysym> resource. See the
1290C<keysym> resource in the urxvt(1) manpage. 1373C<keysym> resource in the urxvt(1) manpage.
1374
1375To add default bindings for actions, an extension should call C<<
1376->bind_action >> in its C<init> hook for every such binding. Doing it
1377in the C<init> hook allows users to override or remove the binding
1378again.
1379
1380Example: the C<searchable-scrollback> by default binds itself
1381on C<Meta-s>, using C<< $self->bind_action >>, which calls C<<
1382$term->bind_action >>.
1383
1384 sub init {
1385 my ($self) = @_;
1386
1387 $self->bind_action ("M-s" => "%:start");
1388 }
1291 1389
1292=item $rend = $term->rstyle ([$new_rstyle]) 1390=item $rend = $term->rstyle ([$new_rstyle])
1293 1391
1294Return and optionally change the current rendition. Text that is output by 1392Return and optionally change the current rendition. Text that is output by
1295the terminal application will use this style. 1393the terminal application will use this style.
1453 1551
1454=item $term->scr_add_lines ($string) 1552=item $term->scr_add_lines ($string)
1455 1553
1456Write the given text string to the screen, as if output by the application 1554Write the given text string to the screen, as if output by the application
1457running inside the terminal. It may not contain command sequences (escape 1555running inside the terminal. It may not contain command sequences (escape
1458codes), but is free to use line feeds, carriage returns and tabs. The 1556codes - see C<cmd_parse> for that), but is free to use line feeds,
1459string is a normal text string, not in locale-dependent encoding. 1557carriage returns and tabs. The string is a normal text string, not in
1558locale-dependent encoding.
1460 1559
1461Normally its not a good idea to use this function, as programs might be 1560Normally 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 1561confused by changes in cursor position or scrolling. Its useful inside a
1463C<on_add_lines> hook, though. 1562C<on_add_lines> hook, though.
1464 1563
1472locale-specific encoding of the terminal and can contain command sequences 1571locale-specific encoding of the terminal and can contain command sequences
1473(escape codes) that will be interpreted. 1572(escape codes) that will be interpreted.
1474 1573
1475=item $term->tt_write ($octets) 1574=item $term->tt_write ($octets)
1476 1575
1477Write the octets given in C<$octets> to the tty (i.e. as program input). To 1576Write the octets given in C<$octets> to the tty (i.e. as user input
1577to the program, see C<cmd_parse> for the opposite direction). To pass
1478pass characters instead of octets, you should convert your strings first 1578characters instead of octets, you should convert your strings first to the
1479to the locale-specific encoding using C<< $term->locale_encode >>. 1579locale-specific encoding using C<< $term->locale_encode >>.
1480 1580
1481=item $term->tt_write_user_input ($octets) 1581=item $term->tt_write_user_input ($octets)
1482 1582
1483Like C<tt_write>, but should be used when writing strings in response to 1583Like 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 1584the user pressing a key, to invoke the additional actions requested by
1485the user for that case (C<tt_write> doesn't do that). 1585the user for that case (C<tt_write> doesn't do that).
1486 1586
1487The typical use case would be inside C<on_action> hooks. 1587The typical use case would be inside C<on_action> hooks.
1488 1588
1489=item $term->tt_paste ($octets) 1589=item $term->tt_paste ($octets)
1531 1631
1532=item $term->key_release ($state, $keycode[, $time]) 1632=item $term->key_release ($state, $keycode[, $time])
1533 1633
1534Deliver various fake events to to terminal. 1634Deliver various fake events to to terminal.
1535 1635
1536=item $window_width = $term->width 1636=item $window_width = $term->width ([$new_value])
1537 1637
1538=item $window_height = $term->height 1638=item $window_height = $term->height ([$new_value])
1539 1639
1540=item $font_width = $term->fwidth 1640=item $font_width = $term->fwidth ([$new_value])
1541 1641
1542=item $font_height = $term->fheight 1642=item $font_height = $term->fheight ([$new_value])
1543 1643
1544=item $font_ascent = $term->fbase 1644=item $font_ascent = $term->fbase ([$new_value])
1545 1645
1546=item $terminal_rows = $term->nrow 1646=item $terminal_rows = $term->nrow ([$new_value])
1547 1647
1548=item $terminal_columns = $term->ncol 1648=item $terminal_columns = $term->ncol ([$new_value])
1549 1649
1550=item $has_focus = $term->focus 1650=item $has_focus = $term->focus ([$new_value])
1551 1651
1552=item $is_mapped = $term->mapped 1652=item $is_mapped = $term->mapped ([$new_value])
1553 1653
1554=item $max_scrollback = $term->saveLines 1654=item $max_scrollback = $term->saveLines ([$new_value])
1555 1655
1556=item $nrow_plus_saveLines = $term->total_rows 1656=item $nrow_plus_saveLines = $term->total_rows ([$new_value])
1557 1657
1558=item $topmost_scrollback_row = $term->top_row 1658=item $topmost_scrollback_row = $term->top_row ([$new_value])
1559 1659
1560Return various integers describing terminal characteristics. 1660Return various integers describing terminal characteristics. If an
1661argument is given, changes the value and returns the previous one.
1561 1662
1562=item $x_display = $term->display_id 1663=item $x_display = $term->display_id
1563 1664
1564Return the DISPLAY used by rxvt-unicode. 1665Return the DISPLAY used by rxvt-unicode.
1565 1666
1601Returns the currently displayed screen (0 primary, 1 secondary). 1702Returns the currently displayed screen (0 primary, 1 secondary).
1602 1703
1603=item $cursor_is_hidden = $term->hidden_cursor 1704=item $cursor_is_hidden = $term->hidden_cursor
1604 1705
1605Returns whether the cursor is currently hidden or not. 1706Returns whether the cursor is currently hidden or not.
1707
1708=item $priv_modes = $term->priv_modes
1709
1710Returns a bitset with the state of DEC private modes.
1711
1712Example:
1713
1714 if ($term->priv_modes & urxvt::PrivMode_mouse_report) {
1715 # mouse reporting is turned on
1716 }
1606 1717
1607=item $view_start = $term->view_start ([$newvalue]) 1718=item $view_start = $term->view_start ([$newvalue])
1608 1719
1609Returns the row number of the topmost displayed line. Maximum value is 1720Returns the row number of the topmost displayed line. Maximum value is
1610C<0>, which displays the normal terminal contents. Lower values scroll 1721C<0>, which displays the normal terminal contents. Lower values scroll
1615Requests a screen refresh. At the next opportunity, rxvt-unicode will 1726Requests a screen refresh. At the next opportunity, rxvt-unicode will
1616compare the on-screen display with its stored representation. If they 1727compare the on-screen display with its stored representation. If they
1617differ, it redraws the differences. 1728differ, it redraws the differences.
1618 1729
1619Used after changing terminal contents to display them. 1730Used after changing terminal contents to display them.
1731
1732=item $term->refresh_check
1733
1734Checks if a refresh has been requested and, if so, schedules one.
1620 1735
1621=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1736=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1622 1737
1623Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >> 1738Returns 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 1739is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines