… | |
… | |
18 | <ul> |
18 | <ul> |
19 | |
19 | |
20 | <li><a href="#prepackaged_extensions">Prepackaged Extensions</a></li> |
20 | <li><a href="#prepackaged_extensions">Prepackaged Extensions</a></li> |
21 | <li><a href="#general_api_considerations">General API Considerations</a></li> |
21 | <li><a href="#general_api_considerations">General API Considerations</a></li> |
22 | <li><a href="#hooks">Hooks</a></li> |
22 | <li><a href="#hooks">Hooks</a></li> |
|
|
23 | <li><a href="#variables_in_the_urxvt_package">Variables in the <code>urxvt</code> Package</a></li> |
23 | <li><a href="#functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></li> |
24 | <li><a href="#functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></li> |
24 | <li><a href="#rendition">RENDITION</a></li> |
25 | <li><a href="#rendition">RENDITION</a></li> |
25 | <li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li> |
26 | <li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li> |
26 | <li><a href="#the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></li> |
27 | <li><a href="#the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></li> |
27 | <li><a href="#the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></li> |
28 | <li><a href="#the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></li> |
… | |
… | |
78 | rxvt -pe <extensionname></pre> |
79 | rxvt -pe <extensionname></pre> |
79 | <dl> |
80 | <dl> |
80 | <dt><strong><a name="item_selection">selection</a></strong><br /> |
81 | <dt><strong><a name="item_selection">selection</a></strong><br /> |
81 | </dt> |
82 | </dt> |
82 | <dd> |
83 | <dd> |
83 | Miscellaneous selection modifications. |
84 | Intelligent selection. This etxension tries to be more intelligent when the user |
|
|
85 | extends selections (double-click). |
|
|
86 | </dd> |
|
|
87 | <dd> |
|
|
88 | <p>It also offers the following bindable event:</p> |
84 | </dd> |
89 | </dd> |
85 | <dl> |
90 | <dl> |
86 | <dt><strong><a name="item_rot13">rot13</a></strong><br /> |
91 | <dt><strong><a name="item_rot13">rot13</a></strong><br /> |
87 | </dt> |
92 | </dt> |
88 | <dd> |
93 | <dd> |
… | |
… | |
111 | </p> |
116 | </p> |
112 | <h2><a name="general_api_considerations">General API Considerations</a></h2> |
117 | <h2><a name="general_api_considerations">General API Considerations</a></h2> |
113 | <p>All objects (such as terminals, time watchers etc.) are typical |
118 | <p>All objects (such as terminals, time watchers etc.) are typical |
114 | reference-to-hash objects. The hash can be used to store anything you |
119 | reference-to-hash objects. The hash can be used to store anything you |
115 | like. All members starting with an underscore (such as <code>_ptr</code> or |
120 | like. All members starting with an underscore (such as <code>_ptr</code> or |
116 | <code>_hook</code>) are reserved for internal uses and must not be accessed or |
121 | <code>_hook</code>) are reserved for internal uses and <strong>MUST NOT</strong> be accessed or |
117 | modified).</p> |
122 | modified).</p> |
118 | <p>When objects are destroyed on the C++ side, the perl object hashes are |
123 | <p>When objects are destroyed on the C++ side, the perl object hashes are |
119 | emptied, so its best to store related objects such as time watchers and |
124 | emptied, so its best to store related objects such as time watchers and |
120 | the like inside the terminal object so they get destroyed as soon as the |
125 | the like inside the terminal object so they get destroyed as soon as the |
121 | terminal is destroyed.</p> |
126 | terminal is destroyed.</p> |
122 | <p> |
127 | <p> |
123 | </p> |
128 | </p> |
124 | <h2><a name="hooks">Hooks</a></h2> |
129 | <h2><a name="hooks">Hooks</a></h2> |
125 | <p>The following subroutines can be declared in loaded scripts, and will be called |
130 | <p>The following subroutines can be declared in loaded scripts, and will be |
126 | whenever the relevant event happens.</p> |
131 | called whenever the relevant event happens.</p> |
|
|
132 | <p>The first argument passed to them is an object private to each terminal |
|
|
133 | and extension package. You can call all <code>urxvt::term</code> methods on it, but |
|
|
134 | its not a real <code>urxvt::term</code> object. Instead, the real <code>urxvt::term</code> |
|
|
135 | object that is shared between all packages is stored in the <code>term</code> |
|
|
136 | member.</p> |
127 | <p>All of them must return a boolean value. If it is true, then the event |
137 | <p>All of them must return a boolean value. If it is true, then the event |
128 | counts as being <em>consumed</em>, and the invocation of other hooks is skipped, |
138 | counts as being <em>consumed</em>, and the invocation of other hooks is skipped, |
129 | and the relevant action might not be carried out by the C++ code.</p> |
139 | and the relevant action might not be carried out by the C++ code.</p> |
130 | <p>When in doubt, return a false value (preferably <code>()</code>).</p> |
140 | <p>When in doubt, return a false value (preferably <code>()</code>).</p> |
131 | <dl> |
141 | <dl> |
… | |
… | |
172 | </dd> |
182 | </dd> |
173 | <dd> |
183 | <dd> |
174 | <p>Returning a true value aborts selection grabbing. It will still be hilighted.</p> |
184 | <p>Returning a true value aborts selection grabbing. It will still be hilighted.</p> |
175 | </dd> |
185 | </dd> |
176 | <p></p> |
186 | <p></p> |
|
|
187 | <dt><strong><a name="item_on_sel_extend__24term">on_sel_extend $term</a></strong><br /> |
|
|
188 | </dt> |
|
|
189 | <dd> |
|
|
190 | Called whenever the user tries to extend the selection (e.g. with a double |
|
|
191 | click) and is either supposed to return false (normal operation), or |
|
|
192 | should extend the selection itelf and return true to suppress the built-in |
|
|
193 | processing. |
|
|
194 | </dd> |
|
|
195 | <dd> |
|
|
196 | <p>See the <em>selection</em> example extension.</p> |
|
|
197 | </dd> |
|
|
198 | <p></p> |
177 | <dt><strong><a name="item_on_focus_in__24term">on_focus_in $term</a></strong><br /> |
199 | <dt><strong><a name="item_on_focus_in__24term">on_focus_in $term</a></strong><br /> |
178 | </dt> |
200 | </dt> |
179 | <dd> |
201 | <dd> |
180 | Called whenever the window gets the keyboard focus, before urxvt does |
202 | Called whenever the window gets the keyboard focus, before urxvt does |
181 | focus in processing. |
203 | focus in processing. |
… | |
… | |
234 | </dt> |
256 | </dt> |
235 | <dd> |
257 | <dd> |
236 | Called whenever the user presses a key combination that has a |
258 | Called whenever the user presses a key combination that has a |
237 | <code>perl:string</code> action bound to it (see description of the <strong>keysym</strong> |
259 | <code>perl:string</code> action bound to it (see description of the <strong>keysym</strong> |
238 | resource in the <code>rxvt(1)</code> manpage). |
260 | resource in the <code>rxvt(1)</code> manpage). |
|
|
261 | </dd> |
|
|
262 | <p></p></dl> |
|
|
263 | <p> |
|
|
264 | </p> |
|
|
265 | <h2><a name="variables_in_the_urxvt_package">Variables in the <code>urxvt</code> Package</a></h2> |
|
|
266 | <dl> |
|
|
267 | <dt><strong><a name="item__24urxvt_3a_3aterm">$urxvt::TERM</a></strong><br /> |
|
|
268 | </dt> |
|
|
269 | <dd> |
|
|
270 | The current terminal. Whenever a callback/Hook is bein executed, this |
|
|
271 | variable stores the current <code>urxvt::term</code> object. |
239 | </dd> |
272 | </dd> |
240 | <p></p></dl> |
273 | <p></p></dl> |
241 | <p> |
274 | <p> |
242 | </p> |
275 | </p> |
243 | <h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2> |
276 | <h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2> |
… | |
… | |
447 | <dd> |
480 | <dd> |
448 | <p>This method returns an urxvt::overlay object. The overlay will be visible |
481 | <p>This method returns an urxvt::overlay object. The overlay will be visible |
449 | as long as the perl object is referenced.</p> |
482 | as long as the perl object is referenced.</p> |
450 | </dd> |
483 | </dd> |
451 | <dd> |
484 | <dd> |
452 | <p>Currently, the only method on the <code>urxvt::overlay</code> object is <a href="#item_set"><code>set</code></a>:</p> |
485 | <p>The methods currently supported on <code>urxvt::overlay</code> objects are:</p> |
453 | </dd> |
486 | </dd> |
454 | <p></p> |
487 | <dl> |
455 | <dt><strong><a name="item_set">$overlay->set ($x, $y, $text, $rend)</a></strong><br /> |
488 | <dt><strong><a name="item_set">$overlay->set ($x, $y, $text, $rend)</a></strong><br /> |
456 | </dt> |
489 | </dt> |
457 | <dd> |
490 | <dd> |
458 | Similar to <a href="#item_row_t"><code>$term->ROW_t</code></a> and <a href="#item_row_r"><code>$term->ROW_r</code></a> in that it puts |
491 | Similar to <a href="#item_row_t"><code>$term->ROW_t</code></a> and <a href="#item_row_r"><code>$term->ROW_r</code></a> in that it puts |
459 | text in rxvt-unicode's special encoding and an array of rendition values |
492 | text in rxvt-unicode's special encoding and an array of rendition values |
460 | at a specific position inside the overlay. |
493 | at a specific position inside the overlay. |
461 | </dd> |
494 | </dd> |
462 | <p></p> |
495 | <p></p> |
|
|
496 | <dt><strong><a name="item_hide">$overlay->hide</a></strong><br /> |
|
|
497 | </dt> |
|
|
498 | <dd> |
|
|
499 | If visible, hide the overlay, but do not destroy it. |
|
|
500 | </dd> |
|
|
501 | <p></p> |
|
|
502 | <dt><strong><a name="item_show">$overlay->show</a></strong><br /> |
|
|
503 | </dt> |
|
|
504 | <dd> |
|
|
505 | If hidden, display the overlay again. |
|
|
506 | </dd> |
|
|
507 | <p></p></dl> |
463 | <dt><strong><a name="item_strwidth">$cellwidth = $term->strwidth $string</a></strong><br /> |
508 | <dt><strong><a name="item_strwidth">$cellwidth = $term->strwidth $string</a></strong><br /> |
464 | </dt> |
509 | </dt> |
465 | <dd> |
510 | <dd> |
466 | Returns the number of screen-cells this string would need. Correctly |
511 | Returns the number of screen-cells this string would need. Correctly |
467 | accounts for wide and combining characters. |
512 | accounts for wide and combining characters. |
… | |
… | |
525 | </dt> |
570 | </dt> |
526 | <dd> |
571 | <dd> |
527 | Returns the text of the entire row with number <code>$row_number</code>. Row <code>0</code> |
572 | Returns the text of the entire row with number <code>$row_number</code>. Row <code>0</code> |
528 | is the topmost terminal line, row <code>$term->$ncol-1</code> is the bottommost |
573 | is the topmost terminal line, row <code>$term->$ncol-1</code> is the bottommost |
529 | terminal line. The scrollback buffer starts at line <code>-1</code> and extends to |
574 | terminal line. The scrollback buffer starts at line <code>-1</code> and extends to |
530 | line <a href="#item_nsaved"><code>-$term->nsaved</code></a>. |
575 | line <a href="#item_nsaved"><code>-$term->nsaved</code></a>. Nothing will be returned if a nonexistent line |
|
|
576 | is requested. |
531 | </dd> |
577 | </dd> |
532 | <dd> |
578 | <dd> |
533 | <p>If <code>$new_text</code> is specified, it will replace characters in the current |
579 | <p>If <code>$new_text</code> is specified, it will replace characters in the current |
534 | line, starting at column <code>$start_col</code> (default <code>0</code>), which is useful |
580 | line, starting at column <code>$start_col</code> (default <code>0</code>), which is useful |
535 | to replace only parts of a line. The font index in the rendition will |
581 | to replace only parts of a line. The font index in the rendition will |
… | |
… | |
546 | <p>You have to obey this encoding when changing text. The advantage is |
592 | <p>You have to obey this encoding when changing text. The advantage is |
547 | that <code>substr</code> and similar functions work on screen cells and not on |
593 | that <code>substr</code> and similar functions work on screen cells and not on |
548 | characters.</p> |
594 | characters.</p> |
549 | </dd> |
595 | </dd> |
550 | <dd> |
596 | <dd> |
551 | <p>The methods <a href="#item_special_encode"><code>$term->special_encode</code></a> and <a href="#item_special_decode"><code>$term->special_decode</code></a> |
597 | <p>The methods <code>$term->special_encode</code> and <a href="#item_special_decode"><code>$term->special_decode</code></a> |
552 | can be used to convert normal strings into this encoding and vice versa.</p> |
598 | can be used to convert normal strings into this encoding and vice versa.</p> |
553 | </dd> |
599 | </dd> |
554 | <p></p> |
600 | <p></p> |
555 | <dt><strong><a name="item_row_r">$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])</a></strong><br /> |
601 | <dt><strong><a name="item_row_r">$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])</a></strong><br /> |
556 | </dt> |
602 | </dt> |
… | |
… | |
567 | </dd> |
613 | </dd> |
568 | <p></p> |
614 | <p></p> |
569 | <dt><strong><a name="item_row_l">$length = $term->ROW_l ($row_number[, $new_length])</a></strong><br /> |
615 | <dt><strong><a name="item_row_l">$length = $term->ROW_l ($row_number[, $new_length])</a></strong><br /> |
570 | </dt> |
616 | </dt> |
571 | <dd> |
617 | <dd> |
572 | Returns the number of screen cells that are in use (``the line length''). If |
618 | Returns the number of screen cells that are in use (``the line |
573 | it is <code>-1</code>, then the line is part of a multiple-row logical ``line'', which |
619 | length''). Unlike the urxvt core, this returns <a href="#item_ncol"><code>$term->ncol</code></a> if the |
574 | means all characters are in use and it is continued on the next row. |
620 | line is joined with the following one. |
|
|
621 | </dd> |
|
|
622 | <p></p> |
|
|
623 | <dt><strong><a name="item_is_longer">$bool = $term->is_longer ($row_number)</a></strong><br /> |
|
|
624 | </dt> |
575 | </dd> |
625 | <dd> |
|
|
626 | Returns true if the row is part of a multiple-row logical ``line'' (i.e. |
|
|
627 | joined with the following row), which means all characters are in use |
|
|
628 | and it is continued on the next row (and possibly a continuation of the |
|
|
629 | previous row(s)). |
|
|
630 | </dd> |
576 | <p></p> |
631 | <p></p> |
|
|
632 | <dt><strong><a name="item_line">$line = $term->line ($row_number)</a></strong><br /> |
|
|
633 | </dt> |
|
|
634 | <dd> |
|
|
635 | Create and return a new <code>urxvt::line</code> object that stores information |
|
|
636 | about the logical line that row <code>$row_number</code> is part of. It supports the |
|
|
637 | following methods: |
|
|
638 | </dd> |
|
|
639 | <dl> |
577 | <dt><strong><a name="item_special_encode">$text = $term->special_encode $string</a></strong><br /> |
640 | <dt><strong><a name="item_t">$text = $line->t</a></strong><br /> |
|
|
641 | </dt> |
|
|
642 | <dd> |
|
|
643 | Returns the full text of the line, similar to <a href="#item_row_t"><code>ROW_t</code></a> |
|
|
644 | </dd> |
|
|
645 | <p></p> |
|
|
646 | <dt><strong><a name="item_r">$rend = $line->r</a></strong><br /> |
|
|
647 | </dt> |
|
|
648 | <dd> |
|
|
649 | Returns the full rendition array of the line, similar to <a href="#item_row_r"><code>ROW_r</code></a> |
|
|
650 | </dd> |
|
|
651 | <p></p> |
|
|
652 | <dt><strong><a name="item_l">$length = $line->l</a></strong><br /> |
|
|
653 | </dt> |
|
|
654 | <dd> |
|
|
655 | Returns the length of the line in cells, similar to <a href="#item_row_l"><code>ROW_l</code></a>. |
|
|
656 | </dd> |
|
|
657 | <p></p> |
|
|
658 | <dt><strong><a name="item_beg">$rownum = $line->beg</a></strong><br /> |
|
|
659 | </dt> |
|
|
660 | <dt><strong><a name="item_end">$rownum = $line->end</a></strong><br /> |
|
|
661 | </dt> |
|
|
662 | <dd> |
|
|
663 | Return the row number of the first/last row of the line, respectively. |
|
|
664 | </dd> |
|
|
665 | <p></p> |
|
|
666 | <dt><strong><a name="item_offset_of">$offset = $line->offset_of ($row, $col)</a></strong><br /> |
|
|
667 | </dt> |
|
|
668 | <dd> |
|
|
669 | Returns the character offset of the given row|col pair within the logical |
|
|
670 | line. |
|
|
671 | </dd> |
|
|
672 | <p></p> |
|
|
673 | <dt><strong><a name="item_coord_of">($row, $col) = $line->coord_of ($offset)</a></strong><br /> |
|
|
674 | </dt> |
|
|
675 | <dd> |
|
|
676 | Translates a string offset into terminal coordinates again. |
|
|
677 | </dd> |
|
|
678 | <p></p></dl> |
|
|
679 | <dt><strong>($row, $col) = $line->coord_of ($offset) |
|
|
680 | =item $text = $term->special_encode $string</strong><br /> |
578 | </dt> |
681 | </dt> |
579 | <dd> |
682 | <dd> |
580 | Converts a perl string into the special encoding used by rxvt-unicode, |
683 | Converts a perl string into the special encoding used by rxvt-unicode, |
581 | where one character corresponds to one screen cell. See |
684 | where one character corresponds to one screen cell. See |
582 | <a href="#item_row_t"><code>$term->ROW_t</code></a> for details. |
685 | <a href="#item_row_t"><code>$term->ROW_t</code></a> for details. |