ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.man.in
(Generate patch)

Comparing rxvt-unicode/doc/rxvtperl.3.man.in (file contents):
Revision 1.7 by root, Tue Jan 3 01:45:12 2006 UTC vs.
Revision 1.8 by root, Tue Jan 3 04:20:37 2006 UTC

… …
186.RE 186.RE
187.RS 4 187.RS 4
188.RE 188.RE
189.IP "digital-clock" 4 189.IP "digital-clock" 4
190.IX Item "digital-clock" 190.IX Item "digital-clock"
191Displays a digital clock using the built-in overlay.
192.IP "example-refresh-hooks" 4
193.IX Item "example-refresh-hooks"
191Displays a very simple digital clock in the upper right corner of the 194Displays a very simple digital clock in the upper right corner of the
192window. Illustrates overwriting the refresh callbacks to create your own 195window. Illustrates overwriting the refresh callbacks to create your own
193overlays or changes. 196overlays or changes.
194.IP "simple-overlay-clock" 4
195.IX Item "simple-overlay-clock"
196Displays a digital clock using the built-in overlay (colorful, useless).
197.Sh "General \s-1API\s0 Considerations" 197.Sh "General \s-1API\s0 Considerations"
198.IX Subsection "General API Considerations" 198.IX Subsection "General API Considerations"
199All objects (such as terminals, time watchers etc.) are typical 199All objects (such as terminals, time watchers etc.) are typical
200reference-to-hash objects. The hash can be used to store anything you 200reference-to-hash objects. The hash can be used to store anything you
201like. All members starting with an underscore (such as \f(CW\*(C`_ptr\*(C'\fR or 201like. All members starting with an underscore (such as \f(CW\*(C`_ptr\*(C'\fR or
… …
315Using this function has the advantage that its output ends up in the 315Using this function has the advantage that its output ends up in the
316correct place, e.g. on stderr of the connecting urxvtc client. 316correct place, e.g. on stderr of the connecting urxvtc client.
317.IP "$time = urxvt::NOW" 4 317.IP "$time = urxvt::NOW" 4
318.IX Item "$time = urxvt::NOW" 318.IX Item "$time = urxvt::NOW"
319Returns the \*(L"current time\*(R" (as per the event loop). 319Returns the \*(L"current time\*(R" (as per the event loop).
320.Sh "\s-1RENDITION\s0"
321.IX Subsection "RENDITION"
322Rendition bitsets contain information about colour, font, font styles and
323similar information for each screen cell.
324.PP
325The following \*(L"macros\*(R" deal with changes in rendition sets. You should
326never just create a bitset, you should always modify an existing one,
327as they contain important information required for correct operation of
328rxvt\-unicode.
329.IP "$rend = urxvt::DEFAULT_RSTYLE" 4
330.IX Item "$rend = urxvt::DEFAULT_RSTYLE"
331Returns the default rendition, as used when the terminal is starting up or
332being reset. Useful as a base to start when creating renditions.
333.IP "$rend = urxvt::OVERLAY_RSTYLE" 4
334.IX Item "$rend = urxvt::OVERLAY_RSTYLE"
335Return the rendition mask used for overlays by default.
336.IP "$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline" 4
337.IX Item "$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline"
338Return the bit that enabled bold, italic, blink, reverse-video and
339underline, respectively. To enable such a style, just logically \s-1OR\s0 it into
340the bitset.
341.ie n .IP "$foreground = urxvt::GET_BASEFG $rend" 4
342.el .IP "$foreground = urxvt::GET_BASEFG \f(CW$rend\fR" 4
343.IX Item "$foreground = urxvt::GET_BASEFG $rend"
344.PD 0
345.ie n .IP "$background = urxvt::GET_BASEBG $rend" 4
346.el .IP "$background = urxvt::GET_BASEBG \f(CW$rend\fR" 4
347.IX Item "$background = urxvt::GET_BASEBG $rend"
348.PD
349Return the foreground/background colour index, respectively.
350.ie n .IP "$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)" 4
351.el .IP "$rend = urxvt::SET_FGCOLOR ($rend, \f(CW$new_colour\fR)" 4
352.IX Item "$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)"
353.PD 0
354.ie n .IP "$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)" 4
355.el .IP "$rend = urxvt::SET_BGCOLOR ($rend, \f(CW$new_colour\fR)" 4
356.IX Item "$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)"
357.PD
358Replace the foreground/background colour in the rendition mask with the
359specified one.
360.IP "$value = urxvt::GET_CUSTOM ($rend)" 4
361.IX Item "$value = urxvt::GET_CUSTOM ($rend)"
362Return the \*(L"custom\*(R" value: Every rendition has 5 bits for use by
363extensions. They can be set and changed as you like and are initially
364zero.
365.ie n .IP "$rend = urxvt::SET_CUSTOM ($rend, $new_value)" 4
366.el .IP "$rend = urxvt::SET_CUSTOM ($rend, \f(CW$new_value\fR)" 4
367.IX Item "$rend = urxvt::SET_CUSTOM ($rend, $new_value)"
368Change the custom value.
320.ie n .Sh "The ""urxvt::term"" Class" 369.ie n .Sh "The ""urxvt::term"" Class"
321.el .Sh "The \f(CWurxvt::term\fP Class" 370.el .Sh "The \f(CWurxvt::term\fP Class"
322.IX Subsection "The urxvt::term Class" 371.IX Subsection "The urxvt::term Class"
323.ie n .IP "$value = $term\fR\->resource ($name[, \f(CW$newval])" 4 372.ie n .IP "$value = $term\fR\->resource ($name[, \f(CW$newval])" 4
324.el .IP "$value = \f(CW$term\fR\->resource ($name[, \f(CW$newval\fR])" 4 373.el .IP "$value = \f(CW$term\fR\->resource ($name[, \f(CW$newval\fR])" 4
… …
376by the next method). 425by the next method).
377.ie n .IP "$oldtext = $term\->selection ([$newtext])" 4 426.ie n .IP "$oldtext = $term\->selection ([$newtext])" 4
378.el .IP "$oldtext = \f(CW$term\fR\->selection ([$newtext])" 4 427.el .IP "$oldtext = \f(CW$term\fR\->selection ([$newtext])" 4
379.IX Item "$oldtext = $term->selection ([$newtext])" 428.IX Item "$oldtext = $term->selection ([$newtext])"
380Return the current selection text and optionally replace it by \f(CW$newtext\fR. 429Return the current selection text and optionally replace it by \f(CW$newtext\fR.
381.ie n .IP "$term\->scr_overlay ($x, $y\fR, \f(CW$text)" 4 430.Sp
382.el .IP "$term\->scr_overlay ($x, \f(CW$y\fR, \f(CW$text\fR)" 4 431#=item \f(CW$term\fR\->overlay ($x, \f(CW$y\fR, \f(CW$text\fR)
383.IX Item "$term->scr_overlay ($x, $y, $text)" 432#
384Create a simple multi-line overlay box. See the next method for details. 433#Create a simple multi-line overlay box. See the next method for details.
434#
435#=cut
436.Sp
437sub urxvt::term::scr_overlay {
438die;
439 my ($self, \f(CW$x\fR, \f(CW$y\fR, \f(CW$text\fR) = \f(CW@_\fR;
440.Sp
441.Vb 1
442\& my @lines = split /\en/, $text;
443.Ve
444.Sp
445.Vb 4
446\& my $w = 0;
447\& for (map $self->strwidth ($_), @lines) {
448\& $w = $_ if $w < $_;
449\& }
450.Ve
451.Sp
452.Vb 3
453\& $self->scr_overlay_new ($x, $y, $w, scalar @lines);
454\& $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
455\&}
456.Ve
385.ie n .IP "$term\->scr_overlay_new ($x, $y\fR, \f(CW$width\fR, \f(CW$height)" 4 457.ie n .IP "$term\->overlay ($x, $y\fR, \f(CW$width\fR, \f(CW$height\fR[, \f(CW$rstyle\fR[, \f(CW$border]])" 4
386.el .IP "$term\->scr_overlay_new ($x, \f(CW$y\fR, \f(CW$width\fR, \f(CW$height\fR)" 4 458.el .IP "$term\->overlay ($x, \f(CW$y\fR, \f(CW$width\fR, \f(CW$height\fR[, \f(CW$rstyle\fR[, \f(CW$border\fR]])" 4
387.IX Item "$term->scr_overlay_new ($x, $y, $width, $height)" 459.IX Item "$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])"
388Create a new (empty) overlay at the given position with the given 460Create a new (empty) overlay at the given position with the given
389width/height. A border will be put around the box. If either \f(CW$x\fR or 461width/height. \f(CW$rstyle\fR defines the initial rendition style
390\&\f(CW$y\fR is negative, then this is counted from the right/bottom side, 462(default: \f(CW\*(C`OVERLAY_RSTYLE\*(C'\fR).
391respectively. 463.Sp
392.IP "$term\->scr_overlay_off" 4 464If \f(CW$border\fR is \f(CW2\fR (default), then a decorative border will be put
393.IX Item "$term->scr_overlay_off" 465around the box.
394Switch the overlay off again. 466.Sp
395.ie n .IP "$term\->scr_overlay_set_char ($x, $y\fR, \f(CW$char\fR, \f(CW$rend = \s-1OVERLAY_RSTYLE\s0)" 4 467If either \f(CW$x\fR or \f(CW$y\fR is negative, then this is counted from the
396.el .IP "$term\->scr_overlay_set_char ($x, \f(CW$y\fR, \f(CW$char\fR, \f(CW$rend\fR = \s-1OVERLAY_RSTYLE\s0)" 4 468right/bottom side, respectively.
397.IX Item "$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)" 469.Sp
398Put a single character (specified numerically) at the given overlay 470This method returns an urxvt::overlay object. The overlay will be visible
399position. 471as long as the perl object is referenced.
472.Sp
473Currently, the only method on the \f(CW\*(C`urxvt::overlay\*(C'\fR object is \f(CW\*(C`set\*(C'\fR:
400.ie n .IP "$term\->scr_overlay_set ($x, $y\fR, \f(CW$text)" 4 474.ie n .IP "$overlay\->set ($x, $y\fR, \f(CW$text\fR, \f(CW$rend)" 4
401.el .IP "$term\->scr_overlay_set ($x, \f(CW$y\fR, \f(CW$text\fR)" 4 475.el .IP "$overlay\->set ($x, \f(CW$y\fR, \f(CW$text\fR, \f(CW$rend\fR)" 4
402.IX Item "$term->scr_overlay_set ($x, $y, $text)" 476.IX Item "$overlay->set ($x, $y, $text, $rend)"
403Write a string at the given position into the overlay. 477Similar to \f(CW\*(C`$term\->ROW_t\*(C'\fR and \f(CW\*(C`$term\->ROW_r\*(C'\fR in that it puts
478text in rxvt\-unicode's special encoding and an array of rendition values
479at a specific position inside the overlay.
404.ie n .IP "$cellwidth = $term\fR\->strwidth \f(CW$string" 4 480.ie n .IP "$cellwidth = $term\fR\->strwidth \f(CW$string" 4
405.el .IP "$cellwidth = \f(CW$term\fR\->strwidth \f(CW$string\fR" 4 481.el .IP "$cellwidth = \f(CW$term\fR\->strwidth \f(CW$string\fR" 4
406.IX Item "$cellwidth = $term->strwidth $string" 482.IX Item "$cellwidth = $term->strwidth $string"
407Returns the number of screen-cells this string would need. Correctly 483Returns the number of screen-cells this string would need. Correctly
408accounts for wide and combining characters. 484accounts for wide and combining characters.
… …
454terminal line. The scrollback buffer starts at line \f(CW\*(C`\-1\*(C'\fR and extends to 530terminal line. The scrollback buffer starts at line \f(CW\*(C`\-1\*(C'\fR and extends to
455line \f(CW\*(C`\-$term\->nsaved\*(C'\fR. 531line \f(CW\*(C`\-$term\->nsaved\*(C'\fR.
456.Sp 532.Sp
457If \f(CW$new_text\fR is specified, it will replace characters in the current 533If \f(CW$new_text\fR is specified, it will replace characters in the current
458line, starting at column \f(CW$start_col\fR (default \f(CW0\fR), which is useful 534line, starting at column \f(CW$start_col\fR (default \f(CW0\fR), which is useful
459to replace only parts of a line. The font iindex in the rendition will 535to replace only parts of a line. The font index in the rendition will
460automatically be updated. 536automatically be updated.
461.Sp 537.Sp
462\&\f(CW$text\fR is in a special encoding: tabs and wide characters that use more 538\&\f(CW$text\fR is in a special encoding: tabs and wide characters that use more
463than one cell when displayed are padded with urxvt::NOCHAR characters 539than one cell when displayed are padded with urxvt::NOCHAR characters
464(\f(CW\*(C`chr 65535\*(C'\fR). Characters with combining characters and other characters 540(\f(CW\*(C`chr 65535\*(C'\fR). Characters with combining characters and other characters
… …
478bitsets. Rendition bitsets contain information about colour, font, font 554bitsets. Rendition bitsets contain information about colour, font, font
479styles and similar information. See also \f(CW\*(C`$term\->ROW_t\*(C'\fR. 555styles and similar information. See also \f(CW\*(C`$term\->ROW_t\*(C'\fR.
480.Sp 556.Sp
481When setting rendition, the font mask will be ignored. 557When setting rendition, the font mask will be ignored.
482.Sp 558.Sp
483See the section on \s-1RENDITION\s0, below. 559See the section on \s-1RENDITION\s0, above.
484.ie n .IP "$length = $term\fR\->ROW_l ($row_number[, \f(CW$new_length])" 4 560.ie n .IP "$length = $term\fR\->ROW_l ($row_number[, \f(CW$new_length])" 4
485.el .IP "$length = \f(CW$term\fR\->ROW_l ($row_number[, \f(CW$new_length\fR])" 4 561.el .IP "$length = \f(CW$term\fR\->ROW_l ($row_number[, \f(CW$new_length\fR])" 4
486.IX Item "$length = $term->ROW_l ($row_number[, $new_length])" 562.IX Item "$length = $term->ROW_l ($row_number[, $new_length])"
487Returns the number of screen cells that are in use (\*(L"the line length\*(R"). If 563Returns the number of screen cells that are in use (\*(L"the line length\*(R"). If
488it is \f(CW\*(C`\-1\*(C'\fR, then the line is part of a multiple-row logical \*(L"line\*(R", which 564it is \f(CW\*(C`\-1\*(C'\fR, then the line is part of a multiple-row logical \*(L"line\*(R", which
… …
496.ie n .IP "$string = $term\fR\->special_decode \f(CW$text" 4 572.ie n .IP "$string = $term\fR\->special_decode \f(CW$text" 4
497.el .IP "$string = \f(CW$term\fR\->special_decode \f(CW$text\fR" 4 573.el .IP "$string = \f(CW$term\fR\->special_decode \f(CW$text\fR" 4
498.IX Item "$string = $term->special_decode $text" 574.IX Item "$string = $term->special_decode $text"
499Converts rxvt-unicodes text reprsentation into a perl string. See 575Converts rxvt-unicodes text reprsentation into a perl string. See
500\&\f(CW\*(C`$term\->ROW_t\*(C'\fR for details. 576\&\f(CW\*(C`$term\->ROW_t\*(C'\fR for details.
501.Sh "\s-1RENDITION\s0"
502.IX Subsection "RENDITION"
503Rendition bitsets contain information about colour, font, font styles and
504similar information for each screen cell.
505.PP
506The following \*(L"macros\*(R" deal with changes in rendition sets. You should
507never just create a bitset, you should always modify an existing one,
508as they contain important information required for correct operation of
509rxvt\-unicode.
510.IP "$rend = urxvt::DEFAULT_RSTYLE" 4
511.IX Item "$rend = urxvt::DEFAULT_RSTYLE"
512Returns the default rendition, as used when the terminal is starting up or
513being reset. Useful as a base
514.ie n .Sh "The ""urxvt::timer"" Class" 577.ie n .Sh "The ""urxvt::timer"" Class"
515.el .Sh "The \f(CWurxvt::timer\fP Class" 578.el .Sh "The \f(CWurxvt::timer\fP Class"
516.IX Subsection "The urxvt::timer Class" 579.IX Subsection "The urxvt::timer Class"
517This class implements timer watchers/events. Time is represented as a 580This class implements timer watchers/events. Time is represented as a
518fractional number of seconds since the epoch. Example: 581fractional number of seconds since the epoch. Example:
519.PP 582.PP
520.Vb 11 583.Vb 8
521\& # create a digital clock display in upper right corner 584\& $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
522\& $term->{timer} = urxvt::timer 585\& $term->{timer} = urxvt::timer
523\& ->new 586\& ->new
524\& ->start (urxvt::NOW) 587\& ->interval (1)
525\& ->cb (sub { 588\& ->cb (sub {
526\& my ($timer) = @_;
527\& my $time = $timer->at;
528\& $timer->start ($time + 1);
529\& $self->scr_overlay (-1, 0, 589\& $term->{overlay}->set (0, 0,
530\& POSIX::strftime "%H:%M:%S", localtime $time); 590\& sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
531\& }); 591\& });
532.Ve 592.Ve
533.IP "$timer = new urxvt::timer" 4 593.IP "$timer = new urxvt::timer" 4
534.IX Item "$timer = new urxvt::timer" 594.IX Item "$timer = new urxvt::timer"
535Create a new timer object in stopped state. 595Create a new timer object in started state. It is scheduled to fire
596immediately.
536.ie n .IP "$timer = $timer\fR\->cb (sub { my ($timer) = \f(CW@_; ... })" 4 597.ie n .IP "$timer = $timer\fR\->cb (sub { my ($timer) = \f(CW@_; ... })" 4
537.el .IP "$timer = \f(CW$timer\fR\->cb (sub { my ($timer) = \f(CW@_\fR; ... })" 4 598.el .IP "$timer = \f(CW$timer\fR\->cb (sub { my ($timer) = \f(CW@_\fR; ... })" 4
538.IX Item "$timer = $timer->cb (sub { my ($timer) = @_; ... })" 599.IX Item "$timer = $timer->cb (sub { my ($timer) = @_; ... })"
539Set the callback to be called when the timer triggers. 600Set the callback to be called when the timer triggers.
540.ie n .IP "$tstamp = $timer\->at" 4 601.ie n .IP "$tstamp = $timer\->at" 4
… …
543Return the time this watcher will fire next. 604Return the time this watcher will fire next.
544.ie n .IP "$timer = $timer\->set ($tstamp)" 4 605.ie n .IP "$timer = $timer\->set ($tstamp)" 4
545.el .IP "$timer = \f(CW$timer\fR\->set ($tstamp)" 4 606.el .IP "$timer = \f(CW$timer\fR\->set ($tstamp)" 4
546.IX Item "$timer = $timer->set ($tstamp)" 607.IX Item "$timer = $timer->set ($tstamp)"
547Set the time the event is generated to \f(CW$tstamp\fR. 608Set the time the event is generated to \f(CW$tstamp\fR.
609.ie n .IP "$timer = $timer\->interval ($interval)" 4
610.el .IP "$timer = \f(CW$timer\fR\->interval ($interval)" 4
611.IX Item "$timer = $timer->interval ($interval)"
612Normally (and when \f(CW$interval\fR is \f(CW0\fR), the timer will automatically
613stop after it has fired once. If \f(CW$interval\fR is non\-zero, then the timer
614is automatically rescheduled at the given intervals.
548.ie n .IP "$timer = $timer\->start" 4 615.ie n .IP "$timer = $timer\->start" 4
549.el .IP "$timer = \f(CW$timer\fR\->start" 4 616.el .IP "$timer = \f(CW$timer\fR\->start" 4
550.IX Item "$timer = $timer->start" 617.IX Item "$timer = $timer->start"
551Start the timer. 618Start the timer.
552.ie n .IP "$timer = $timer\->start ($tstamp)" 4 619.ie n .IP "$timer = $timer\->start ($tstamp)" 4

Diff Legend

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