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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines