… | |
… | |
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" |
|
|
191 | Displays a digital clock using the built-in overlay. |
|
|
192 | .IP "example-refresh-hooks" 4 |
|
|
193 | .IX Item "example-refresh-hooks" |
191 | Displays a very simple digital clock in the upper right corner of the |
194 | Displays a very simple digital clock in the upper right corner of the |
192 | window. Illustrates overwriting the refresh callbacks to create your own |
195 | window. Illustrates overwriting the refresh callbacks to create your own |
193 | overlays or changes. |
196 | overlays or changes. |
194 | .IP "simple-overlay-clock" 4 |
|
|
195 | .IX Item "simple-overlay-clock" |
|
|
196 | Displays 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" |
199 | All objects (such as terminals, time watchers etc.) are typical |
199 | All objects (such as terminals, time watchers etc.) are typical |
200 | reference-to-hash objects. The hash can be used to store anything you |
200 | reference-to-hash objects. The hash can be used to store anything you |
201 | like. All members starting with an underscore (such as \f(CW\*(C`_ptr\*(C'\fR or |
201 | like. All members starting with an underscore (such as \f(CW\*(C`_ptr\*(C'\fR or |
… | |
… | |
315 | Using this function has the advantage that its output ends up in the |
315 | Using this function has the advantage that its output ends up in the |
316 | correct place, e.g. on stderr of the connecting urxvtc client. |
316 | correct 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" |
319 | Returns the \*(L"current time\*(R" (as per the event loop). |
319 | Returns the \*(L"current time\*(R" (as per the event loop). |
|
|
320 | .Sh "\s-1RENDITION\s0" |
|
|
321 | .IX Subsection "RENDITION" |
|
|
322 | Rendition bitsets contain information about colour, font, font styles and |
|
|
323 | similar information for each screen cell. |
|
|
324 | .PP |
|
|
325 | The following \*(L"macros\*(R" deal with changes in rendition sets. You should |
|
|
326 | never just create a bitset, you should always modify an existing one, |
|
|
327 | as they contain important information required for correct operation of |
|
|
328 | rxvt\-unicode. |
|
|
329 | .IP "$rend = urxvt::DEFAULT_RSTYLE" 4 |
|
|
330 | .IX Item "$rend = urxvt::DEFAULT_RSTYLE" |
|
|
331 | Returns the default rendition, as used when the terminal is starting up or |
|
|
332 | being reset. Useful as a base to start when creating renditions. |
|
|
333 | .IP "$rend = urxvt::OVERLAY_RSTYLE" 4 |
|
|
334 | .IX Item "$rend = urxvt::OVERLAY_RSTYLE" |
|
|
335 | Return 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" |
|
|
338 | Return the bit that enabled bold, italic, blink, reverse-video and |
|
|
339 | underline, respectively. To enable such a style, just logically \s-1OR\s0 it into |
|
|
340 | the 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 |
|
|
349 | Return 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 |
|
|
358 | Replace the foreground/background colour in the rendition mask with the |
|
|
359 | specified one. |
|
|
360 | .IP "$value = urxvt::GET_CUSTOM ($rend)" 4 |
|
|
361 | .IX Item "$value = urxvt::GET_CUSTOM ($rend)" |
|
|
362 | Return the \*(L"custom\*(R" value: Every rendition has 5 bits for use by |
|
|
363 | extensions. They can be set and changed as you like and are initially |
|
|
364 | zero. |
|
|
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)" |
|
|
368 | Change 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 |
… | |
… | |
376 | by the next method). |
425 | by 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])" |
380 | Return the current selection text and optionally replace it by \f(CW$newtext\fR. |
429 | Return 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 | # |
384 | Create 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 |
|
|
437 | sub urxvt::term::scr_overlay { |
|
|
438 | die; |
|
|
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]])" |
388 | Create a new (empty) overlay at the given position with the given |
460 | Create a new (empty) overlay at the given position with the given |
389 | width/height. A border will be put around the box. If either \f(CW$x\fR or |
461 | width/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). |
391 | respectively. |
463 | .Sp |
392 | .IP "$term\->scr_overlay_off" 4 |
464 | If \f(CW$border\fR is \f(CW2\fR (default), then a decorative border will be put |
393 | .IX Item "$term->scr_overlay_off" |
465 | around the box. |
394 | Switch 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 |
467 | If 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 |
468 | right/bottom side, respectively. |
397 | .IX Item "$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)" |
469 | .Sp |
398 | Put a single character (specified numerically) at the given overlay |
470 | This method returns an urxvt::overlay object. The overlay will be visible |
399 | position. |
471 | as long as the perl object is referenced. |
|
|
472 | .Sp |
|
|
473 | Currently, 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)" |
403 | Write a string at the given position into the overlay. |
477 | Similar to \f(CW\*(C`$term\->ROW_t\*(C'\fR and \f(CW\*(C`$term\->ROW_r\*(C'\fR in that it puts |
|
|
478 | text in rxvt\-unicode's special encoding and an array of rendition values |
|
|
479 | at 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" |
407 | Returns the number of screen-cells this string would need. Correctly |
483 | Returns the number of screen-cells this string would need. Correctly |
408 | accounts for wide and combining characters. |
484 | accounts for wide and combining characters. |
… | |
… | |
454 | terminal line. The scrollback buffer starts at line \f(CW\*(C`\-1\*(C'\fR and extends to |
530 | terminal line. The scrollback buffer starts at line \f(CW\*(C`\-1\*(C'\fR and extends to |
455 | line \f(CW\*(C`\-$term\->nsaved\*(C'\fR. |
531 | line \f(CW\*(C`\-$term\->nsaved\*(C'\fR. |
456 | .Sp |
532 | .Sp |
457 | If \f(CW$new_text\fR is specified, it will replace characters in the current |
533 | If \f(CW$new_text\fR is specified, it will replace characters in the current |
458 | line, starting at column \f(CW$start_col\fR (default \f(CW0\fR), which is useful |
534 | line, starting at column \f(CW$start_col\fR (default \f(CW0\fR), which is useful |
459 | to replace only parts of a line. The font iindex in the rendition will |
535 | to replace only parts of a line. The font index in the rendition will |
460 | automatically be updated. |
536 | automatically 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 |
463 | than one cell when displayed are padded with urxvt::NOCHAR characters |
539 | than 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 |
… | |
… | |
478 | bitsets. Rendition bitsets contain information about colour, font, font |
554 | bitsets. Rendition bitsets contain information about colour, font, font |
479 | styles and similar information. See also \f(CW\*(C`$term\->ROW_t\*(C'\fR. |
555 | styles and similar information. See also \f(CW\*(C`$term\->ROW_t\*(C'\fR. |
480 | .Sp |
556 | .Sp |
481 | When setting rendition, the font mask will be ignored. |
557 | When setting rendition, the font mask will be ignored. |
482 | .Sp |
558 | .Sp |
483 | See the section on \s-1RENDITION\s0, below. |
559 | See 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])" |
487 | Returns the number of screen cells that are in use (\*(L"the line length\*(R"). If |
563 | Returns the number of screen cells that are in use (\*(L"the line length\*(R"). If |
488 | it is \f(CW\*(C`\-1\*(C'\fR, then the line is part of a multiple-row logical \*(L"line\*(R", which |
564 | it 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" |
499 | Converts rxvt-unicodes text reprsentation into a perl string. See |
575 | Converts 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" |
|
|
503 | Rendition bitsets contain information about colour, font, font styles and |
|
|
504 | similar information for each screen cell. |
|
|
505 | .PP |
|
|
506 | The following \*(L"macros\*(R" deal with changes in rendition sets. You should |
|
|
507 | never just create a bitset, you should always modify an existing one, |
|
|
508 | as they contain important information required for correct operation of |
|
|
509 | rxvt\-unicode. |
|
|
510 | .IP "$rend = urxvt::DEFAULT_RSTYLE" 4 |
|
|
511 | .IX Item "$rend = urxvt::DEFAULT_RSTYLE" |
|
|
512 | Returns the default rendition, as used when the terminal is starting up or |
|
|
513 | being 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" |
517 | This class implements timer watchers/events. Time is represented as a |
580 | This class implements timer watchers/events. Time is represented as a |
518 | fractional number of seconds since the epoch. Example: |
581 | fractional 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" |
535 | Create a new timer object in stopped state. |
595 | Create a new timer object in started state. It is scheduled to fire |
|
|
596 | immediately. |
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) = @_; ... })" |
539 | Set the callback to be called when the timer triggers. |
600 | Set 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 |
… | |
… | |
543 | Return the time this watcher will fire next. |
604 | Return 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)" |
547 | Set the time the event is generated to \f(CW$tstamp\fR. |
608 | Set 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)" |
|
|
612 | Normally (and when \f(CW$interval\fR is \f(CW0\fR), the timer will automatically |
|
|
613 | stop after it has fired once. If \f(CW$interval\fR is non\-zero, then the timer |
|
|
614 | is 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" |
551 | Start the timer. |
618 | Start the timer. |
552 | .ie n .IP "$timer = $timer\->start ($tstamp)" 4 |
619 | .ie n .IP "$timer = $timer\->start ($tstamp)" 4 |