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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.4 by root, Tue Jan 3 01:39:56 2006 UTC vs.
Revision 1.26 by root, Fri Jan 13 01:09:37 2006 UTC

12 # start a rxvt using it: 12 # start a rxvt using it:
13 13
14 rxvt --perl-lib $HOME -pe grab_test 14 rxvt --perl-lib $HOME -pe grab_test
15 15
16DESCRIPTION 16DESCRIPTION
17 Everytime a terminal object gets created, scripts specified via the 17 Everytime a terminal object gets created, extension scripts specified
18 "perl" resource are loaded and associated with it. 18 via the "perl" resource are loaded and associated with it.
19 19
20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and 20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21 thus must be encoded as UTF-8. 21 thus must be encoded as UTF-8.
22 22
23 Each script will only ever be loaded once, even in rxvtd, where scripts 23 Each script will only ever be loaded once, even in rxvtd, where scripts
24 will be shared (But not enabled) for all terminals. 24 will be shared (but not enabled) for all terminals.
25 25
26PACKAGED EXTENSIONS 26PREPACKAGED EXTENSIONS
27 This section describes the extensiosn delivered with this version. You 27 This section describes the extensions delivered with this release. You
28 can find them in /opt/rxvt/lib/urxvt/perl/. 28 can find them in /opt/rxvt/lib/urxvt/perl/.
29 29
30 You can activate them like this: 30 You can activate them like this:
31 31
32 rxvt -pe <extensionname> 32 rxvt -pe <extensionname>
33 33
34 selection 34 selection (enabled by default)
35 Miscellaneous selection modifications. 35 (More) intelligent selection. This extension tries to be more
36 intelligent when the user extends selections (double-click and
37 further clicks). Right now, it tries to select words, urls and
38 complete shell-quoted arguments, which is very convenient, too, if
39 your ls supports "--quoting-style=shell".
40
41 A double-click usually selects the word under the cursor, further
42 clicks will enlarge the selection.
43
44 The selection works by trying to match a number of regexes and
45 displaying them in increasing order of length. You can add your own
46 regexes by specifying resources of the form:
47
48 URxvt.selection.pattern-0: perl-regex
49 URxvt.selection.pattern-1: perl-regex
50 ...
51
52 The index number (0, 1...) must not have any holes, and each regex
53 must contain at least one pair of capturing parentheses, which will
54 be used for the match. For example, the followign adds a regex that
55 matches everything between two vertical bars:
56
57 URxvt.selection.pattern-0: \\|([^|]+)\\|
58
59 You can look at the source of the selection extension to see more
60 interesting uses, such as parsing a line from beginning to end.
61
62 This extension also offers the following bindable keyboard command:
36 63
37 rot13 64 rot13
38 Rot-13 the selection when activated. Used via keyboard trigger: 65 Rot-13 the selection when activated. Used via keyboard trigger:
39 66
40 URxvt.keysym.C-M-r: perl:selection:rot13 67 URxvt.keysym.C-M-r: perl:selection:rot13
41 68
69 option-popup (enabled by default)
70 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
71 options at runtime.
72
73 selection-popup (enabled by default)
74 Binds a popup menu to Ctrl-Button3 that lets you convert the
75 selection text into various other formats/action (such as uri
76 unescaping, perl evalution, web-browser starting etc.), depending on
77 content.
78
79 searchable-scrollback<hotkey> (enabled by default)
80 Adds regex search functionality to the scrollback buffer, triggered
81 by a hotkey (default: "M-s"). While in search mode, normal terminal
82 input/output is suspended and a regex is displayed at the bottom of
83 the screen.
84
85 Inputting characters appends them to the regex and continues
86 incremental search. "BackSpace" removes a character from the regex,
87 "Up" and "Down" search upwards/downwards in the scrollback buffer,
88 "End" jumps to the bottom. "Escape" leaves search mode and returns
89 to the point where search was started, while "Enter" or "Return"
90 stay at the current position and additionally stores the first match
91 in the current line into the primary selection.
92
93 selection-autotransform
94 This selection allows you to do automatic transforms on a selection
95 whenever a selection is made.
96
97 It works by specifying perl snippets (most useful is a single "s///"
98 operator) that modify $_ as resources:
99
100 URxvt.selection-autotransform.0: transform
101 URxvt.selection-autotransform.1: transform
102 ...
103
104 For example, the following will transform selections of the form
105 "filename:number", often seen in compiler messages, into "vi
106 +$filename $word":
107
108 URxvt.selection-autotransform.0: s/^(\\S+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
109
110 And this example matches the same,but replaces it with vi-commands
111 you can paste directly into your (vi :) editor:
112
113 URxvt.selection-autotransform.0: s/^(S+):(d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
114
115 Of course, this can be modified to suit your needs and your editor
116 :)
117
118 To expand the example above to typical perl error messages ("XXX at
119 FILENAME line YYY."), you need a slightly more elaborate solution:
120
121 URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
122 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
123
124 The first line tells the selection code to treat the unchanging part
125 of every error message as a selection pattern, and the second line
126 transforms the message into vi commands to load the file.
127
128 mark-urls
129 Uses per-line display filtering ("on_line_update") to underline urls
130 and make them clickable. When middle-clicked, the program specified
131 in the resource "urlLauncher" (default "x-www-browser") will be
132 started with the URL as first argument.
133
134 block-graphics-to-ascii
135 A not very useful example of filtering all text output to the
136 terminal, by replacing all line-drawing characters (U+2500 ..
137 U+259F) by a similar-looking ascii character.
138
42 digital-clock 139 digital-clock
140 Displays a digital clock using the built-in overlay.
141
142 example-refresh-hooks
43 Displays a very simple digital clock in the upper right corner of 143 Displays a very simple digital clock in the upper right corner of
44 the window. Illustrates overwriting the refresh callbacks to create 144 the window. Illustrates overwriting the refresh callbacks to create
45 your own overlays or changes. 145 your own overlays or changes.
46 146
47 simple-overlay-clock 147API DOCUMENTATION
48 Displays a digital clock using the built-in overlay (colorful,
49 useless).
50
51 General API Considerations 148 General API Considerations
52 All objects (such as terminals, time watchers etc.) are typical 149 All objects (such as terminals, time watchers etc.) are typical
53 reference-to-hash objects. The hash can be used to store anything you 150 reference-to-hash objects. The hash can be used to store anything you
54 like. All members starting with an underscore (such as "_ptr" or 151 like. All members starting with an underscore (such as "_ptr" or
55 "_hook") are reserved for internal uses and must not be accessed or 152 "_hook") are reserved for internal uses and MUST NOT be accessed or
56 modified). 153 modified).
57 154
58 When objects are destroyed on the C++ side, the perl object hashes are 155 When objects are destroyed on the C++ side, the perl object hashes are
59 emptied, so its best to store related objects such as time watchers and 156 emptied, so its best to store related objects such as time watchers and
60 the like inside the terminal object so they get destroyed as soon as the 157 the like inside the terminal object so they get destroyed as soon as the
61 terminal is destroyed. 158 terminal is destroyed.
62 159
160 Argument names also often indicate the type of a parameter. Here are
161 some hints on what they mean:
162
163 $text
164 Rxvt-unicodes special way of encoding text, where one "unicode"
165 character always represents one screen cell. See ROW_t for a
166 discussion of this format.
167
168 $string
169 A perl text string, with an emphasis on *text*. It can store all
170 unicode characters and is to be distinguished with text encoded in a
171 specific encoding (often locale-specific) and binary data.
172
173 $octets
174 Either binary data or - more common - a text string encoded in a
175 locale-specific way.
176
177 Extension Objects
178 Very perl extension is a perl class. A separate perl object is created
179 for each terminal and each extension and passed as the first parameter
180 to hooks. So extensions can use their $self object without having to
181 think about other extensions, with the exception of methods and members
182 that begin with an underscore character "_": these are reserved for
183 internal use.
184
185 Although it isn't a "urxvt::term" object, you can call all methods of
186 the "urxvt::term" class on this object.
187
188 It has the following methods and data members:
189
190 $urxvt_term = $self->{term}
191 Returns the "urxvt::term" object associated with this instance of
192 the extension. This member *must not* be changed in any way.
193
194 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
195 Dynamically enable the given hooks (named without the "on_" prefix)
196 for this extension, replacing any previous hook. This is useful when
197 you want to overwrite time-critical hooks only temporarily.
198
199 $self->disable ($hook_name[, $hook_name..])
200 Dynamically disable the given hooks.
201
63 Hooks 202 Hooks
64 The following subroutines can be declared in loaded scripts, and will be 203 The following subroutines can be declared in extension files, and will
65 called whenever the relevant event happens. 204 be called whenever the relevant event happens.
66 205
206 The first argument passed to them is an extension oject as described in
207 the in the "Extension Objects" section.
208
67 All of them must return a boolean value. If it is true, then the event 209 All of these hooks must return a boolean value. If it is true, then the
68 counts as being *consumed*, and the invocation of other hooks is 210 event counts as being *consumed*, and the invocation of other hooks is
69 skipped, and the relevant action might not be carried out by the C++ 211 skipped, and the relevant action might not be carried out by the C++
70 code. 212 code.
71 213
72 When in doubt, return a false value (preferably "()"). 214 *When in doubt, return a false value (preferably "()").*
73 215
74 on_init $term 216 on_init $term
75 Called after a new terminal object has been initialized, but before 217 Called after a new terminal object has been initialized, but before
76 windows are created or the command gets run. 218 windows are created or the command gets run. Most methods are unsafe
219 to call or deliver senseless data, as terminal size and other
220 characteristics have not yet been determined. You can safely query
221 and change resources, though.
77 222
78 on_reset $term 223 on_reset $term
79 Called after the screen is "reset" for any reason, such as resizing 224 Called after the screen is "reset" for any reason, such as resizing
80 or control sequences. Here is where you can react on changes to 225 or control sequences. Here is where you can react on changes to
81 size-related variables. 226 size-related variables.
99 queried and changed by calling "$term->selection". 244 queried and changed by calling "$term->selection".
100 245
101 Returning a true value aborts selection grabbing. It will still be 246 Returning a true value aborts selection grabbing. It will still be
102 hilighted. 247 hilighted.
103 248
104 on_focus_in $term 249 on_sel_extend $term
105 Called whenever the window gets the keyboard focus, before urxvt 250 Called whenever the user tries to extend the selection (e.g. with a
106 does focus in processing. 251 double click) and is either supposed to return false (normal
252 operation), or should extend the selection itelf and return true to
253 suppress the built-in processing. This can happen multiple times, as
254 long as the callback returns true, it will be called on every
255 further click by the user and is supposed to enlarge the selection
256 more and more, if possible.
107 257
108 on_focus_out $term 258 See the selection example extension.
109 Called wheneever the window loses keyboard focus, before urxvt does
110 focus out processing.
111 259
112 on_view_change $term, $offset 260 on_view_change $term, $offset
113 Called whenever the view offset changes, i..e the user or program 261 Called whenever the view offset changes, i..e the user or program
114 scrolls. Offset 0 means display the normal terminal, positive values 262 scrolls. Offset 0 means display the normal terminal, positive values
115 show this many lines of scrollback. 263 show this many lines of scrollback.
121 269
122 It is called before lines are scrolled out (so rows 0 .. min ($lines 270 It is called before lines are scrolled out (so rows 0 .. min ($lines
123 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is 271 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
124 the total number of lines that will be in the scrollback buffer. 272 the total number of lines that will be in the scrollback buffer.
125 273
126 on_tty_activity $term *NYI* 274 on_osc_seq $term, $string
127 Called whenever the program(s) running in the urxvt window send 275 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
128 output. 276 operating system command) is processed. Cursor position and other
277 state information is up-to-date when this happens. For
278 interoperability, the string should start with the extension name
279 and a colon, to distinguish it from commands for other extensions,
280 and this might be enforced in the future.
281
282 Be careful not ever to trust (in a security sense) the data you
283 receive, as its source can not easily be controleld (e-mail content,
284 messages from other users on the same system etc.).
285
286 on_add_lines $term, $string
287 Called whenever text is about to be output, with the text as
288 argument. You can filter/change and output the text yourself by
289 returning a true value and calling "$term->scr_add_lines" yourself.
290 Please note that this might be very slow, however, as your hook is
291 called for all text being output.
292
293 on_tt_write $term, $octets
294 Called whenever some data is written to the tty/pty and can be used
295 to suppress or filter tty input.
296
297 on_line_update $term, $row
298 Called whenever a line was updated or changed. Can be used to filter
299 screen output (e.g. underline urls or other useless stuff). Only
300 lines that are being shown will be filtered, and, due to performance
301 reasons, not always immediately.
302
303 The row number is always the topmost row of the line if the line
304 spans multiple rows.
305
306 Please note that, if you change the line, then the hook might get
307 called later with the already-modified line (e.g. if unrelated parts
308 change), so you cannot just toggle rendition bits, but only set
309 them.
129 310
130 on_refresh_begin $term 311 on_refresh_begin $term
131 Called just before the screen gets redrawn. Can be used for overlay 312 Called just before the screen gets redrawn. Can be used for overlay
132 or similar effects by modify terminal contents in refresh_begin, and 313 or similar effects by modify terminal contents in refresh_begin, and
133 restoring them in refresh_end. The built-in overlay and selection 314 restoring them in refresh_end. The built-in overlay and selection
139 on_keyboard_command $term, $string 320 on_keyboard_command $term, $string
140 Called whenever the user presses a key combination that has a 321 Called whenever the user presses a key combination that has a
141 "perl:string" action bound to it (see description of the keysym 322 "perl:string" action bound to it (see description of the keysym
142 resource in the rxvt(1) manpage). 323 resource in the rxvt(1) manpage).
143 324
325 on_focus_in $term
326 Called whenever the window gets the keyboard focus, before
327 rxvt-unicode does focus in processing.
328
329 on_focus_out $term
330 Called wheneever the window loses keyboard focus, before
331 rxvt-unicode does focus out processing.
332
333 on_key_press $term, $event, $keysym, $octets
334 on_key_release $term, $event, $keysym
335 on_button_press $term, $event
336 on_button_release $term, $event
337 on_motion_notify $term, $event
338 on_map_notify $term, $event
339 on_unmap_notify $term, $event
340 Called whenever the corresponding X event is received for the
341 terminal If the hook returns true, then the even will be ignored by
342 rxvt-unicode.
343
344 The event is a hash with most values as named by Xlib (see the
345 XEvent manpage), with the additional members "row" and "col", which
346 are the row and column under the mouse cursor.
347
348 "on_key_press" additionally receives the string rxvt-unicode would
349 output, if any, in locale-specific encoding.
350
351 subwindow.
352
353 Variables in the "urxvt" Package
354 $urxvt::LIBDIR
355 The rxvt-unicode library directory, where, among other things, the
356 perl modules and scripts are stored.
357
358 $urxvt::RESCLASS, $urxvt::RESCLASS
359 The resource class and name rxvt-unicode uses to look up X
360 resources.
361
362 $urxvt::RXVTNAME
363 The basename of the installed binaries, usually "urxvt".
364
365 $urxvt::TERM
366 The current terminal. This variable stores the current "urxvt::term"
367 object, whenever a callback/hook is executing.
368
144 Functions in the "urxvt" Package 369 Functions in the "urxvt" Package
145 urxvt::fatal $errormessage 370 urxvt::fatal $errormessage
146 Fatally aborts execution with the given error message. Avoid at all 371 Fatally aborts execution with the given error message. Avoid at all
147 costs! The only time this is acceptable is when the terminal process 372 costs! The only time this is acceptable is when the terminal process
148 starts up. 373 starts up.
153 function that calls this function. 378 function that calls this function.
154 379
155 Using this function has the advantage that its output ends up in the 380 Using this function has the advantage that its output ends up in the
156 correct place, e.g. on stderr of the connecting urxvtc client. 381 correct place, e.g. on stderr of the connecting urxvtc client.
157 382
383 Messages have a size limit of 1023 bytes currently.
384
385 $is_safe = urxvt::safe
386 Returns true when it is safe to do potentially unsafe things, such
387 as evaluating perl code specified by the user. This is true when
388 urxvt was started setuid or setgid.
389
158 $time = urxvt::NOW 390 $time = urxvt::NOW
159 Returns the "current time" (as per the event loop). 391 Returns the "current time" (as per the event loop).
160 392
393 urxvt::CurrentTime
394 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
395 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
396 Button5Mask, AnyModifier
397 Various constants for use in X calls and event processing.
398
399 RENDITION
400 Rendition bitsets contain information about colour, font, font styles
401 and similar information for each screen cell.
402
403 The following "macros" deal with changes in rendition sets. You should
404 never just create a bitset, you should always modify an existing one, as
405 they contain important information required for correct operation of
406 rxvt-unicode.
407
408 $rend = urxvt::DEFAULT_RSTYLE
409 Returns the default rendition, as used when the terminal is starting
410 up or being reset. Useful as a base to start when creating
411 renditions.
412
413 $rend = urxvt::OVERLAY_RSTYLE
414 Return the rendition mask used for overlays by default.
415
416 $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
417 Return the bit that enabled bold, italic, blink, reverse-video and
418 underline, respectively. To enable such a style, just logically OR
419 it into the bitset.
420
421 $foreground = urxvt::GET_BASEFG $rend
422 $background = urxvt::GET_BASEBG $rend
423 Return the foreground/background colour index, respectively.
424
425 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
426 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
427 Replace the foreground/background colour in the rendition mask with
428 the specified one.
429
430 $value = urxvt::GET_CUSTOM $rend
431 Return the "custom" value: Every rendition has 5 bits for use by
432 extensions. They can be set and changed as you like and are
433 initially zero.
434
435 $rend = urxvt::SET_CUSTOM $rend, $new_value
436 Change the custom value.
437
438 The "urxvt::anyevent" Class
439 The sole purpose of this class is to deliver an interface to the
440 "AnyEvent" module - any module using it will work inside urxvt without
441 further programming. The only exception is that you cannot wait on
442 condition variables, but non-blocking condvar use is ok. What this means
443 is that you cannot use blocking APIs, but the non-blocking variant
444 should work.
445
161 The "urxvt::term" Class 446 The "urxvt::term" Class
447 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
448 Creates a new terminal, very similar as if you had started it with
449 system "$rxvtname, arg...". $envhashref must be a reference to a
450 %ENV-like hash which defines the environment of the new terminal.
451
452 Croaks (and probably outputs an error message) if the new instance
453 couldn't be created. Returns "undef" if the new instance didn't
454 initialise perl, and the terminal object otherwise. The "init" and
455 "start" hooks will be called during this call.
456
457 $term->destroy
458 Destroy the terminal object (close the window, free resources etc.).
459 Please note that rxvt will not exit as long as any event watchers
460 (timers, io watchers) are still active.
461
462 $isset = $term->option ($optval[, $set])
463 Returns true if the option specified by $optval is enabled, and
464 optionally change it. All option values are stored by name in the
465 hash %urxvt::OPTION. Options not enabled in this binary are not in
466 the hash.
467
468 Here is a a likely non-exhaustive list of option names, please see
469 the source file /src/optinc.h to see the actual list:
470
471 borderLess console cursorBlink cursorUnderline hold iconic insecure
472 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
473 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
474 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
475 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
476 tripleclickwords utmpInhibit visualBell
477
162 $value = $term->resource ($name[, $newval]) 478 $value = $term->resource ($name[, $newval])
163 Returns the current resource value associated with a given name and 479 Returns the current resource value associated with a given name and
164 optionally sets a new value. Setting values is most useful in the 480 optionally sets a new value. Setting values is most useful in the
165 "init" hook. Unset resources are returned and accepted as "undef". 481 "init" hook. Unset resources are returned and accepted as "undef".
166 482
175 Please note that resource strings will currently only be freed when 491 Please note that resource strings will currently only be freed when
176 the terminal is destroyed, so changing options frequently will eat 492 the terminal is destroyed, so changing options frequently will eat
177 memory. 493 memory.
178 494
179 Here is a a likely non-exhaustive list of resource names, not all of 495 Here is a a likely non-exhaustive list of resource names, not all of
180 which are supported in every build, please see the source to see the 496 which are supported in every build, please see the source file
181 actual list: 497 /src/rsinc.h to see the actual list:
182 498
183 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 499 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
184 borderLess color cursorBlink cursorUnderline cutchars delete_key 500 borderLess color cursorBlink cursorUnderline cutchars delete_key
185 display_name embed ext_bwidth fade font geometry hold iconName 501 display_name embed ext_bwidth fade font geometry hold iconName
186 imFont imLocale inputMethod insecure int_bwidth intensityStyles 502 imFont imLocale inputMethod insecure int_bwidth intensityStyles
187 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 503 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
188 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 504 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
189 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 505 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
190 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 506 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
191 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 507 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
192 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 508 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
193 shade term_name title transparent transparent_all tripleclickwords 509 shade term_name title transparent transparent_all tripleclickwords
194 utmpInhibit visualBell 510 utmpInhibit visualBell
195 511
512 $value = $term->x_resource ($pattern)
513 Returns the X-Resource for the given pattern, excluding the program
514 or class name, i.e. "$term->x_resource ("boldFont")" should return
515 the same value as used by this instance of rxvt-unicode. Returns
516 "undef" if no resource with that pattern exists.
517
518 This method should only be called during the "on_start" hook, as
519 there is only one resource database per display, and later
520 invocations might return the wrong resources.
521
522 $success = $term->parse_keysym ($keysym_spec, $command_string)
523 Adds a keymap translation exactly as specified via a resource. See
524 the "keysym" resource in the rxvt(1) manpage.
525
526 $rend = $term->rstyle ([$new_rstyle])
527 Return and optionally change the current rendition. Text that is
528 output by the terminal application will use this style.
529
530 ($row, $col) = $term->screen_cur ([$row, $col])
531 Return the current coordinates of the text cursor position and
532 optionally set it (which is usually bad as applications don't expect
533 that).
534
196 ($row, $col) = $term->selection_mark ([$row, $col]) 535 ($row, $col) = $term->selection_mark ([$row, $col])
197 ($row, $col) = $term->selection_beg ([$row, $col]) 536 ($row, $col) = $term->selection_beg ([$row, $col])
198 ($row, $col) = $term->selection_end ([$row, $col]) 537 ($row, $col) = $term->selection_end ([$row, $col])
199 Return the current values of the selection mark, begin or end 538 Return the current values of the selection mark, begin or end
200 positions, and optionally set them to new values. 539 positions, and optionally set them to new values.
201 540
541 $term->selection_make ($eventtime[, $rectangular])
542 Tries to make a selection as set by "selection_beg" and
543 "selection_end". If $rectangular is true (default: false), a
544 rectangular selection will be made. This is the prefered function to
545 make a selection.
546
202 $success = $term->selection_grab ($eventtime) 547 $success = $term->selection_grab ($eventtime)
203 Try to request the primary selection from the server (for example, 548 Try to request the primary selection text from the server (for
204 as set by the next method). 549 example, as set by the next method). No visual feedback will be
550 given. This function is mostly useful from within "on_sel_grab"
551 hooks.
205 552
206 $oldtext = $term->selection ([$newtext]) 553 $oldtext = $term->selection ([$newtext])
207 Return the current selection text and optionally replace it by 554 Return the current selection text and optionally replace it by
208 $newtext. 555 $newtext.
209 556
210 $term->scr_overlay ($x, $y, $text) 557 $term->overlay_simple ($x, $y, $text)
211 Create a simple multi-line overlay box. See the next method for 558 Create a simple multi-line overlay box. See the next method for
212 details. 559 details.
213 560
214 $term->scr_overlay_new ($x, $y, $width, $height) 561 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
215 Create a new (empty) overlay at the given position with the given 562 Create a new (empty) overlay at the given position with the given
216 width/height. A border will be put around the box. If either $x or 563 width/height. $rstyle defines the initial rendition style (default:
564 "OVERLAY_RSTYLE").
565
566 If $border is 2 (default), then a decorative border will be put
567 around the box.
568
217 $y is negative, then this is counted from the right/bottom side, 569 If either $x or $y is negative, then this is counted from the
218 respectively. 570 right/bottom side, respectively.
219 571
220 $term->scr_overlay_off 572 This method returns an urxvt::overlay object. The overlay will be
221 Switch the overlay off again. 573 visible as long as the perl object is referenced.
222 574
223 $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 575 The methods currently supported on "urxvt::overlay" objects are:
224 Put a single character (specified numerically) at the given overlay
225 position.
226 576
227 $term->scr_overlay_set ($x, $y, $text) 577 $overlay->set ($x, $y, $text, $rend)
228 Write a string at the given position into the overlay. 578 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
579 text in rxvt-unicode's special encoding and an array of
580 rendition values at a specific position inside the overlay.
229 581
582 $overlay->hide
583 If visible, hide the overlay, but do not destroy it.
584
585 $overlay->show
586 If hidden, display the overlay again.
587
588 $popup = $term->popup ($event)
589 Creates a new "urxvt::popup" object that implements a popup menu.
590 The $event *must* be the event causing the menu to pop up (a button
591 event, currently).
592
230 $cellwidth = $term->strwidth $string 593 $cellwidth = $term->strwidth ($string)
231 Returns the number of screen-cells this string would need. Correctly 594 Returns the number of screen-cells this string would need. Correctly
232 accounts for wide and combining characters. 595 accounts for wide and combining characters.
233 596
234 $octets = $term->locale_encode $string 597 $octets = $term->locale_encode ($string)
235 Convert the given text string into the corresponding locale 598 Convert the given text string into the corresponding locale
236 encoding. 599 encoding.
237 600
238 $string = $term->locale_decode $octets 601 $string = $term->locale_decode ($octets)
239 Convert the given locale-encoded octets into a perl string. 602 Convert the given locale-encoded octets into a perl string.
603
604 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
605 XORs the rendition values in the given span with the provided value
606 (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful
607 in refresh hooks to provide effects similar to the selection.
608
609 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
610 $rstyle2]])
611 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
612 whitespace will additionally be xored with the $rstyle2, which
613 defaults to "RS_RVid | RS_Uline", which removes reverse video again
614 and underlines it instead. Both styles *MUST NOT* contain font
615 styles.
616
617 $term->scr_bell
618 Ring the bell!
619
620 $term->scr_add_lines ($string)
621 Write the given text string to the screen, as if output by the
622 application running inside the terminal. It may not contain command
623 sequences (escape codes), but is free to use line feeds, carriage
624 returns and tabs. The string is a normal text string, not in
625 locale-dependent encoding.
626
627 Normally its not a good idea to use this function, as programs might
628 be confused by changes in cursor position or scrolling. Its useful
629 inside a "on_add_lines" hook, though.
630
631 $term->cmd_parse ($octets)
632 Similar to "scr_add_lines", but the argument must be in the
633 locale-specific encoding of the terminal and can contain command
634 sequences (escape codes) that will be interpreted.
240 635
241 $term->tt_write ($octets) 636 $term->tt_write ($octets)
242 Write the octets given in $data to the tty (i.e. as program input). 637 Write the octets given in $data to the tty (i.e. as program input).
243 To pass characters instead of octets, you should convert your 638 To pass characters instead of octets, you should convert your
244 strings first to the locale-specific encoding using 639 strings first to the locale-specific encoding using
245 "$term->locale_encode". 640 "$term->locale_encode".
246 641
642 $old_events = $term->pty_ev_events ([$new_events])
643 Replaces the event mask of the pty watcher by the given event mask.
644 Can be used to suppress input and output handling to the pty/tty.
645 See the description of "urxvt::timer->events". Make sure to always
646 restore the previous value.
647
648 $windowid = $term->parent
649 Return the window id of the toplevel window.
650
651 $windowid = $term->vt
652 Return the window id of the terminal window.
653
654 $window_width = $term->width
655 $window_height = $term->height
656 $font_width = $term->fwidth
657 $font_height = $term->fheight
658 $font_ascent = $term->fbase
247 $nrow = $term->nrow 659 $terminal_rows = $term->nrow
248 $ncol = $term->ncol 660 $terminal_columns = $term->ncol
249 Return the number of rows/columns of the terminal window (i.e. as 661 $has_focus = $term->focus
250 specified by "-geometry", excluding any scrollback). 662 $is_mapped = $term->mapped
663 $max_scrollback = $term->saveLines
664 $nrow_plus_saveLines = $term->total_rows
665 $lines_in_scrollback = $term->nsaved
666 Return various integers describing terminal characteristics.
251 667
668 $x_display = $term->display_id
669 Return the DISPLAY used by rxvt-unicode.
670
671 $lc_ctype = $term->locale
672 Returns the LC_CTYPE category string used by this rxvt-unicode.
673
252 $nsaved = $term->nsaved 674 $env = $term->env
253 Returns the number of lines in the scrollback buffer. 675 Returns a copy of the environment in effect for the terminal as a
676 hashref similar to "\%ENV".
677
678 $modifiermask = $term->ModLevel3Mask
679 $modifiermask = $term->ModMetaMask
680 $modifiermask = $term->ModNumLockMask
681 Return the modifier masks corresponding to the "ISO Level 3 Shift"
682 (often AltGr), the meta key (often Alt) and the num lock key, if
683 applicable.
254 684
255 $view_start = $term->view_start ([$newvalue]) 685 $view_start = $term->view_start ([$newvalue])
256 Returns the negative row number of the topmost line. Minimum value 686 Returns the negative row number of the topmost line. Minimum value
257 is 0, which displays the normal terminal contents. Larger values 687 is 0, which displays the normal terminal contents. Larger values
258 scroll this many lines into the scrollback buffer. 688 scroll this many lines into the scrollback buffer.
266 696
267 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 697 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
268 Returns the text of the entire row with number $row_number. Row 0 is 698 Returns the text of the entire row with number $row_number. Row 0 is
269 the topmost terminal line, row "$term->$ncol-1" is the bottommost 699 the topmost terminal line, row "$term->$ncol-1" is the bottommost
270 terminal line. The scrollback buffer starts at line -1 and extends 700 terminal line. The scrollback buffer starts at line -1 and extends
271 to line "-$term->nsaved". 701 to line "-$term->nsaved". Nothing will be returned if a nonexistent
702 line is requested.
272 703
273 If $new_text is specified, it will replace characters in the current 704 If $new_text is specified, it will replace characters in the current
274 line, starting at column $start_col (default 0), which is useful to 705 line, starting at column $start_col (default 0), which is useful to
275 replace only parts of a line. The font iindex in the rendition will 706 replace only parts of a line. The font index in the rendition will
276 automatically be updated. 707 automatically be updated.
277 708
278 $text is in a special encoding: tabs and wide characters that use 709 $text is in a special encoding: tabs and wide characters that use
279 more than one cell when displayed are padded with urxvt::NOCHAR 710 more than one cell when displayed are padded with urxvt::NOCHAR
280 characters ("chr 65535"). Characters with combining characters and 711 characters ("chr 65535"). Characters with combining characters and
293 Rendition bitsets contain information about colour, font, font 724 Rendition bitsets contain information about colour, font, font
294 styles and similar information. See also "$term->ROW_t". 725 styles and similar information. See also "$term->ROW_t".
295 726
296 When setting rendition, the font mask will be ignored. 727 When setting rendition, the font mask will be ignored.
297 728
298 See the section on RENDITION, below. 729 See the section on RENDITION, above.
299 730
300 $length = $term->ROW_l ($row_number[, $new_length]) 731 $length = $term->ROW_l ($row_number[, $new_length])
301 Returns the number of screen cells that are in use ("the line 732 Returns the number of screen cells that are in use ("the line
302 length"). If it is -1, then the line is part of a multiple-row 733 length"). Unlike the urxvt core, this returns "$term->ncol" if the
303 logical "line", which means all characters are in use and it is 734 line is joined with the following one.
304 continued on the next row. 735
736 $bool = $term->is_longer ($row_number)
737 Returns true if the row is part of a multiple-row logical "line"
738 (i.e. joined with the following row), which means all characters are
739 in use and it is continued on the next row (and possibly a
740 continuation of the previous row(s)).
741
742 $line = $term->line ($row_number)
743 Create and return a new "urxvt::line" object that stores information
744 about the logical line that row $row_number is part of. It supports
745 the following methods:
746
747 $text = $line->t ([$new_text])
748 Returns or replaces the full text of the line, similar to
749 "ROW_t"
750
751 $rend = $line->r ([$new_rend])
752 Returns or replaces the full rendition array of the line,
753 similar to "ROW_r"
754
755 $length = $line->l
756 Returns the length of the line in cells, similar to "ROW_l".
757
758 $rownum = $line->beg
759 $rownum = $line->end
760 Return the row number of the first/last row of the line,
761 respectively.
762
763 $offset = $line->offset_of ($row, $col)
764 Returns the character offset of the given row|col pair within
765 the logical line. Works for rows outside the line, too, and
766 returns corresponding offsets outside the string.
767
768 ($row, $col) = $line->coord_of ($offset)
769 Translates a string offset into terminal coordinates again.
305 770
306 $text = $term->special_encode $string 771 $text = $term->special_encode $string
307 Converts a perl string into the special encoding used by 772 Converts a perl string into the special encoding used by
308 rxvt-unicode, where one character corresponds to one screen cell. 773 rxvt-unicode, where one character corresponds to one screen cell.
309 See "$term->ROW_t" for details. 774 See "$term->ROW_t" for details.
310 775
311 $string = $term->special_decode $text 776 $string = $term->special_decode $text
312 Converts rxvt-unicodes text reprsentation into a perl string. See 777 Converts rxvt-unicodes text reprsentation into a perl string. See
313 "$term->ROW_t" for details. 778 "$term->ROW_t" for details.
314 779
315 RENDITION 780 $success = $term->grab_button ($button, $modifiermask)
316 Rendition bitsets contain information about colour, font, font styles 781 Registers a synchronous button grab. See the XGrabButton manpage.
317 and similar information for each screen cell.
318 782
319 The following "macros" deal with changes in rendition sets. You should 783 $success = $term->grab ($eventtime[, $sync])
320 never just create a bitset, you should always modify an existing one, as 784 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
321 they contain important information required for correct operation of 785 synchronous ($sync is true). Also remembers the grab timestampe.
322 rxvt-unicode.
323 786
324 $rend = urxvt::DEFAULT_RSTYLE 787 $term->allow_events_async
325 Returns the default rendition, as used when the terminal is starting 788 Calls XAllowEvents with AsyncBoth for the most recent grab.
326 up or being reset. Useful as a base 789
790 $term->allow_events_sync
791 Calls XAllowEvents with SyncBoth for the most recent grab.
792
793 $term->allow_events_replay
794 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
795 the most recent grab.
796
797 $term->ungrab
798 Calls XUngrab for the most recent grab. Is called automatically on
799 evaluation errors, as it is better to lose the grab in the error
800 case as the session.
801
802 The "urxvt::popup" Class
803 $popup->add_title ($title)
804 Adds a non-clickable title to the popup.
805
806 $popup->add_separator ([$sepchr])
807 Creates a separator, optionally using the character given as
808 $sepchr.
809
810 $popup->add_button ($text, $cb)
811 Adds a clickable button to the popup. $cb is called whenever it is
812 selected.
813
814 $popup->add_toggle ($text, $cb, $initial_value)
815 Adds a toggle/checkbox item to the popup. Teh callback gets called
816 whenever it gets toggled, with a boolean indicating its value as its
817 first argument.
818
819 $popup->show
820 Displays the popup (which is initially hidden).
327 821
328 The "urxvt::timer" Class 822 The "urxvt::timer" Class
329 This class implements timer watchers/events. Time is represented as a 823 This class implements timer watchers/events. Time is represented as a
330 fractional number of seconds since the epoch. Example: 824 fractional number of seconds since the epoch. Example:
331 825
332 # create a digital clock display in upper right corner 826 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
333 $term->{timer} = urxvt::timer 827 $term->{timer} = urxvt::timer
334 ->new 828 ->new
335 ->start (urxvt::NOW) 829 ->interval (1)
336 ->cb (sub { 830 ->cb (sub {
337 my ($timer) = @_;
338 my $time = $timer->at;
339 $timer->start ($time + 1);
340 $self->scr_overlay (-1, 0, 831 $term->{overlay}->set (0, 0,
341 POSIX::strftime "%H:%M:%S", localtime $time); 832 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
342 }); 833 });
343 834
344 $timer = new urxvt::timer 835 $timer = new urxvt::timer
345 Create a new timer object in stopped state. 836 Create a new timer object in started state. It is scheduled to fire
837 immediately.
346 838
347 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 839 $timer = $timer->cb (sub { my ($timer) = @_; ... })
348 Set the callback to be called when the timer triggers. 840 Set the callback to be called when the timer triggers.
349 841
350 $tstamp = $timer->at 842 $tstamp = $timer->at
351 Return the time this watcher will fire next. 843 Return the time this watcher will fire next.
352 844
353 $timer = $timer->set ($tstamp) 845 $timer = $timer->set ($tstamp)
354 Set the time the event is generated to $tstamp. 846 Set the time the event is generated to $tstamp.
847
848 $timer = $timer->interval ($interval)
849 Normally (and when $interval is 0), the timer will automatically
850 stop after it has fired once. If $interval is non-zero, then the
851 timer is automatically rescheduled at the given intervals.
355 852
356 $timer = $timer->start 853 $timer = $timer->start
357 Start the timer. 854 Start the timer.
358 855
359 $timer = $timer->start ($tstamp) 856 $timer = $timer->start ($tstamp)
367 864
368 $term->{socket} = ... 865 $term->{socket} = ...
369 $term->{iow} = urxvt::iow 866 $term->{iow} = urxvt::iow
370 ->new 867 ->new
371 ->fd (fileno $term->{socket}) 868 ->fd (fileno $term->{socket})
372 ->events (1) # wait for read data 869 ->events (urxvt::EVENT_READ)
373 ->start 870 ->start
374 ->cb (sub { 871 ->cb (sub {
375 my ($iow, $revents) = @_; 872 my ($iow, $revents) = @_;
376 # $revents must be 1 here, no need to check 873 # $revents must be 1 here, no need to check
377 sysread $term->{socket}, my $buf, 8192 874 sysread $term->{socket}, my $buf, 8192
387 884
388 $iow = $iow->fd ($fd) 885 $iow = $iow->fd ($fd)
389 Set the filedescriptor (not handle) to watch. 886 Set the filedescriptor (not handle) to watch.
390 887
391 $iow = $iow->events ($eventmask) 888 $iow = $iow->events ($eventmask)
392 Set the event mask to watch. Bit #0 (value 1) enables watching for 889 Set the event mask to watch. The only allowed values are
393 read data, Bit #1 (value 2) enables watching for write data. 890 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
891 together, or "urxvt::EVENT_NONE".
394 892
395 $iow = $iow->start 893 $iow = $iow->start
396 Start watching for requested events on the given handle. 894 Start watching for requested events on the given handle.
397 895
398 $iow = $iow->stop 896 $iow = $iow->stop
401ENVIRONMENT 899ENVIRONMENT
402 URXVT_PERL_VERBOSITY 900 URXVT_PERL_VERBOSITY
403 This variable controls the verbosity level of the perl extension. Higher 901 This variable controls the verbosity level of the perl extension. Higher
404 numbers indicate more verbose output. 902 numbers indicate more verbose output.
405 903
406 0 - only fatal messages 904 == 0 - fatal messages
407 3 - script loading and management 905 >= 3 - script loading and management
408 10 - all events received 906 >=10 - all called hooks
907 >=11 - hook reutrn values
409 908
410AUTHOR 909AUTHOR
411 Marc Lehmann <pcg@goof.com> 910 Marc Lehmann <pcg@goof.com>
412 http://software.schmorp.de/pkg/rxvt-unicode 911 http://software.schmorp.de/pkg/rxvt-unicode
413 912

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines