--- rxvt-unicode/src/urxvt.pm 2006/01/03 20:47:36 1.24 +++ rxvt-unicode/src/urxvt.pm 2006/01/06 01:16:58 1.34 @@ -41,8 +41,10 @@ =item selection -Intelligent selection. This etxension tries to be more intelligent when the user -extends selections (double-click). +Intelligent selection. This extension tries to be more intelligent when +the user extends selections (double-click). Right now, it tries to select +urls and complete shell-quoted arguments, which is very convenient, too, +if your F supports C<--quoting-style=shell>. It also offers the following bindable event: @@ -66,6 +68,13 @@ window. Illustrates overwriting the refresh callbacks to create your own overlays or changes. +=item mark-urls + +A not very useful example of filtering all text output to the terminal, by +underlining all urls that matches a certain regex (i.e. some urls :). It +is not very useful because urls that are output in multiple steps (e.g. +when typing them) do not get marked. + =back =head2 General API Considerations @@ -81,6 +90,29 @@ the like inside the terminal object so they get destroyed as soon as the terminal is destroyed. +Argument names also often indicate the type of a parameter. Here are some +hints on what they mean: + +=over 4 + +=item $text + +Rxvt-unicodes special way of encoding text, where one "unicode" character +always represents one screen cell. See L for a discussion of this format. + +=item $string + +A perl text string, with an emphasis on I. It can store all unicode +characters and is to be distinguished with text encoded in a specific +encoding (often locale-specific) and binary data. + +=item $octets + +Either binary data or - more common - a text string encoded in a +locale-specific way. + +=back + =head2 Hooks The following subroutines can be declared in loaded scripts, and will be @@ -172,6 +204,27 @@ Called whenever the program(s) running in the urxvt window send output. +=item on_osc_seq $term, $string + +Called whenever the B command sequence (OSC = +operating system command) is processed. Cursor position and other state +information is up-to-date when this happens. For interoperability, the +string should start with the extension name and a colon, to distinguish +it from commands for other extensions, and this might be enforced in the +future. + +Be careful not ever to trust (in a security sense) the data you receive, +as its source can not easily be controleld (e-mail content, messages from +other users on the same system etc.). + +=item on_add_lines $term, $string + +Called whenever text is about to be output, with the text as argument. You +can filter/change and output the text yourself by returning a true value +and calling C<< $term->scr_add_lines >> yourself. Please note that this +might be very slow, however, as your hook is called for B text being +output. + =item on_refresh_begin $term Called just before the screen gets redrawn. Can be used for overlay @@ -353,6 +406,8 @@ } } +our $retval; # return value for urxvt + # called by the rxvt core sub invoke { local $TERM = shift; @@ -361,7 +416,7 @@ if ($htype == 0) { # INIT my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); - for my $ext (split /:/, $TERM->resource ("perl_ext")) { + for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { my @files = grep -f $_, map "$_/$ext", @dirs; if (@files) { @@ -370,35 +425,45 @@ warn "perl extension '$ext' not found in perl library search path\n"; } } + } + + $retval = undef; + + if (my $cb = $TERM->{_hook}[$htype]) { + verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" + if $verbosity >= 10; + + keys %$cb; + + while (my ($pkg, $cb) = each %$cb) { + $retval = $cb->( + $TERM->{_pkg}{$pkg} ||= do { + my $proxy = bless { }, urxvt::term::proxy::; + Scalar::Util::weaken ($proxy->{term} = $TERM); + $proxy + }, + @_, + ) and last; + } + } - } elsif ($htype == 1) { # DESTROY + if ($htype == 1) { # DESTROY + # remove hooks if unused if (my $hook = $TERM->{_hook}) { for my $htype (0..$#$hook) { $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } or set_should_invoke $htype, 0; } } - } - - my $cb = $TERM->{_hook}[$htype] - or return; - verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" - if $verbosity >= 10; + # clear package objects + %$_ = () for values %{ $TERM->{_pkg} }; - while (my ($pkg, $cb) = each %$cb) { - return 1 - if $cb->( - $TERM->{$pkg} ||= do { - my $proxy = bless { }, urxvt::term::proxy::; - Scalar::Util::weaken ($proxy->{term} = $TERM); - $proxy - }, - @_, - ); + # clear package + %$TERM = (); } - 0 + $retval } sub urxvt::term::proxy::AUTOLOAD { @@ -446,7 +511,7 @@ display_name embed ext_bwidth fade font geometry hold iconName imFont imLocale inputMethod insecure int_bwidth intensityStyles italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier - mouseWheelScrollPage name pastableTabs path perl_eval perl_ext + mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput @@ -462,6 +527,16 @@ goto &urxvt::term::_resource; } +=item $rend = $term->rstyle ([$new_rstyle]) + +Return and optionally change the current rendition. Text that is output by +the terminal application will use this style. + +=item ($row, $col) = $term->screen_cur ([$row, $col]) + +Return the current coordinates of the text cursor position and optionally +set it (which is usually bad as applications don't expect that). + =item ($row, $col) = $term->selection_mark ([$row, $col]) =item ($row, $col) = $term->selection_beg ([$row, $col]) @@ -485,21 +560,20 @@ #Create a simple multi-line overlay box. See the next method for details. # #=cut - -sub urxvt::term::scr_overlay { -die; - my ($self, $x, $y, $text) = @_; - - my @lines = split /\n/, $text; - - my $w = 0; - for (map $self->strwidth ($_), @lines) { - $w = $_ if $w < $_; - } - - $self->scr_overlay_new ($x, $y, $w, scalar @lines); - $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; -} +# +#sub urxvt::term::scr_overlay { +# my ($self, $x, $y, $text) = @_; +# +# my @lines = split /\n/, $text; +# +# my $w = 0; +# for (map $self->strwidth ($_), @lines) { +# $w = $_ if $w < $_; +# } +# +# $self->scr_overlay_new ($x, $y, $w, scalar @lines); +# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; +#} =item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) @@ -549,22 +623,48 @@ Convert the given locale-encoded octets into a perl string. +=item $term->scr_add_lines ($string) + +Write the given text string to the screen, as if output by the application +running inside the terminal. It may not contain command sequences (escape +codes), but is free to use line feeds, carriage returns and tabs. The +string is a normal text string, not in locale-dependent encoding. + +Normally its not a good idea to use this function, as programs might be +confused by changes in cursor position or scrolling. Its useful inside a +C hook, though. + =item $term->tt_write ($octets) Write the octets given in C<$data> to the tty (i.e. as program input). To pass characters instead of octets, you should convert your strings first to the locale-specific encoding using C<< $term->locale_encode >>. -=item $nrow = $term->nrow +=item $window_width = $term->width + +=item $window_height = $term->height + +=item $font_width = $term->fwidth + +=item $font_height = $term->fheight + +=item $font_ascent = $term->fbase + +=item $terminal_rows = $term->nrow -=item $ncol = $term->ncol +=item $terminal_columns = $term->ncol -Return the number of rows/columns of the terminal window (i.e. as -specified by C<-geometry>, excluding any scrollback). +=item $has_focus = $term->focus -=item $nsaved = $term->nsaved +=item $is_mapped = $term->mapped -Returns the number of lines in the scrollback buffer. +=item $max_scrollback = $term->saveLines + +=item $nrow_plus_saveLines = $term->total_rows + +=item $lines_in_scrollback = $term->nsaved + +Return various integers describing terminal characteristics. =item $view_start = $term->view_start ([$newvalue]) @@ -682,6 +782,7 @@ term => $self, beg => $beg, end => $end, + ncol => $self->ncol, len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), }, urxvt::line:: } @@ -689,18 +790,35 @@ sub urxvt::line::t { my ($self) = @_; - substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), - 0, $self->{len} + if (@_ > 1) + { + $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) + for $self->{beg} .. $self->{end}; + } + + defined wantarray && + substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), + 0, $self->{len} } sub urxvt::line::r { my ($self) = @_; - my $rend = [ - map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} - ]; - $#$rend = $self->{len} - 1; - $rend + if (@_ > 1) + { + $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) + for $self->{beg} .. $self->{end}; + } + + if (defined wantarray) { + my $rend = [ + map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} + ]; + $#$rend = $self->{len} - 1; + return $rend; + } + + () } sub urxvt::line::beg { $_[0]{beg} } @@ -710,7 +828,7 @@ sub urxvt::line::offset_of { my ($self, $row, $col) = @_; - ($row - $self->{beg}) * $self->{term}->ncol + $col + ($row - $self->{beg}) * $self->{ncol} + $col } sub urxvt::line::coord_of { @@ -719,8 +837,8 @@ use integer; ( - $offset / $self->{term}->ncol + $self->{beg}, - $offset % $self->{term}->ncol + $offset / $self->{ncol} + $self->{beg}, + $offset % $self->{ncol} ) } @@ -848,11 +966,11 @@ =over 4 -=item 0 - only fatal messages +=item =0 - only fatal messages -=item 3 - script loading and management +=item =3 - script loading and management -=item 10 - all events received +=item =10 - all events received =back