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.6 by root, Tue Jan 3 04:20:37 2006 UTC vs.
Revision 1.41 by root, Tue Feb 21 01:00:40 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
26 Prepackaged 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 Or by adding them to the resource for extensions loaded by default:
35 Miscellaneous selection modifications. 35
36 URxvt.perl-ext-common: default,automove-background,selection-autotransform
37
38 selection (enabled by default)
39 (More) intelligent selection. This extension tries to be more
40 intelligent when the user extends selections (double-click and
41 further clicks). Right now, it tries to select words, urls and
42 complete shell-quoted arguments, which is very convenient, too, if
43 your ls supports "--quoting-style=shell".
44
45 A double-click usually selects the word under the cursor, further
46 clicks will enlarge the selection.
47
48 The selection works by trying to match a number of regexes and
49 displaying them in increasing order of length. You can add your own
50 regexes by specifying resources of the form:
51
52 URxvt.selection.pattern-0: perl-regex
53 URxvt.selection.pattern-1: perl-regex
54 ...
55
56 The index number (0, 1...) must not have any holes, and each regex
57 must contain at least one pair of capturing parentheses, which will
58 be used for the match. For example, the followign adds a regex that
59 matches everything between two vertical bars:
60
61 URxvt.selection.pattern-0: \\|([^|]+)\\|
62
63 Another example: Programs I use often output "absolute path: " at
64 the beginning of a line when they process multiple files. The
65 following pattern matches the filename (note, there is a single
66 space at the very end):
67
68 URxvt.selection.pattern-0: ^(/[^:]+):\
69
70 You can look at the source of the selection extension to see more
71 interesting uses, such as parsing a line from beginning to end.
72
73 This extension also offers following bindable keyboard commands:
36 74
37 rot13 75 rot13
38 Rot-13 the selection when activated. Used via keyboard trigger: 76 Rot-13 the selection when activated. Used via keyboard trigger:
39 77
40 URxvt.keysym.C-M-r: perl:selection:rot13 78 URxvt.keysym.C-M-r: perl:selection:rot13
41 79
80 option-popup (enabled by default)
81 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
82 options at runtime.
83
84 Other extensions can extend this popup menu by pushing a code
85 reference onto "@{ $term-"{option_popup_hook} }>, which gets called
86 whenever the popup is being displayed.
87
88 It's sole argument is the popup menu, which can be modified. It
89 should either return nothing or a string, the initial boolean value
90 and a code reference. The string will be used as button text and the
91 code reference will be called when the toggle changes, with the new
92 boolean value as first argument.
93
94 The following will add an entry "myoption" that changes
95 "$self-"{myoption}>:
96
97 push @{ $self->{term}{option_popup_hook} }, sub {
98 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
99 };
100
101 selection-popup (enabled by default)
102 Binds a popup menu to Ctrl-Button3 that lets you convert the
103 selection text into various other formats/action (such as uri
104 unescaping, perl evaluation, web-browser starting etc.), depending
105 on content.
106
107 Other extensions can extend this popup menu by pushing a code
108 reference onto "@{ $term-"{selection_popup_hook} }>, which gets
109 called whenever the popup is being displayed.
110
111 It's sole argument is the popup menu, which can be modified. The
112 selection is in $_, which can be used to decide wether to add
113 something or not. It should either return nothing or a string and a
114 code reference. The string will be used as button text and the code
115 reference will be called when the button gets activated and should
116 transform $_.
117
118 The following will add an entry "a to b" that transforms all "a"s in
119 the selection to "b"s, but only if the selection currently contains
120 any "a"s:
121
122 push @{ $self->{term}{selection_popup_hook} }, sub {
123 /a/ ? ("a to be" => sub { s/a/b/g }
124 : ()
125 };
126
127 searchable-scrollback<hotkey> (enabled by default)
128 Adds regex search functionality to the scrollback buffer, triggered
129 by a hotkey (default: "M-s"). While in search mode, normal terminal
130 input/output is suspended and a regex is displayed at the bottom of
131 the screen.
132
133 Inputting characters appends them to the regex and continues
134 incremental search. "BackSpace" removes a character from the regex,
135 "Up" and "Down" search upwards/downwards in the scrollback buffer,
136 "End" jumps to the bottom. "Escape" leaves search mode and returns
137 to the point where search was started, while "Enter" or "Return"
138 stay at the current position and additionally stores the first match
139 in the current line into the primary selection.
140
141 readline (enabled by default)
142 A support package that tries to make editing with readline easier.
143 At the moment, it reacts to clicking shift-left mouse button by
144 trying to move the text cursor to this position. It does so by
145 generating as many cursor-left or cursor-right keypresses as
146 required (the this only works for programs that correctly support
147 wide characters).
148
149 To avoid too many false positives, this is only done when:
150
151 - the tty is in ICANON state.
152 - the text cursor is visible.
153 - the primary screen is currently being displayed.
154 - the mouse is on the same (multi-row-) line as the text cursor.
155
156 The normal selection mechanism isn't disabled, so quick successive
157 clicks might interfere with selection creation in harmless ways.
158
159 selection-autotransform
160 This selection allows you to do automatic transforms on a selection
161 whenever a selection is made.
162
163 It works by specifying perl snippets (most useful is a single "s///"
164 operator) that modify $_ as resources:
165
166 URxvt.selection-autotransform.0: transform
167 URxvt.selection-autotransform.1: transform
168 ...
169
170 For example, the following will transform selections of the form
171 "filename:number", often seen in compiler messages, into "vi
172 +$filename $word":
173
174 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
175
176 And this example matches the same,but replaces it with vi-commands
177 you can paste directly into your (vi :) editor:
178
179 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
180
181 Of course, this can be modified to suit your needs and your editor
182 :)
183
184 To expand the example above to typical perl error messages ("XXX at
185 FILENAME line YYY."), you need a slightly more elaborate solution:
186
187 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
188 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
189
190 The first line tells the selection code to treat the unchanging part
191 of every error message as a selection pattern, and the second line
192 transforms the message into vi commands to load the file.
193
194 tabbed
195 This transforms the terminal into a tabbar with additional
196 terminals, that is, it implements what is commonly refered to as
197 "tabbed terminal". The topmost line displays a "[NEW]" button,
198 which, when clicked, will add a new tab, followed by one button per
199 tab.
200
201 Clicking a button will activate that tab. Pressing Shift-Left and
202 Shift-Right will switch to the tab left or right of the current one,
203 while Shift-Down creates a new tab.
204
205 The tabbar itself can be configured similarly to a normal terminal,
206 but with a resource class of "URxvt.tabbed". In addition, it
207 supports the following four resources (shown with defaults):
208
209 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
210 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
211 URxvt.tabbed.tab-fg: <colour-index, default 0>
212 URxvt.tabbed.tab-bg: <colour-index, default 1>
213
214 See *COLOR AND GRAPHICS* in the rxvt(1) manpage for valid indices.
215
216 mark-urls
217 Uses per-line display filtering ("on_line_update") to underline urls
218 and make them clickable. When middle-clicked, the program specified
219 in the resource "urlLauncher" (default "x-www-browser") will be
220 started with the URL as first argument.
221
222 xim-onthespot
223 This (experimental) perl extension implements OnTheSpot editing. It
224 does not work perfectly, and some input methods don't seem to work
225 well with OnTheSpot editing in general, but it seems to work at
226 leats for SCIM and kinput2.
227
228 You enable it by specifying this extension and a preedit style of
229 "OnTheSpot", i.e.:
230
231 rxvt -pt OnTheSpot -pe xim-onthespot
232
233 automove-background
234 This is basically a one-line extension that dynamically changes the
235 background pixmap offset to the window position, in effect creating
236 the same effect as pseudo transparency with a custom pixmap. No
237 scaling is supported in this mode. Exmaple:
238
239 rxvt -pixmap background.xpm -pe automove-background
240
241 block-graphics-to-ascii
242 A not very useful example of filtering all text output to the
243 terminal, by replacing all line-drawing characters (U+2500 ..
244 U+259F) by a similar-looking ascii character.
245
42 digital-clock 246 digital-clock
43 Displays a digital clock using the built-in overlay. 247 Displays a digital clock using the built-in overlay.
248
249 remote-clipboard
250 Somewhat of a misnomer, this extension adds two menu entries to the
251 selection popup that allows one ti run external commands to store
252 the selection somewhere and fetch it again.
253
254 We use it to implement a "distributed selection mechanism", which
255 just means that one command uploads the file to a remote server, and
256 another reads it.
257
258 The commands can be set using the "URxvt.remote-selection.store" and
259 "URxvt.remote-selection.fetch" resources. The first should read the
260 selection to store from STDIN (always in UTF-8), the second should
261 provide the selection data on STDOUT (also in UTF-8).
262
263 The defaults (which are likely useless to you) use rsh and cat:
264
265 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
266 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
267
268 selection-pastebin
269 This is a little rarely useful extension that Uploads the selection
270 as textfile to a remote site (or does other things). (The
271 implementation is not currently secure for use in a multiuser
272 environment as it writes to /tmp directly.).
273
274 It listens to the "selection-pastebin:remote-pastebin" keyboard
275 command, i.e.
276
277 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
278
279 Pressing this combination runs a command with "%" replaced by the
280 name of the textfile. This command can be set via a resource:
281
282 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
283
284 And the default is likely not useful to anybody but the few people
285 around here :)
286
287 The name of the textfile is the hex encoded md5 sum of the
288 selection, so the same content should lead to the same filename.
289
290 After a successful upload the selection will be replaced by the text
291 given in the "selection-pastebin-url" resource (again, the % is the
292 placeholder for the filename):
293
294 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
44 295
45 example-refresh-hooks 296 example-refresh-hooks
46 Displays a very simple digital clock in the upper right corner of 297 Displays a very simple digital clock in the upper right corner of
47 the window. Illustrates overwriting the refresh callbacks to create 298 the window. Illustrates overwriting the refresh callbacks to create
48 your own overlays or changes. 299 your own overlays or changes.
49 300
301API DOCUMENTATION
50 General API Considerations 302 General API Considerations
51 All objects (such as terminals, time watchers etc.) are typical 303 All objects (such as terminals, time watchers etc.) are typical
52 reference-to-hash objects. The hash can be used to store anything you 304 reference-to-hash objects. The hash can be used to store anything you
53 like. All members starting with an underscore (such as "_ptr" or 305 like. All members starting with an underscore (such as "_ptr" or
54 "_hook") are reserved for internal uses and must not be accessed or 306 "_hook") are reserved for internal uses and MUST NOT be accessed or
55 modified). 307 modified).
56 308
57 When objects are destroyed on the C++ side, the perl object hashes are 309 When objects are destroyed on the C++ side, the perl object hashes are
58 emptied, so its best to store related objects such as time watchers and 310 emptied, so its best to store related objects such as time watchers and
59 the like inside the terminal object so they get destroyed as soon as the 311 the like inside the terminal object so they get destroyed as soon as the
60 terminal is destroyed. 312 terminal is destroyed.
61 313
314 Argument names also often indicate the type of a parameter. Here are
315 some hints on what they mean:
316
317 $text
318 Rxvt-unicodes special way of encoding text, where one "unicode"
319 character always represents one screen cell. See ROW_t for a
320 discussion of this format.
321
322 $string
323 A perl text string, with an emphasis on *text*. It can store all
324 unicode characters and is to be distinguished with text encoded in a
325 specific encoding (often locale-specific) and binary data.
326
327 $octets
328 Either binary data or - more common - a text string encoded in a
329 locale-specific way.
330
331 Extension Objects
332 Very perl extension is a perl class. A separate perl object is created
333 for each terminal and each extension and passed as the first parameter
334 to hooks. So extensions can use their $self object without having to
335 think about other extensions, with the exception of methods and members
336 that begin with an underscore character "_": these are reserved for
337 internal use.
338
339 Although it isn't a "urxvt::term" object, you can call all methods of
340 the "urxvt::term" class on this object.
341
342 It has the following methods and data members:
343
344 $urxvt_term = $self->{term}
345 Returns the "urxvt::term" object associated with this instance of
346 the extension. This member *must not* be changed in any way.
347
348 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
349 Dynamically enable the given hooks (named without the "on_" prefix)
350 for this extension, replacing any previous hook. This is useful when
351 you want to overwrite time-critical hooks only temporarily.
352
353 $self->disable ($hook_name[, $hook_name..])
354 Dynamically disable the given hooks.
355
62 Hooks 356 Hooks
63 The following subroutines can be declared in loaded scripts, and will be 357 The following subroutines can be declared in extension files, and will
64 called whenever the relevant event happens. 358 be called whenever the relevant event happens.
65 359
66 All of them must return a boolean value. If it is true, then the event 360 The first argument passed to them is an extension oject as described in
67 counts as being *consumed*, and the invocation of other hooks is 361 the in the "Extension Objects" section.
362
363 All of these hooks must return a boolean value. If any of the called
364 hooks returns true, then the event counts as being *consumed*, and the
68 skipped, and the relevant action might not be carried out by the C++ 365 relevant action might not be carried out by the C++ code.
69 code.
70 366
71 When in doubt, return a false value (preferably "()"). 367 *When in doubt, return a false value (preferably "()").*
72 368
73 on_init $term 369 on_init $term
74 Called after a new terminal object has been initialized, but before 370 Called after a new terminal object has been initialized, but before
75 windows are created or the command gets run. 371 windows are created or the command gets run. Most methods are unsafe
372 to call or deliver senseless data, as terminal size and other
373 characteristics have not yet been determined. You can safely query
374 and change resources and options, though. For many purposes the
375 "on_start" hook is a better place.
376
377 on_start $term
378 Called at the very end of initialisation of a new terminal, just
379 before trying to map (display) the toplevel and returning to the
380 mainloop.
381
382 on_destroy $term
383 Called whenever something tries to destroy terminal, when the
384 terminal is still fully functional (not for long, though).
76 385
77 on_reset $term 386 on_reset $term
78 Called after the screen is "reset" for any reason, such as resizing 387 Called after the screen is "reset" for any reason, such as resizing
79 or control sequences. Here is where you can react on changes to 388 or control sequences. Here is where you can react on changes to
80 size-related variables. 389 size-related variables.
81 390
82 on_start $term 391 on_child_start $term, $pid
83 Called at the very end of initialisation of a new terminal, just 392 Called just after the child process has been "fork"ed.
84 before returning to the mainloop. 393
394 on_child_exit $term, $status
395 Called just after the child process has exited. $status is the
396 status from "waitpid".
85 397
86 on_sel_make $term, $eventtime 398 on_sel_make $term, $eventtime
87 Called whenever a selection has been made by the user, but before 399 Called whenever a selection has been made by the user, but before
88 the selection text is copied, so changes to the beginning, end or 400 the selection text is copied, so changes to the beginning, end or
89 type of the selection will be honored. 401 type of the selection will be honored.
… …
98 queried and changed by calling "$term->selection". 410 queried and changed by calling "$term->selection".
99 411
100 Returning a true value aborts selection grabbing. It will still be 412 Returning a true value aborts selection grabbing. It will still be
101 hilighted. 413 hilighted.
102 414
103 on_focus_in $term 415 on_sel_extend $term
104 Called whenever the window gets the keyboard focus, before urxvt 416 Called whenever the user tries to extend the selection (e.g. with a
105 does focus in processing. 417 double click) and is either supposed to return false (normal
418 operation), or should extend the selection itelf and return true to
419 suppress the built-in processing. This can happen multiple times, as
420 long as the callback returns true, it will be called on every
421 further click by the user and is supposed to enlarge the selection
422 more and more, if possible.
106 423
107 on_focus_out $term 424 See the selection example extension.
108 Called wheneever the window loses keyboard focus, before urxvt does
109 focus out processing.
110 425
111 on_view_change $term, $offset 426 on_view_change $term, $offset
112 Called whenever the view offset changes, i..e the user or program 427 Called whenever the view offset changes, i..e the user or program
113 scrolls. Offset 0 means display the normal terminal, positive values 428 scrolls. Offset 0 means display the normal terminal, positive values
114 show this many lines of scrollback. 429 show this many lines of scrollback.
… …
120 435
121 It is called before lines are scrolled out (so rows 0 .. min ($lines 436 It is called before lines are scrolled out (so rows 0 .. min ($lines
122 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is 437 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
123 the total number of lines that will be in the scrollback buffer. 438 the total number of lines that will be in the scrollback buffer.
124 439
125 on_tty_activity $term *NYI* 440 on_osc_seq $term, $string
126 Called whenever the program(s) running in the urxvt window send 441 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
127 output. 442 operating system command) is processed. Cursor position and other
443 state information is up-to-date when this happens. For
444 interoperability, the string should start with the extension name
445 and a colon, to distinguish it from commands for other extensions,
446 and this might be enforced in the future.
447
448 Be careful not ever to trust (in a security sense) the data you
449 receive, as its source can not easily be controleld (e-mail content,
450 messages from other users on the same system etc.).
451
452 on_add_lines $term, $string
453 Called whenever text is about to be output, with the text as
454 argument. You can filter/change and output the text yourself by
455 returning a true value and calling "$term->scr_add_lines" yourself.
456 Please note that this might be very slow, however, as your hook is
457 called for all text being output.
458
459 on_tt_write $term, $octets
460 Called whenever some data is written to the tty/pty and can be used
461 to suppress or filter tty input.
462
463 on_line_update $term, $row
464 Called whenever a line was updated or changed. Can be used to filter
465 screen output (e.g. underline urls or other useless stuff). Only
466 lines that are being shown will be filtered, and, due to performance
467 reasons, not always immediately.
468
469 The row number is always the topmost row of the line if the line
470 spans multiple rows.
471
472 Please note that, if you change the line, then the hook might get
473 called later with the already-modified line (e.g. if unrelated parts
474 change), so you cannot just toggle rendition bits, but only set
475 them.
128 476
129 on_refresh_begin $term 477 on_refresh_begin $term
130 Called just before the screen gets redrawn. Can be used for overlay 478 Called just before the screen gets redrawn. Can be used for overlay
131 or similar effects by modify terminal contents in refresh_begin, and 479 or similar effects by modify terminal contents in refresh_begin, and
132 restoring them in refresh_end. The built-in overlay and selection 480 restoring them in refresh_end. The built-in overlay and selection
133 display code is run after this hook, and takes precedence. 481 display code is run after this hook, and takes precedence.
134 482
135 on_refresh_end $term 483 on_refresh_end $term
136 Called just after the screen gets redrawn. See "on_refresh_begin". 484 Called just after the screen gets redrawn. See "on_refresh_begin".
137 485
138 on_keyboard_command $term, $string 486 on_user_command $term, $string
139 Called whenever the user presses a key combination that has a 487 Called whenever the a user-configured event is being activated (e.g.
140 "perl:string" action bound to it (see description of the keysym 488 via a "perl:string" action bound to a key, see description of the
141 resource in the rxvt(1) manpage). 489 keysym resource in the rxvt(1) manpage).
490
491 The event is simply the action string. This interface is assumed to
492 change slightly in the future.
493
494 on_resize_all_windows $tern, $new_width, $new_height
495 Called just after the new window size has been calculcated, but
496 before windows are actually being resized or hints are being set. If
497 this hook returns TRUE, setting of the window hints is being
498 skipped.
499
500 on_x_event $term, $event
501 Called on every X event received on the vt window (and possibly
502 other windows). Should only be used as a last resort. Most event
503 structure members are not passed.
504
505 on_focus_in $term
506 Called whenever the window gets the keyboard focus, before
507 rxvt-unicode does focus in processing.
508
509 on_focus_out $term
510 Called wheneever the window loses keyboard focus, before
511 rxvt-unicode does focus out processing.
512
513 on_configure_notify $term, $event
514 on_property_notify $term, $event
515 on_key_press $term, $event, $keysym, $octets
516 on_key_release $term, $event, $keysym
517 on_button_press $term, $event
518 on_button_release $term, $event
519 on_motion_notify $term, $event
520 on_map_notify $term, $event
521 on_unmap_notify $term, $event
522 Called whenever the corresponding X event is received for the
523 terminal If the hook returns true, then the even will be ignored by
524 rxvt-unicode.
525
526 The event is a hash with most values as named by Xlib (see the
527 XEvent manpage), with the additional members "row" and "col", which
528 are the (real, not screen-based) row and column under the mouse
529 cursor.
530
531 "on_key_press" additionally receives the string rxvt-unicode would
532 output, if any, in locale-specific encoding.
533
534 subwindow.
535
536 on_client_message $term, $event
537 on_wm_protocols $term, $event
538 on_wm_delete_window $term, $event
539 Called when various types of ClientMessage events are received (all
540 with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
541
542 Variables in the "urxvt" Package
543 $urxvt::LIBDIR
544 The rxvt-unicode library directory, where, among other things, the
545 perl modules and scripts are stored.
546
547 $urxvt::RESCLASS, $urxvt::RESCLASS
548 The resource class and name rxvt-unicode uses to look up X
549 resources.
550
551 $urxvt::RXVTNAME
552 The basename of the installed binaries, usually "urxvt".
553
554 $urxvt::TERM
555 The current terminal. This variable stores the current "urxvt::term"
556 object, whenever a callback/hook is executing.
557
558 @urxvt::TERM_INIT
559 All coderefs in this array will be called as methods of the next
560 newly created "urxvt::term" object (during the "on_init" phase). The
561 array gets cleared before the codereferences that were in it are
562 being executed, so coderefs can push themselves onto it again if
563 they so desire.
564
565 This complements to the perl-eval commandline option, but gets
566 executed first.
567
568 @urxvt::TERM_EXT
569 Works similar to @TERM_INIT, but contains perl package/class names,
570 which get registered as normal extensions after calling the hooks in
571 @TERM_INIT but before other extensions. Gets cleared just like
572 @TERM_INIT.
142 573
143 Functions in the "urxvt" Package 574 Functions in the "urxvt" Package
144 urxvt::fatal $errormessage 575 urxvt::fatal $errormessage
145 Fatally aborts execution with the given error message. Avoid at all 576 Fatally aborts execution with the given error message. Avoid at all
146 costs! The only time this is acceptable is when the terminal process 577 costs! The only time this is acceptable is when the terminal process
… …
152 function that calls this function. 583 function that calls this function.
153 584
154 Using this function has the advantage that its output ends up in the 585 Using this function has the advantage that its output ends up in the
155 correct place, e.g. on stderr of the connecting urxvtc client. 586 correct place, e.g. on stderr of the connecting urxvtc client.
156 587
588 Messages have a size limit of 1023 bytes currently.
589
590 @terms = urxvt::termlist
591 Returns all urxvt::term objects that exist in this process,
592 regardless of wether they are started, being destroyed etc., so be
593 careful. Only term objects that have perl extensions attached will
594 be returned (because there is no urxvt::term objet associated with
595 others).
596
157 $time = urxvt::NOW 597 $time = urxvt::NOW
158 Returns the "current time" (as per the event loop). 598 Returns the "current time" (as per the event loop).
599
600 urxvt::CurrentTime
601 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
602 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
603 Button5Mask, AnyModifier
604 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
605 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
606 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
607 Button3MotionMask, Button4MotionMask, Button5MotionMask,
608 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
609 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
610 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
611 ColormapChangeMask, OwnerGrabButtonMask
612 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
613 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
614 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
615 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
616 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
617 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
618 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
619 Various constants for use in X calls and event processing.
159 620
160 RENDITION 621 RENDITION
161 Rendition bitsets contain information about colour, font, font styles 622 Rendition bitsets contain information about colour, font, font styles
162 and similar information for each screen cell. 623 and similar information for each screen cell.
163 624
… …
181 642
182 $foreground = urxvt::GET_BASEFG $rend 643 $foreground = urxvt::GET_BASEFG $rend
183 $background = urxvt::GET_BASEBG $rend 644 $background = urxvt::GET_BASEBG $rend
184 Return the foreground/background colour index, respectively. 645 Return the foreground/background colour index, respectively.
185 646
186 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 647 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
187 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 648 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
649 $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
188 Replace the foreground/background colour in the rendition mask with 650 Replace the foreground/background colour in the rendition mask with
189 the specified one. 651 the specified one.
190 652
191 $value = urxvt::GET_CUSTOM ($rend) 653 $value = urxvt::GET_CUSTOM $rend
192 Return the "custom" value: Every rendition has 5 bits for use by 654 Return the "custom" value: Every rendition has 5 bits for use by
193 extensions. They can be set and changed as you like and are 655 extensions. They can be set and changed as you like and are
194 initially zero. 656 initially zero.
195 657
196 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 658 $rend = urxvt::SET_CUSTOM $rend, $new_value
197 Change the custom value. 659 Change the custom value.
198 660
661 The "urxvt::anyevent" Class
662 The sole purpose of this class is to deliver an interface to the
663 "AnyEvent" module - any module using it will work inside urxvt without
664 further programming. The only exception is that you cannot wait on
665 condition variables, but non-blocking condvar use is ok. What this means
666 is that you cannot use blocking APIs, but the non-blocking variant
667 should work.
668
199 The "urxvt::term" Class 669 The "urxvt::term" Class
670 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
671 Creates a new terminal, very similar as if you had started it with
672 system "$rxvtname, arg...". $envhashref must be a reference to a
673 %ENV-like hash which defines the environment of the new terminal.
674
675 Croaks (and probably outputs an error message) if the new instance
676 couldn't be created. Returns "undef" if the new instance didn't
677 initialise perl, and the terminal object otherwise. The "init" and
678 "start" hooks will be called before this call returns, and are free
679 to refer to global data (which is race free).
680
681 $term->destroy
682 Destroy the terminal object (close the window, free resources etc.).
683 Please note that rxvt will not exit as long as any event watchers
684 (timers, io watchers) are still active.
685
686 $term->exec_async ($cmd[, @args])
687 Works like the combination of the "fork"/"exec" builtins, which
688 executes ("starts") programs in the background. This function takes
689 care of setting the user environment before exec'ing the command
690 (e.g. "PATH") and should be preferred over explicit calls to "exec"
691 or "system".
692
693 Returns the pid of the subprocess or "undef" on error.
694
695 $isset = $term->option ($optval[, $set])
696 Returns true if the option specified by $optval is enabled, and
697 optionally change it. All option values are stored by name in the
698 hash %urxvt::OPTION. Options not enabled in this binary are not in
699 the hash.
700
701 Here is a a likely non-exhaustive list of option names, please see
702 the source file /src/optinc.h to see the actual list:
703
704 borderLess console cursorBlink cursorUnderline hold iconic insecure
705 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
706 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
707 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
708 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
709 transparent tripleclickwords utmpInhibit visualBell
710
200 $value = $term->resource ($name[, $newval]) 711 $value = $term->resource ($name[, $newval])
201 Returns the current resource value associated with a given name and 712 Returns the current resource value associated with a given name and
202 optionally sets a new value. Setting values is most useful in the 713 optionally sets a new value. Setting values is most useful in the
203 "init" hook. Unset resources are returned and accepted as "undef". 714 "init" hook. Unset resources are returned and accepted as "undef".
204 715
… …
213 Please note that resource strings will currently only be freed when 724 Please note that resource strings will currently only be freed when
214 the terminal is destroyed, so changing options frequently will eat 725 the terminal is destroyed, so changing options frequently will eat
215 memory. 726 memory.
216 727
217 Here is a a likely non-exhaustive list of resource names, not all of 728 Here is a a likely non-exhaustive list of resource names, not all of
218 which are supported in every build, please see the source to see the 729 which are supported in every build, please see the source file
219 actual list: 730 /src/rsinc.h to see the actual list:
220 731
221 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 732 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
222 borderLess color cursorBlink cursorUnderline cutchars delete_key 733 borderLess color cursorBlink cursorUnderline cutchars delete_key
223 display_name embed ext_bwidth fade font geometry hold iconName 734 display_name embed ext_bwidth fade font geometry hold iconName
224 imFont imLocale inputMethod insecure int_bwidth intensityStyles 735 imFont imLocale inputMethod insecure int_bwidth intensityStyles
225 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 736 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
226 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 737 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
227 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 738 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
228 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 739 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
229 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 740 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
230 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 741 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
742 secondaryScreen secondaryScroll selectstyle shade term_name title
231 shade term_name title transparent transparent_all tripleclickwords 743 transient_for transparent transparent_all tripleclickwords utmpInhibit
232 utmpInhibit visualBell 744 visualBell
745
746 $value = $term->x_resource ($pattern)
747 Returns the X-Resource for the given pattern, excluding the program
748 or class name, i.e. "$term->x_resource ("boldFont")" should return
749 the same value as used by this instance of rxvt-unicode. Returns
750 "undef" if no resource with that pattern exists.
751
752 This method should only be called during the "on_start" hook, as
753 there is only one resource database per display, and later
754 invocations might return the wrong resources.
755
756 $success = $term->parse_keysym ($keysym_spec, $command_string)
757 Adds a keymap translation exactly as specified via a resource. See
758 the "keysym" resource in the rxvt(1) manpage.
759
760 $rend = $term->rstyle ([$new_rstyle])
761 Return and optionally change the current rendition. Text that is
762 output by the terminal application will use this style.
763
764 ($row, $col) = $term->screen_cur ([$row, $col])
765 Return the current coordinates of the text cursor position and
766 optionally set it (which is usually bad as applications don't expect
767 that).
233 768
234 ($row, $col) = $term->selection_mark ([$row, $col]) 769 ($row, $col) = $term->selection_mark ([$row, $col])
235 ($row, $col) = $term->selection_beg ([$row, $col]) 770 ($row, $col) = $term->selection_beg ([$row, $col])
236 ($row, $col) = $term->selection_end ([$row, $col]) 771 ($row, $col) = $term->selection_end ([$row, $col])
237 Return the current values of the selection mark, begin or end 772 Return the current values of the selection mark, begin or end
238 positions, and optionally set them to new values. 773 positions, and optionally set them to new values.
239 774
775 $term->selection_make ($eventtime[, $rectangular])
776 Tries to make a selection as set by "selection_beg" and
777 "selection_end". If $rectangular is true (default: false), a
778 rectangular selection will be made. This is the prefered function to
779 make a selection.
780
240 $success = $term->selection_grab ($eventtime) 781 $success = $term->selection_grab ($eventtime)
241 Try to request the primary selection from the server (for example, 782 Try to request the primary selection text from the server (for
242 as set by the next method). 783 example, as set by the next method). No visual feedback will be
784 given. This function is mostly useful from within "on_sel_grab"
785 hooks.
243 786
244 $oldtext = $term->selection ([$newtext]) 787 $oldtext = $term->selection ([$newtext])
245 Return the current selection text and optionally replace it by 788 Return the current selection text and optionally replace it by
246 $newtext. 789 $newtext.
247 790
248 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 791 $term->overlay_simple ($x, $y, $text)
249 overlay box. See the next method for details. # #=cut 792 Create a simple multi-line overlay box. See the next method for
250 793 details.
251 sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;
252
253 my @lines = split /\n/, $text;
254
255 my $w = 0;
256 for (map $self->strwidth ($_), @lines) {
257 $w = $_ if $w < $_;
258 }
259
260 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
261 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
262 }
263 794
264 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 795 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
265 Create a new (empty) overlay at the given position with the given 796 Create a new (empty) overlay at the given position with the given
266 width/height. $rstyle defines the initial rendition style (default: 797 width/height. $rstyle defines the initial rendition style (default:
267 "OVERLAY_RSTYLE"). 798 "OVERLAY_RSTYLE").
… …
273 right/bottom side, respectively. 804 right/bottom side, respectively.
274 805
275 This method returns an urxvt::overlay object. The overlay will be 806 This method returns an urxvt::overlay object. The overlay will be
276 visible as long as the perl object is referenced. 807 visible as long as the perl object is referenced.
277 808
278 Currently, the only method on the "urxvt::overlay" object is "set": 809 The methods currently supported on "urxvt::overlay" objects are:
279 810
280 $overlay->set ($x, $y, $text, $rend) 811 $overlay->set ($x, $y, $text, $rend)
281 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts text in 812 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
282 rxvt-unicode's special encoding and an array of rendition values at 813 text in rxvt-unicode's special encoding and an array of
283 a specific position inside the overlay. 814 rendition values at a specific position inside the overlay.
284 815
816 $overlay->hide
817 If visible, hide the overlay, but do not destroy it.
818
819 $overlay->show
820 If hidden, display the overlay again.
821
822 $popup = $term->popup ($event)
823 Creates a new "urxvt::popup" object that implements a popup menu.
824 The $event *must* be the event causing the menu to pop up (a button
825 event, currently).
826
285 $cellwidth = $term->strwidth $string 827 $cellwidth = $term->strwidth ($string)
286 Returns the number of screen-cells this string would need. Correctly 828 Returns the number of screen-cells this string would need. Correctly
287 accounts for wide and combining characters. 829 accounts for wide and combining characters.
288 830
289 $octets = $term->locale_encode $string 831 $octets = $term->locale_encode ($string)
290 Convert the given text string into the corresponding locale 832 Convert the given text string into the corresponding locale
291 encoding. 833 encoding.
292 834
293 $string = $term->locale_decode $octets 835 $string = $term->locale_decode ($octets)
294 Convert the given locale-encoded octets into a perl string. 836 Convert the given locale-encoded octets into a perl string.
837
838 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
839 XORs the rendition values in the given span with the provided value
840 (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful
841 in refresh hooks to provide effects similar to the selection.
842
843 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
844 $rstyle2]])
845 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
846 whitespace will additionally be xored with the $rstyle2, which
847 defaults to "RS_RVid | RS_Uline", which removes reverse video again
848 and underlines it instead. Both styles *MUST NOT* contain font
849 styles.
850
851 $term->scr_bell
852 Ring the bell!
853
854 $term->scr_add_lines ($string)
855 Write the given text string to the screen, as if output by the
856 application running inside the terminal. It may not contain command
857 sequences (escape codes), but is free to use line feeds, carriage
858 returns and tabs. The string is a normal text string, not in
859 locale-dependent encoding.
860
861 Normally its not a good idea to use this function, as programs might
862 be confused by changes in cursor position or scrolling. Its useful
863 inside a "on_add_lines" hook, though.
864
865 $term->scr_change_screen ($screen)
866 Switch to given screen - 0 primary, 1 secondary.
867
868 $term->cmd_parse ($octets)
869 Similar to "scr_add_lines", but the argument must be in the
870 locale-specific encoding of the terminal and can contain command
871 sequences (escape codes) that will be interpreted.
295 872
296 $term->tt_write ($octets) 873 $term->tt_write ($octets)
297 Write the octets given in $data to the tty (i.e. as program input). 874 Write the octets given in $data to the tty (i.e. as program input).
298 To pass characters instead of octets, you should convert your 875 To pass characters instead of octets, you should convert your
299 strings first to the locale-specific encoding using 876 strings first to the locale-specific encoding using
300 "$term->locale_encode". 877 "$term->locale_encode".
301 878
879 $old_events = $term->pty_ev_events ([$new_events])
880 Replaces the event mask of the pty watcher by the given event mask.
881 Can be used to suppress input and output handling to the pty/tty.
882 See the description of "urxvt::timer->events". Make sure to always
883 restore the previous value.
884
885 $fd = $term->pty_fd
886 Returns the master file descriptor for the pty in use, or -1 if no
887 pty is used.
888
889 $windowid = $term->parent
890 Return the window id of the toplevel window.
891
892 $windowid = $term->vt
893 Return the window id of the terminal window.
894
895 $term->vt_emask_add ($x_event_mask)
896 Adds the specified events to the vt event mask. Useful e.g. when you
897 want to receive pointer events all the times:
898
899 $term->vt_emask_add (urxvt::PointerMotionMask);
900
901 $term->focus_in
902 $term->focus_out
903 $term->key_press ($state, $keycode[, $time])
904 $term->key_release ($state, $keycode[, $time])
905 Deliver various fake events to to terminal.
906
907 $window_width = $term->width
908 $window_height = $term->height
909 $font_width = $term->fwidth
910 $font_height = $term->fheight
911 $font_ascent = $term->fbase
302 $nrow = $term->nrow 912 $terminal_rows = $term->nrow
303 $ncol = $term->ncol 913 $terminal_columns = $term->ncol
304 Return the number of rows/columns of the terminal window (i.e. as 914 $has_focus = $term->focus
305 specified by "-geometry", excluding any scrollback). 915 $is_mapped = $term->mapped
916 $max_scrollback = $term->saveLines
917 $nrow_plus_saveLines = $term->total_rows
918 $topmost_scrollback_row = $term->top_row
919 Return various integers describing terminal characteristics.
306 920
921 $x_display = $term->display_id
922 Return the DISPLAY used by rxvt-unicode.
923
924 $lc_ctype = $term->locale
925 Returns the LC_CTYPE category string used by this rxvt-unicode.
926
307 $nsaved = $term->nsaved 927 $env = $term->env
308 Returns the number of lines in the scrollback buffer. 928 Returns a copy of the environment in effect for the terminal as a
929 hashref similar to "\%ENV".
930
931 @envv = $term->envv
932 Returns the environment as array of strings of the form "VAR=VALUE".
933
934 @argv = $term->argv
935 Return the argument vector as this terminal, similar to @ARGV, but
936 includes the program name as first element.
937
938 $modifiermask = $term->ModLevel3Mask
939 $modifiermask = $term->ModMetaMask
940 $modifiermask = $term->ModNumLockMask
941 Return the modifier masks corresponding to the "ISO Level 3 Shift"
942 (often AltGr), the meta key (often Alt) and the num lock key, if
943 applicable.
944
945 $screen = $term->current_screen
946 Returns the currently displayed screen (0 primary, 1 secondary).
947
948 $cursor_is_hidden = $term->hidden_cursor
949 Returns wether the cursor is currently hidden or not.
309 950
310 $view_start = $term->view_start ([$newvalue]) 951 $view_start = $term->view_start ([$newvalue])
311 Returns the negative row number of the topmost line. Minimum value 952 Returns the row number of the topmost displayed line. Maximum value
312 is 0, which displays the normal terminal contents. Larger values 953 is 0, which displays the normal terminal contents. Lower values
313 scroll this many lines into the scrollback buffer. 954 scroll this many lines into the scrollback buffer.
314 955
315 $term->want_refresh 956 $term->want_refresh
316 Requests a screen refresh. At the next opportunity, rxvt-unicode 957 Requests a screen refresh. At the next opportunity, rxvt-unicode
317 will compare the on-screen display with its stored representation. 958 will compare the on-screen display with its stored representation.
… …
321 962
322 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 963 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
323 Returns the text of the entire row with number $row_number. Row 0 is 964 Returns the text of the entire row with number $row_number. Row 0 is
324 the topmost terminal line, row "$term->$ncol-1" is the bottommost 965 the topmost terminal line, row "$term->$ncol-1" is the bottommost
325 terminal line. The scrollback buffer starts at line -1 and extends 966 terminal line. The scrollback buffer starts at line -1 and extends
326 to line "-$term->nsaved". 967 to line "-$term->nsaved". Nothing will be returned if a nonexistent
968 line is requested.
327 969
328 If $new_text is specified, it will replace characters in the current 970 If $new_text is specified, it will replace characters in the current
329 line, starting at column $start_col (default 0), which is useful to 971 line, starting at column $start_col (default 0), which is useful to
330 replace only parts of a line. The font index in the rendition will 972 replace only parts of a line. The font index in the rendition will
331 automatically be updated. 973 automatically be updated.
332 974
333 $text is in a special encoding: tabs and wide characters that use 975 $text is in a special encoding: tabs and wide characters that use
334 more than one cell when displayed are padded with urxvt::NOCHAR 976 more than one cell when displayed are padded with $urxvt::NOCHAR
335 characters ("chr 65535"). Characters with combining characters and 977 (chr 65535) characters. Characters with combining characters and
336 other characters that do not fit into the normal tetx encoding will 978 other characters that do not fit into the normal tetx encoding will
337 be replaced with characters in the private use area. 979 be replaced with characters in the private use area.
338 980
339 You have to obey this encoding when changing text. The advantage is 981 You have to obey this encoding when changing text. The advantage is
340 that "substr" and similar functions work on screen cells and not on 982 that "substr" and similar functions work on screen cells and not on
… …
352 994
353 See the section on RENDITION, above. 995 See the section on RENDITION, above.
354 996
355 $length = $term->ROW_l ($row_number[, $new_length]) 997 $length = $term->ROW_l ($row_number[, $new_length])
356 Returns the number of screen cells that are in use ("the line 998 Returns the number of screen cells that are in use ("the line
357 length"). If it is -1, then the line is part of a multiple-row 999 length"). Unlike the urxvt core, this returns "$term->ncol" if the
358 logical "line", which means all characters are in use and it is 1000 line is joined with the following one.
359 continued on the next row. 1001
1002 $bool = $term->is_longer ($row_number)
1003 Returns true if the row is part of a multiple-row logical "line"
1004 (i.e. joined with the following row), which means all characters are
1005 in use and it is continued on the next row (and possibly a
1006 continuation of the previous row(s)).
1007
1008 $line = $term->line ($row_number)
1009 Create and return a new "urxvt::line" object that stores information
1010 about the logical line that row $row_number is part of. It supports
1011 the following methods:
1012
1013 $text = $line->t ([$new_text])
1014 Returns or replaces the full text of the line, similar to
1015 "ROW_t"
1016
1017 $rend = $line->r ([$new_rend])
1018 Returns or replaces the full rendition array of the line,
1019 similar to "ROW_r"
1020
1021 $length = $line->l
1022 Returns the length of the line in cells, similar to "ROW_l".
1023
1024 $rownum = $line->beg
1025 $rownum = $line->end
1026 Return the row number of the first/last row of the line,
1027 respectively.
1028
1029 $offset = $line->offset_of ($row, $col)
1030 Returns the character offset of the given row|col pair within
1031 the logical line. Works for rows outside the line, too, and
1032 returns corresponding offsets outside the string.
1033
1034 ($row, $col) = $line->coord_of ($offset)
1035 Translates a string offset into terminal coordinates again.
360 1036
361 $text = $term->special_encode $string 1037 $text = $term->special_encode $string
362 Converts a perl string into the special encoding used by 1038 Converts a perl string into the special encoding used by
363 rxvt-unicode, where one character corresponds to one screen cell. 1039 rxvt-unicode, where one character corresponds to one screen cell.
364 See "$term->ROW_t" for details. 1040 See "$term->ROW_t" for details.
365 1041
366 $string = $term->special_decode $text 1042 $string = $term->special_decode $text
367 Converts rxvt-unicodes text reprsentation into a perl string. See 1043 Converts rxvt-unicodes text reprsentation into a perl string. See
368 "$term->ROW_t" for details. 1044 "$term->ROW_t" for details.
1045
1046 $success = $term->grab_button ($button, $modifiermask[, $window =
1047 $term->vt])
1048 $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1049 Register/unregister a synchronous button grab. See the XGrabButton
1050 manpage.
1051
1052 $success = $term->grab ($eventtime[, $sync])
1053 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1054 synchronous ($sync is true). Also remembers the grab timestampe.
1055
1056 $term->allow_events_async
1057 Calls XAllowEvents with AsyncBoth for the most recent grab.
1058
1059 $term->allow_events_sync
1060 Calls XAllowEvents with SyncBoth for the most recent grab.
1061
1062 $term->allow_events_replay
1063 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
1064 the most recent grab.
1065
1066 $term->ungrab
1067 Calls XUngrab for the most recent grab. Is called automatically on
1068 evaluation errors, as it is better to lose the grab in the error
1069 case as the session.
1070
1071 $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1072 $atom_name = $term->XGetAtomName ($atom)
1073 @atoms = $term->XListProperties ($window)
1074 ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1075 $term->XChangeWindowProperty ($window, $property, $type, $format,
1076 $octets)
1077 $term->XDeleteProperty ($window, $property)
1078 $window = $term->DefaultRootWindow
1079 $term->XReparentWindow ($window, $parent, [$x, $y])
1080 $term->XMapWindow ($window)
1081 $term->XUnmapWindow ($window)
1082 $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1083 ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
1084 $y)
1085 $term->XChangeInput ($window, $add_events[, $del_events])
1086 Various X or X-related functions. The $term object only serves as
1087 the source of the display, otherwise those functions map
1088 more-or-less directory onto the X functions of the same name.
1089
1090 The "urxvt::popup" Class
1091 $popup->add_title ($title)
1092 Adds a non-clickable title to the popup.
1093
1094 $popup->add_separator ([$sepchr])
1095 Creates a separator, optionally using the character given as
1096 $sepchr.
1097
1098 $popup->add_button ($text, $cb)
1099 Adds a clickable button to the popup. $cb is called whenever it is
1100 selected.
1101
1102 $popup->add_toggle ($text, $initial_value, $cb)
1103 Adds a toggle/checkbox item to the popup. The callback gets called
1104 whenever it gets toggled, with a boolean indicating its new value as
1105 its first argument.
1106
1107 $popup->show
1108 Displays the popup (which is initially hidden).
369 1109
370 The "urxvt::timer" Class 1110 The "urxvt::timer" Class
371 This class implements timer watchers/events. Time is represented as a 1111 This class implements timer watchers/events. Time is represented as a
372 fractional number of seconds since the epoch. Example: 1112 fractional number of seconds since the epoch. Example:
373 1113
… …
402 Start the timer. 1142 Start the timer.
403 1143
404 $timer = $timer->start ($tstamp) 1144 $timer = $timer->start ($tstamp)
405 Set the event trigger time to $tstamp and start the timer. 1145 Set the event trigger time to $tstamp and start the timer.
406 1146
1147 $timer = $timer->after ($delay)
1148 Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
1149
407 $timer = $timer->stop 1150 $timer = $timer->stop
408 Stop the timer. 1151 Stop the timer.
409 1152
410 The "urxvt::iow" Class 1153 The "urxvt::iow" Class
411 This class implements io watchers/events. Example: 1154 This class implements io watchers/events. Example:
412 1155
413 $term->{socket} = ... 1156 $term->{socket} = ...
414 $term->{iow} = urxvt::iow 1157 $term->{iow} = urxvt::iow
415 ->new 1158 ->new
416 ->fd (fileno $term->{socket}) 1159 ->fd (fileno $term->{socket})
417 ->events (1) # wait for read data 1160 ->events (urxvt::EVENT_READ)
418 ->start 1161 ->start
419 ->cb (sub { 1162 ->cb (sub {
420 my ($iow, $revents) = @_; 1163 my ($iow, $revents) = @_;
421 # $revents must be 1 here, no need to check 1164 # $revents must be 1 here, no need to check
422 sysread $term->{socket}, my $buf, 8192 1165 sysread $term->{socket}, my $buf, 8192
… …
432 1175
433 $iow = $iow->fd ($fd) 1176 $iow = $iow->fd ($fd)
434 Set the filedescriptor (not handle) to watch. 1177 Set the filedescriptor (not handle) to watch.
435 1178
436 $iow = $iow->events ($eventmask) 1179 $iow = $iow->events ($eventmask)
437 Set the event mask to watch. Bit #0 (value 1) enables watching for 1180 Set the event mask to watch. The only allowed values are
438 read data, Bit #1 (value 2) enables watching for write data. 1181 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
1182 together, or "urxvt::EVENT_NONE".
439 1183
440 $iow = $iow->start 1184 $iow = $iow->start
441 Start watching for requested events on the given handle. 1185 Start watching for requested events on the given handle.
442 1186
443 $iow = $iow->stop 1187 $iow = $iow->stop
444 Stop watching for events on the given filehandle. 1188 Stop watching for events on the given filehandle.
1189
1190 The "urxvt::iw" Class
1191 This class implements idle watchers, that get called automatically when
1192 the process is idle. They should return as fast as possible, after doing
1193 some useful work.
1194
1195 $iw = new urxvt::iw
1196 Create a new idle watcher object in stopped state.
1197
1198 $iw = $iw->cb (sub { my ($iw) = @_; ... })
1199 Set the callback to be called when the watcher triggers.
1200
1201 $timer = $timer->start
1202 Start the watcher.
1203
1204 $timer = $timer->stop
1205 Stop the watcher.
1206
1207 The "urxvt::pw" Class
1208 This class implements process watchers. They create an event whenever a
1209 process exits, after which they stop automatically.
1210
1211 my $pid = fork;
1212 ...
1213 $term->{pw} = urxvt::pw
1214 ->new
1215 ->start ($pid)
1216 ->cb (sub {
1217 my ($pw, $exit_status) = @_;
1218 ...
1219 });
1220
1221 $pw = new urxvt::pw
1222 Create a new process watcher in stopped state.
1223
1224 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1225 Set the callback to be called when the timer triggers.
1226
1227 $pw = $timer->start ($pid)
1228 Tells the wqtcher to start watching for process $pid.
1229
1230 $pw = $pw->stop
1231 Stop the watcher.
445 1232
446ENVIRONMENT 1233ENVIRONMENT
447 URXVT_PERL_VERBOSITY 1234 URXVT_PERL_VERBOSITY
448 This variable controls the verbosity level of the perl extension. Higher 1235 This variable controls the verbosity level of the perl extension. Higher
449 numbers indicate more verbose output. 1236 numbers indicate more verbose output.
450 1237
451 0 - only fatal messages 1238 == 0 - fatal messages
452 3 - script loading and management 1239 >= 3 - script loading and management
453 10 - all events received 1240 >=10 - all called hooks
1241 >=11 - hook reutrn values
454 1242
455AUTHOR 1243AUTHOR
456 Marc Lehmann <pcg@goof.com> 1244 Marc Lehmann <pcg@goof.com>
457 http://software.schmorp.de/pkg/rxvt-unicode 1245 http://software.schmorp.de/pkg/rxvt-unicode
458 1246

Diff Legend

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