… | |
… | |
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 extension tries to be more intelligent when |
|
|
85 | the user extends selections (double-click). Right now, it tries to select |
|
|
86 | urls and complete shell-quoted arguments, which is very convenient, too, |
|
|
87 | if your <em>ls</em> supports <code>--quoting-style=shell</code>. |
|
|
88 | </dd> |
|
|
89 | <dd> |
|
|
90 | <p>It also offers the following bindable event:</p> |
84 | </dd> |
91 | </dd> |
85 | <dl> |
92 | <dl> |
86 | <dt><strong><a name="item_rot13">rot13</a></strong><br /> |
93 | <dt><strong><a name="item_rot13">rot13</a></strong><br /> |
87 | </dt> |
94 | </dt> |
88 | <dd> |
95 | <dd> |
… | |
… | |
111 | </p> |
118 | </p> |
112 | <h2><a name="general_api_considerations">General API Considerations</a></h2> |
119 | <h2><a name="general_api_considerations">General API Considerations</a></h2> |
113 | <p>All objects (such as terminals, time watchers etc.) are typical |
120 | <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 |
121 | 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 |
122 | 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 |
123 | <code>_hook</code>) are reserved for internal uses and <strong>MUST NOT</strong> be accessed or |
117 | modified).</p> |
124 | modified).</p> |
118 | <p>When objects are destroyed on the C++ side, the perl object hashes are |
125 | <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 |
126 | 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 |
127 | the like inside the terminal object so they get destroyed as soon as the |
121 | terminal is destroyed.</p> |
128 | terminal is destroyed.</p> |
122 | <p> |
129 | <p> |
123 | </p> |
130 | </p> |
124 | <h2><a name="hooks">Hooks</a></h2> |
131 | <h2><a name="hooks">Hooks</a></h2> |
125 | <p>The following subroutines can be declared in loaded scripts, and will be called |
132 | <p>The following subroutines can be declared in loaded scripts, and will be |
126 | whenever the relevant event happens.</p> |
133 | called whenever the relevant event happens.</p> |
|
|
134 | <p>The first argument passed to them is an object private to each terminal |
|
|
135 | and extension package. You can call all <code>urxvt::term</code> methods on it, but |
|
|
136 | its not a real <code>urxvt::term</code> object. Instead, the real <code>urxvt::term</code> |
|
|
137 | object that is shared between all packages is stored in the <code>term</code> |
|
|
138 | member.</p> |
127 | <p>All of them must return a boolean value. If it is true, then the event |
139 | <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, |
140 | 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> |
141 | 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> |
142 | <p>When in doubt, return a false value (preferably <code>()</code>).</p> |
131 | <dl> |
143 | <dl> |
… | |
… | |
172 | </dd> |
184 | </dd> |
173 | <dd> |
185 | <dd> |
174 | <p>Returning a true value aborts selection grabbing. It will still be hilighted.</p> |
186 | <p>Returning a true value aborts selection grabbing. It will still be hilighted.</p> |
175 | </dd> |
187 | </dd> |
176 | <p></p> |
188 | <p></p> |
|
|
189 | <dt><strong><a name="item_on_sel_extend__24term">on_sel_extend $term</a></strong><br /> |
|
|
190 | </dt> |
|
|
191 | <dd> |
|
|
192 | Called whenever the user tries to extend the selection (e.g. with a double |
|
|
193 | click) and is either supposed to return false (normal operation), or |
|
|
194 | should extend the selection itelf and return true to suppress the built-in |
|
|
195 | processing. |
|
|
196 | </dd> |
|
|
197 | <dd> |
|
|
198 | <p>See the <em>selection</em> example extension.</p> |
|
|
199 | </dd> |
|
|
200 | <p></p> |
177 | <dt><strong><a name="item_on_focus_in__24term">on_focus_in $term</a></strong><br /> |
201 | <dt><strong><a name="item_on_focus_in__24term">on_focus_in $term</a></strong><br /> |
178 | </dt> |
202 | </dt> |
179 | <dd> |
203 | <dd> |
180 | Called whenever the window gets the keyboard focus, before urxvt does |
204 | Called whenever the window gets the keyboard focus, before urxvt does |
181 | focus in processing. |
205 | focus in processing. |
… | |
… | |
211 | <p></p> |
235 | <p></p> |
212 | <dt><strong><a name="item_on_tty_activity__24term__2anyi_2a">on_tty_activity $term *NYI*</a></strong><br /> |
236 | <dt><strong><a name="item_on_tty_activity__24term__2anyi_2a">on_tty_activity $term *NYI*</a></strong><br /> |
213 | </dt> |
237 | </dt> |
214 | <dd> |
238 | <dd> |
215 | Called whenever the <code>program(s)</code> running in the urxvt window send output. |
239 | Called whenever the <code>program(s)</code> running in the urxvt window send output. |
|
|
240 | </dd> |
|
|
241 | <p></p> |
|
|
242 | <dt><strong><a name="item_on_osc_seq__24term_2c__24string">on_osc_seq $term, $string</a></strong><br /> |
|
|
243 | </dt> |
|
|
244 | <dd> |
|
|
245 | Called whenever the <strong>ESC ] 777 ; string ST</strong> command sequence (OSC = |
|
|
246 | operating system command) is processed. Cursor position and other state |
|
|
247 | information is up-to-date when this happens. For interoperability, the |
|
|
248 | string should start with the extension name and a colon, to distinguish |
|
|
249 | it from commands for other extensions, and this might be enforced in the |
|
|
250 | future. |
|
|
251 | </dd> |
|
|
252 | <dd> |
|
|
253 | <p>Be careful not ever to trust (in a security sense) the data you receive, |
|
|
254 | as its source can not easily be controleld (e-mail content, messages from |
|
|
255 | other users on the same system etc.).</p> |
216 | </dd> |
256 | </dd> |
217 | <p></p> |
257 | <p></p> |
218 | <dt><strong><a name="item_on_refresh_begin__24term">on_refresh_begin $term</a></strong><br /> |
258 | <dt><strong><a name="item_on_refresh_begin__24term">on_refresh_begin $term</a></strong><br /> |
219 | </dt> |
259 | </dt> |
220 | <dd> |
260 | <dd> |
… | |
… | |
234 | </dt> |
274 | </dt> |
235 | <dd> |
275 | <dd> |
236 | Called whenever the user presses a key combination that has a |
276 | 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> |
277 | <code>perl:string</code> action bound to it (see description of the <strong>keysym</strong> |
238 | resource in the <code>rxvt(1)</code> manpage). |
278 | resource in the <code>rxvt(1)</code> manpage). |
|
|
279 | </dd> |
|
|
280 | <p></p></dl> |
|
|
281 | <p> |
|
|
282 | </p> |
|
|
283 | <h2><a name="variables_in_the_urxvt_package">Variables in the <code>urxvt</code> Package</a></h2> |
|
|
284 | <dl> |
|
|
285 | <dt><strong><a name="item__24urxvt_3a_3aterm">$urxvt::TERM</a></strong><br /> |
|
|
286 | </dt> |
|
|
287 | <dd> |
|
|
288 | The current terminal. Whenever a callback/Hook is bein executed, this |
|
|
289 | variable stores the current <code>urxvt::term</code> object. |
239 | </dd> |
290 | </dd> |
240 | <p></p></dl> |
291 | <p></p></dl> |
241 | <p> |
292 | <p> |
242 | </p> |
293 | </p> |
243 | <h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2> |
294 | <h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2> |
… | |
… | |
447 | <dd> |
498 | <dd> |
448 | <p>This method returns an urxvt::overlay object. The overlay will be visible |
499 | <p>This method returns an urxvt::overlay object. The overlay will be visible |
449 | as long as the perl object is referenced.</p> |
500 | as long as the perl object is referenced.</p> |
450 | </dd> |
501 | </dd> |
451 | <dd> |
502 | <dd> |
452 | <p>Currently, the only method on the <code>urxvt::overlay</code> object is <a href="#item_set"><code>set</code></a>:</p> |
503 | <p>The methods currently supported on <code>urxvt::overlay</code> objects are:</p> |
453 | </dd> |
504 | </dd> |
454 | <p></p> |
505 | <dl> |
455 | <dt><strong><a name="item_set">$overlay->set ($x, $y, $text, $rend)</a></strong><br /> |
506 | <dt><strong><a name="item_set">$overlay->set ($x, $y, $text, $rend)</a></strong><br /> |
456 | </dt> |
507 | </dt> |
457 | <dd> |
508 | <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 |
509 | 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 |
510 | text in rxvt-unicode's special encoding and an array of rendition values |
460 | at a specific position inside the overlay. |
511 | at a specific position inside the overlay. |
461 | </dd> |
512 | </dd> |
462 | <p></p> |
513 | <p></p> |
|
|
514 | <dt><strong><a name="item_hide">$overlay->hide</a></strong><br /> |
|
|
515 | </dt> |
|
|
516 | <dd> |
|
|
517 | If visible, hide the overlay, but do not destroy it. |
|
|
518 | </dd> |
|
|
519 | <p></p> |
|
|
520 | <dt><strong><a name="item_show">$overlay->show</a></strong><br /> |
|
|
521 | </dt> |
|
|
522 | <dd> |
|
|
523 | If hidden, display the overlay again. |
|
|
524 | </dd> |
|
|
525 | <p></p></dl> |
463 | <dt><strong><a name="item_strwidth">$cellwidth = $term->strwidth $string</a></strong><br /> |
526 | <dt><strong><a name="item_strwidth">$cellwidth = $term->strwidth $string</a></strong><br /> |
464 | </dt> |
527 | </dt> |
465 | <dd> |
528 | <dd> |
466 | Returns the number of screen-cells this string would need. Correctly |
529 | Returns the number of screen-cells this string would need. Correctly |
467 | accounts for wide and combining characters. |
530 | accounts for wide and combining characters. |
… | |
… | |
525 | </dt> |
588 | </dt> |
526 | <dd> |
589 | <dd> |
527 | Returns the text of the entire row with number <code>$row_number</code>. Row <code>0</code> |
590 | 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 |
591 | 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 |
592 | 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>. |
593 | line <a href="#item_nsaved"><code>-$term->nsaved</code></a>. Nothing will be returned if a nonexistent line |
|
|
594 | is requested. |
531 | </dd> |
595 | </dd> |
532 | <dd> |
596 | <dd> |
533 | <p>If <code>$new_text</code> is specified, it will replace characters in the current |
597 | <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 |
598 | 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 |
599 | 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 |
610 | <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 |
611 | that <code>substr</code> and similar functions work on screen cells and not on |
548 | characters.</p> |
612 | characters.</p> |
549 | </dd> |
613 | </dd> |
550 | <dd> |
614 | <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> |
615 | <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> |
616 | can be used to convert normal strings into this encoding and vice versa.</p> |
553 | </dd> |
617 | </dd> |
554 | <p></p> |
618 | <p></p> |
555 | <dt><strong><a name="item_row_r">$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])</a></strong><br /> |
619 | <dt><strong><a name="item_row_r">$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])</a></strong><br /> |
556 | </dt> |
620 | </dt> |
… | |
… | |
567 | </dd> |
631 | </dd> |
568 | <p></p> |
632 | <p></p> |
569 | <dt><strong><a name="item_row_l">$length = $term->ROW_l ($row_number[, $new_length])</a></strong><br /> |
633 | <dt><strong><a name="item_row_l">$length = $term->ROW_l ($row_number[, $new_length])</a></strong><br /> |
570 | </dt> |
634 | </dt> |
571 | <dd> |
635 | <dd> |
572 | Returns the number of screen cells that are in use (``the line length''). If |
636 | 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 |
637 | 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. |
638 | line is joined with the following one. |
|
|
639 | </dd> |
|
|
640 | <p></p> |
|
|
641 | <dt><strong><a name="item_is_longer">$bool = $term->is_longer ($row_number)</a></strong><br /> |
|
|
642 | </dt> |
575 | </dd> |
643 | <dd> |
|
|
644 | Returns true if the row is part of a multiple-row logical ``line'' (i.e. |
|
|
645 | joined with the following row), which means all characters are in use |
|
|
646 | and it is continued on the next row (and possibly a continuation of the |
|
|
647 | previous row(s)). |
|
|
648 | </dd> |
576 | <p></p> |
649 | <p></p> |
|
|
650 | <dt><strong><a name="item_line">$line = $term->line ($row_number)</a></strong><br /> |
|
|
651 | </dt> |
|
|
652 | <dd> |
|
|
653 | Create and return a new <code>urxvt::line</code> object that stores information |
|
|
654 | about the logical line that row <code>$row_number</code> is part of. It supports the |
|
|
655 | following methods: |
|
|
656 | </dd> |
|
|
657 | <dl> |
577 | <dt><strong><a name="item_special_encode">$text = $term->special_encode $string</a></strong><br /> |
658 | <dt><strong><a name="item_t">$text = $line->t</a></strong><br /> |
|
|
659 | </dt> |
|
|
660 | <dd> |
|
|
661 | Returns the full text of the line, similar to <a href="#item_row_t"><code>ROW_t</code></a> |
|
|
662 | </dd> |
|
|
663 | <p></p> |
|
|
664 | <dt><strong><a name="item_r">$rend = $line->r</a></strong><br /> |
|
|
665 | </dt> |
|
|
666 | <dd> |
|
|
667 | Returns the full rendition array of the line, similar to <a href="#item_row_r"><code>ROW_r</code></a> |
|
|
668 | </dd> |
|
|
669 | <p></p> |
|
|
670 | <dt><strong><a name="item_l">$length = $line->l</a></strong><br /> |
|
|
671 | </dt> |
|
|
672 | <dd> |
|
|
673 | Returns the length of the line in cells, similar to <a href="#item_row_l"><code>ROW_l</code></a>. |
|
|
674 | </dd> |
|
|
675 | <p></p> |
|
|
676 | <dt><strong><a name="item_beg">$rownum = $line->beg</a></strong><br /> |
|
|
677 | </dt> |
|
|
678 | <dt><strong><a name="item_end">$rownum = $line->end</a></strong><br /> |
|
|
679 | </dt> |
|
|
680 | <dd> |
|
|
681 | Return the row number of the first/last row of the line, respectively. |
|
|
682 | </dd> |
|
|
683 | <p></p> |
|
|
684 | <dt><strong><a name="item_offset_of">$offset = $line->offset_of ($row, $col)</a></strong><br /> |
|
|
685 | </dt> |
|
|
686 | <dd> |
|
|
687 | Returns the character offset of the given row|col pair within the logical |
|
|
688 | line. |
|
|
689 | </dd> |
|
|
690 | <p></p> |
|
|
691 | <dt><strong><a name="item_coord_of">($row, $col) = $line->coord_of ($offset)</a></strong><br /> |
|
|
692 | </dt> |
|
|
693 | <dd> |
|
|
694 | Translates a string offset into terminal coordinates again. |
|
|
695 | </dd> |
|
|
696 | <p></p></dl> |
|
|
697 | <dt><strong>($row, $col) = $line->coord_of ($offset) |
|
|
698 | =item $text = $term->special_encode $string</strong><br /> |
578 | </dt> |
699 | </dt> |
579 | <dd> |
700 | <dd> |
580 | Converts a perl string into the special encoding used by rxvt-unicode, |
701 | Converts a perl string into the special encoding used by rxvt-unicode, |
581 | where one character corresponds to one screen cell. See |
702 | where one character corresponds to one screen cell. See |
582 | <a href="#item_row_t"><code>$term->ROW_t</code></a> for details. |
703 | <a href="#item_row_t"><code>$term->ROW_t</code></a> for details. |
… | |
… | |
718 | <p> |
839 | <p> |
719 | </p> |
840 | </p> |
720 | <h2><a name="urxvt_perl_verbosity">URXVT_PERL_VERBOSITY</a></h2> |
841 | <h2><a name="urxvt_perl_verbosity">URXVT_PERL_VERBOSITY</a></h2> |
721 | <p>This variable controls the verbosity level of the perl extension. Higher |
842 | <p>This variable controls the verbosity level of the perl extension. Higher |
722 | numbers indicate more verbose output.</p> |
843 | numbers indicate more verbose output.</p> |
723 | <ol> |
844 | <dl> |
724 | <li><strong><a name="item__2d_only_fatal_messages">- only fatal messages</a></strong><br /> |
845 | <dt><strong><a name="item__3d0__2d_only_fatal_messages">=0 - only fatal messages</a></strong><br /> |
725 | </li> |
846 | </dt> |
726 | <li><strong><a name="item__2d_script_loading_and_management">- script loading and management</a></strong><br /> |
847 | <dt><strong><a name="item__3d3__2d_script_loading_and_management">=3 - script loading and management</a></strong><br /> |
727 | </li> |
848 | </dt> |
728 | <li><strong><a name="item__2d_all_events_received">- all events received</a></strong><br /> |
849 | <dt><strong><a name="item__3d10__2d_all_events_received">=10 - all events received</a></strong><br /> |
|
|
850 | </dt> |
729 | </li> |
851 | </dl> |
730 | </ol> |
|
|
731 | <p> |
852 | <p> |
732 | </p> |
853 | </p> |
733 | <hr /> |
854 | <hr /> |
734 | <h1><a name="author">AUTHOR</a></h1> |
855 | <h1><a name="author">AUTHOR</a></h1> |
735 | <pre> |
856 | <pre> |