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

Comparing rxvt-unicode/doc/rxvtperl.3.man.in (file contents):
Revision 1.14 by root, Sat Jan 7 04:19:43 2006 UTC vs.
Revision 1.15 by root, Sun Jan 8 00:20:12 2006 UTC

… …
127.\} 127.\}
128.rm #[ #] #H #V #F C 128.rm #[ #] #H #V #F C
129.\" ======================================================================== 129.\" ========================================================================
130.\" 130.\"
131.IX Title "rxvt 3" 131.IX Title "rxvt 3"
132.TH rxvt 3 "2006-01-07" "6.3" "RXVT-UNICODE" 132.TH rxvt 3 "2006-01-08" "6.3" "RXVT-UNICODE"
133.SH "NAME" 133.SH "NAME"
134@@RXVT_NAME@@perl \- rxvt\-unicode's embedded perl interpreter 134@@RXVT_NAME@@perl \- rxvt\-unicode's embedded perl interpreter
135.SH "SYNOPSIS" 135.SH "SYNOPSIS"
136.IX Header "SYNOPSIS" 136.IX Header "SYNOPSIS"
137.Vb 1 137.Vb 1
… …
152.Vb 1 152.Vb 1
153\& @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 153\& @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
154.Ve 154.Ve
155.SH "DESCRIPTION" 155.SH "DESCRIPTION"
156.IX Header "DESCRIPTION" 156.IX Header "DESCRIPTION"
157Everytime a terminal object gets created, scripts specified via the 157Everytime a terminal object gets created, extension scripts specified via
158\&\f(CW\*(C`perl\*(C'\fR resource are loaded and associated with it. 158the \f(CW\*(C`perl\*(C'\fR resource are loaded and associated with it.
159.PP 159.PP
160Scripts are compiled in a 'use strict' and 'use utf8' environment, and 160Scripts are compiled in a 'use strict' and 'use utf8' environment, and
161thus must be encoded as \s-1UTF\-8\s0. 161thus must be encoded as \s-1UTF\-8\s0.
162.PP 162.PP
163Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 163Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
… …
239.IX Subsection "Hooks" 239.IX Subsection "Hooks"
240The following subroutines can be declared in extension files, and will be 240The following subroutines can be declared in extension files, and will be
241called whenever the relevant event happens. 241called whenever the relevant event happens.
242.PP 242.PP
243The first argument passed to them is an object private to each terminal 243The first argument passed to them is an object private to each terminal
244and extension package. You can call all \f(CW\*(C`urxvt::term\*(C'\fR methods on it, but 244and extension package. You can call all \f(CW\*(C`urxvt::term\*(C'\fR methods on it, but
245its not a real \f(CW\*(C`urxvt::term\*(C'\fR object. Instead, the real \f(CW\*(C`urxvt::term\*(C'\fR 245its not a real \f(CW\*(C`urxvt::term\*(C'\fR object. Instead, the real \f(CW\*(C`urxvt::term\*(C'\fR
246object that is shared between all packages is stored in the \f(CW\*(C`term\*(C'\fR 246object that is shared between all packages is stored in the \f(CW\*(C`term\*(C'\fR
247member. 247member. It is, however, blessed intot he package of the extension script,
248so for all practical purposes you can treat an extension script as a class.
248.PP 249.PP
249All of them must return a boolean value. If it is true, then the event 250All of them must return a boolean value. If it is true, then the event
250counts as being \fIconsumed\fR, and the invocation of other hooks is skipped, 251counts as being \fIconsumed\fR, and the invocation of other hooks is skipped,
251and the relevant action might not be carried out by the \*(C+ code. 252and the relevant action might not be carried out by the \*(C+ code.
252.PP 253.PP
… …
294click) and is either supposed to return false (normal operation), or 295click) and is either supposed to return false (normal operation), or
295should extend the selection itelf and return true to suppress the built-in 296should extend the selection itelf and return true to suppress the built-in
296processing. 297processing.
297.Sp 298.Sp
298See the \fIselection\fR example extension. 299See the \fIselection\fR example extension.
299.ie n .IP "on_focus_in $term" 4
300.el .IP "on_focus_in \f(CW$term\fR" 4
301.IX Item "on_focus_in $term"
302Called whenever the window gets the keyboard focus, before urxvt does
303focus in processing.
304.ie n .IP "on_focus_out $term" 4
305.el .IP "on_focus_out \f(CW$term\fR" 4
306.IX Item "on_focus_out $term"
307Called wheneever the window loses keyboard focus, before urxvt does focus
308out processing.
309.ie n .IP "on_view_change $term\fR, \f(CW$offset" 4 300.ie n .IP "on_view_change $term\fR, \f(CW$offset" 4
310.el .IP "on_view_change \f(CW$term\fR, \f(CW$offset\fR" 4 301.el .IP "on_view_change \f(CW$term\fR, \f(CW$offset\fR" 4
311.IX Item "on_view_change $term, $offset" 302.IX Item "on_view_change $term, $offset"
312Called whenever the view offset changes, i..e the user or program 303Called whenever the view offset changes, i..e the user or program
313scrolls. Offset \f(CW0\fR means display the normal terminal, positive values 304scrolls. Offset \f(CW0\fR means display the normal terminal, positive values
… …
376.el .IP "on_keyboard_command \f(CW$term\fR, \f(CW$string\fR" 4 367.el .IP "on_keyboard_command \f(CW$term\fR, \f(CW$string\fR" 4
377.IX Item "on_keyboard_command $term, $string" 368.IX Item "on_keyboard_command $term, $string"
378Called whenever the user presses a key combination that has a 369Called whenever the user presses a key combination that has a
379\&\f(CW\*(C`perl:string\*(C'\fR action bound to it (see description of the \fBkeysym\fR 370\&\f(CW\*(C`perl:string\*(C'\fR action bound to it (see description of the \fBkeysym\fR
380resource in the @@RXVT_NAME@@(1) manpage). 371resource in the @@RXVT_NAME@@(1) manpage).
372.ie n .IP "on_focus_in $term" 4
373.el .IP "on_focus_in \f(CW$term\fR" 4
374.IX Item "on_focus_in $term"
375Called whenever the window gets the keyboard focus, before rxvt-unicode
376does focus in processing.
377.ie n .IP "on_focus_out $term" 4
378.el .IP "on_focus_out \f(CW$term\fR" 4
379.IX Item "on_focus_out $term"
380Called wheneever the window loses keyboard focus, before rxvt-unicode does
381focus out processing.
381.ie n .IP "on_key_press $term\fR, \f(CW$event\fR, \f(CW$octets" 4 382.ie n .IP "on_key_press $term\fR, \f(CW$event\fR, \f(CW$octets" 4
382.el .IP "on_key_press \f(CW$term\fR, \f(CW$event\fR, \f(CW$octets\fR" 4 383.el .IP "on_key_press \f(CW$term\fR, \f(CW$event\fR, \f(CW$octets\fR" 4
383.IX Item "on_key_press $term, $event, $octets" 384.IX Item "on_key_press $term, $event, $octets"
384.PD 0 385.PD 0
385.ie n .IP "on_key_release $term\fR, \f(CW$event" 4 386.ie n .IP "on_key_release $term\fR, \f(CW$event" 4
… …
392.el .IP "on_button_release \f(CW$term\fR, \f(CW$event\fR" 4 393.el .IP "on_button_release \f(CW$term\fR, \f(CW$event\fR" 4
393.IX Item "on_button_release $term, $event" 394.IX Item "on_button_release $term, $event"
394.ie n .IP "on_motion_notify $term\fR, \f(CW$event" 4 395.ie n .IP "on_motion_notify $term\fR, \f(CW$event" 4
395.el .IP "on_motion_notify \f(CW$term\fR, \f(CW$event\fR" 4 396.el .IP "on_motion_notify \f(CW$term\fR, \f(CW$event\fR" 4
396.IX Item "on_motion_notify $term, $event" 397.IX Item "on_motion_notify $term, $event"
398.ie n .IP "on_map_notify $term\fR, \f(CW$event" 4
399.el .IP "on_map_notify \f(CW$term\fR, \f(CW$event\fR" 4
400.IX Item "on_map_notify $term, $event"
401.ie n .IP "on_unmap_notify $term\fR, \f(CW$event" 4
402.el .IP "on_unmap_notify \f(CW$term\fR, \f(CW$event\fR" 4
403.IX Item "on_unmap_notify $term, $event"
397.PD 404.PD
398Called whenever the corresponding X event is received for the terminal If 405Called whenever the corresponding X event is received for the terminal If
399the hook returns true, then the even will be ignored by rxvt\-unicode. 406the hook returns true, then the even will be ignored by rxvt\-unicode.
400.Sp 407.Sp
401The event is a hash with most values as named by Xlib (see the XEvent 408The event is a hash with most values as named by Xlib (see the XEvent
… …
439Using this function has the advantage that its output ends up in the 446Using this function has the advantage that its output ends up in the
440correct place, e.g. on stderr of the connecting urxvtc client. 447correct place, e.g. on stderr of the connecting urxvtc client.
441.IP "$time = urxvt::NOW" 4 448.IP "$time = urxvt::NOW" 4
442.IX Item "$time = urxvt::NOW" 449.IX Item "$time = urxvt::NOW"
443Returns the \*(L"current time\*(R" (as per the event loop). 450Returns the \*(L"current time\*(R" (as per the event loop).
451.IP "urxvt::CurrentTime" 4
452.IX Item "urxvt::CurrentTime"
453.PD 0
454.IP "urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, AnyModifier" 4
455.IX Item "urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, AnyModifier"
456.PD
457Various constants for use in X events.
444.Sh "\s-1RENDITION\s0" 458.Sh "\s-1RENDITION\s0"
445.IX Subsection "RENDITION" 459.IX Subsection "RENDITION"
446Rendition bitsets contain information about colour, font, font styles and 460Rendition bitsets contain information about colour, font, font styles and
447similar information for each screen cell. 461similar information for each screen cell.
448.PP 462.PP
… …
494.el .Sh "The \f(CWurxvt::term\fP Class" 508.el .Sh "The \f(CWurxvt::term\fP Class"
495.IX Subsection "The urxvt::term Class" 509.IX Subsection "The urxvt::term Class"
496.IP "$term\->destroy" 4 510.IP "$term\->destroy" 4
497.IX Item "$term->destroy" 511.IX Item "$term->destroy"
498Destroy the terminal object (close the window, free resources etc.). 512Destroy the terminal object (close the window, free resources etc.).
513.ie n .IP "$isset = $term\fR\->option ($optval[, \f(CW$set])" 4
514.el .IP "$isset = \f(CW$term\fR\->option ($optval[, \f(CW$set\fR])" 4
515.IX Item "$isset = $term->option ($optval[, $set])"
516Returns true if the option specified by \f(CW$optval\fR is enabled, and
517optionally change it. All option values are stored by name in the hash
518\&\f(CW%urxvt::OPTION\fR. Options not enabled in this binary are not in the hash.
519.Sp
520Here is a a likely non-exhaustive list of option names, please see the
521source file \fI/src/optinc.h\fR to see the actual list:
522.Sp
523.Vb 6
524\& borderLess console cursorBlink cursorUnderline hold iconic insecure
525\& intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
526\& pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
527\& scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
528\& secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
529\& tripleclickwords utmpInhibit visualBell
530.Ve
499.ie n .IP "$value = $term\fR\->resource ($name[, \f(CW$newval])" 4 531.ie n .IP "$value = $term\fR\->resource ($name[, \f(CW$newval])" 4
500.el .IP "$value = \f(CW$term\fR\->resource ($name[, \f(CW$newval\fR])" 4 532.el .IP "$value = \f(CW$term\fR\->resource ($name[, \f(CW$newval\fR])" 4
501.IX Item "$value = $term->resource ($name[, $newval])" 533.IX Item "$value = $term->resource ($name[, $newval])"
502Returns the current resource value associated with a given name and 534Returns the current resource value associated with a given name and
503optionally sets a new value. Setting values is most useful in the \f(CW\*(C`init\*(C'\fR 535optionally sets a new value. Setting values is most useful in the \f(CW\*(C`init\*(C'\fR
… …
513.Sp 545.Sp
514Please note that resource strings will currently only be freed when the 546Please note that resource strings will currently only be freed when the
515terminal is destroyed, so changing options frequently will eat memory. 547terminal is destroyed, so changing options frequently will eat memory.
516.Sp 548.Sp
517Here is a a likely non-exhaustive list of resource names, not all of which 549Here is a a likely non-exhaustive list of resource names, not all of which
518are supported in every build, please see the source to see the actual 550are supported in every build, please see the source file \fI/src/rsinc.h\fR
519list: 551to see the actual list:
520.Sp 552.Sp
521.Vb 12 553.Vb 12
522\& answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 554\& answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
523\& borderLess color cursorBlink cursorUnderline cutchars delete_key 555\& borderLess color cursorBlink cursorUnderline cutchars delete_key
524\& display_name embed ext_bwidth fade font geometry hold iconName 556\& display_name embed ext_bwidth fade font geometry hold iconName
… …
615.IX Item "$overlay->show" 647.IX Item "$overlay->show"
616If hidden, display the overlay again. 648If hidden, display the overlay again.
617.RE 649.RE
618.RS 4 650.RS 4
619.RE 651.RE
652.ie n .IP "$popup = $term\->popup ($event)" 4
653.el .IP "$popup = \f(CW$term\fR\->popup ($event)" 4
654.IX Item "$popup = $term->popup ($event)"
655Creates a new \f(CW\*(C`urxvt::popup\*(C'\fR object that implements a popup menu. The
656\&\f(CW$event\fR \fImust\fR be the event causing the menu to pop up (a button event,
657currently).
620.ie n .IP "$cellwidth = $term\->strwidth ($string)" 4 658.ie n .IP "$cellwidth = $term\->strwidth ($string)" 4
621.el .IP "$cellwidth = \f(CW$term\fR\->strwidth ($string)" 4 659.el .IP "$cellwidth = \f(CW$term\fR\->strwidth ($string)" 4
622.IX Item "$cellwidth = $term->strwidth ($string)" 660.IX Item "$cellwidth = $term->strwidth ($string)"
623Returns the number of screen-cells this string would need. Correctly 661Returns the number of screen-cells this string would need. Correctly
624accounts for wide and combining characters. 662accounts for wide and combining characters.
… …
695.ie n .IP "$lines_in_scrollback = $term\->nsaved" 4 733.ie n .IP "$lines_in_scrollback = $term\->nsaved" 4
696.el .IP "$lines_in_scrollback = \f(CW$term\fR\->nsaved" 4 734.el .IP "$lines_in_scrollback = \f(CW$term\fR\->nsaved" 4
697.IX Item "$lines_in_scrollback = $term->nsaved" 735.IX Item "$lines_in_scrollback = $term->nsaved"
698.PD 736.PD
699Return various integers describing terminal characteristics. 737Return various integers describing terminal characteristics.
738.ie n .IP "$modifiermask = $term\->ModLevel3Mask" 4
739.el .IP "$modifiermask = \f(CW$term\fR\->ModLevel3Mask" 4
740.IX Item "$modifiermask = $term->ModLevel3Mask"
741.PD 0
742.ie n .IP "$modifiermask = $term\->ModMetaMask" 4
743.el .IP "$modifiermask = \f(CW$term\fR\->ModMetaMask" 4
744.IX Item "$modifiermask = $term->ModMetaMask"
745.ie n .IP "$modifiermask = $term\->ModNumLockMask" 4
746.el .IP "$modifiermask = \f(CW$term\fR\->ModNumLockMask" 4
747.IX Item "$modifiermask = $term->ModNumLockMask"
748.PD
749Return the modifier masks corresponding to the \*(L"\s-1ISO\s0 Level 3 Shift\*(R" (often
750AltGr), the meta key (often Alt) and the num lock key, if applicable.
700.ie n .IP "$view_start = $term\->view_start ([$newvalue])" 4 751.ie n .IP "$view_start = $term\->view_start ([$newvalue])" 4
701.el .IP "$view_start = \f(CW$term\fR\->view_start ([$newvalue])" 4 752.el .IP "$view_start = \f(CW$term\fR\->view_start ([$newvalue])" 4
702.IX Item "$view_start = $term->view_start ([$newvalue])" 753.IX Item "$view_start = $term->view_start ([$newvalue])"
703Returns the negative row number of the topmost line. Minimum value is 754Returns the negative row number of the topmost line. Minimum value is
704\&\f(CW0\fR, which displays the normal terminal contents. Larger values scroll 755\&\f(CW0\fR, which displays the normal terminal contents. Larger values scroll
… …
808.ie n .IP "$string = $term\fR\->special_decode \f(CW$text" 4 859.ie n .IP "$string = $term\fR\->special_decode \f(CW$text" 4
809.el .IP "$string = \f(CW$term\fR\->special_decode \f(CW$text\fR" 4 860.el .IP "$string = \f(CW$term\fR\->special_decode \f(CW$text\fR" 4
810.IX Item "$string = $term->special_decode $text" 861.IX Item "$string = $term->special_decode $text"
811Converts rxvt-unicodes text reprsentation into a perl string. See 862Converts rxvt-unicodes text reprsentation into a perl string. See
812\&\f(CW\*(C`$term\->ROW_t\*(C'\fR for details. 863\&\f(CW\*(C`$term\->ROW_t\*(C'\fR for details.
864.ie n .Sh "The ""urxvt::popup"" Class"
865.el .Sh "The \f(CWurxvt::popup\fP Class"
866.IX Subsection "The urxvt::popup Class"
813.ie n .Sh "The ""urxvt::timer"" Class" 867.ie n .Sh "The ""urxvt::timer"" Class"
814.el .Sh "The \f(CWurxvt::timer\fP Class" 868.el .Sh "The \f(CWurxvt::timer\fP Class"
815.IX Subsection "The urxvt::timer Class" 869.IX Subsection "The urxvt::timer Class"
870.RS 4
816This class implements timer watchers/events. Time is represented as a 871This class implements timer watchers/events. Time is represented as a
817fractional number of seconds since the epoch. Example: 872fractional number of seconds since the epoch. Example:
818.PP 873.Sp
819.Vb 8 874.Vb 8
820\& $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 875\& $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
821\& $term->{timer} = urxvt::timer 876\& $term->{timer} = urxvt::timer
822\& ->new 877\& ->new
823\& ->interval (1) 878\& ->interval (1)
… …
858Set the event trigger time to \f(CW$tstamp\fR and start the timer. 913Set the event trigger time to \f(CW$tstamp\fR and start the timer.
859.ie n .IP "$timer = $timer\->stop" 4 914.ie n .IP "$timer = $timer\->stop" 4
860.el .IP "$timer = \f(CW$timer\fR\->stop" 4 915.el .IP "$timer = \f(CW$timer\fR\->stop" 4
861.IX Item "$timer = $timer->stop" 916.IX Item "$timer = $timer->stop"
862Stop the timer. 917Stop the timer.
918.RE
919.RS 4
863.ie n .Sh "The ""urxvt::iow"" Class" 920.ie n .Sh "The ""urxvt::iow"" Class"
864.el .Sh "The \f(CWurxvt::iow\fP Class" 921.el .Sh "The \f(CWurxvt::iow\fP Class"
865.IX Subsection "The urxvt::iow Class" 922.IX Subsection "The urxvt::iow Class"
866This class implements io watchers/events. Example: 923This class implements io watchers/events. Example:
867.PP 924.Sp
868.Vb 12 925.Vb 12
869\& $term->{socket} = ... 926\& $term->{socket} = ...
870\& $term->{iow} = urxvt::iow 927\& $term->{iow} = urxvt::iow
871\& ->new 928\& ->new
872\& ->fd (fileno $term->{socket}) 929\& ->fd (fileno $term->{socket})
… …
902Start watching for requested events on the given handle. 959Start watching for requested events on the given handle.
903.ie n .IP "$iow = $iow\->stop" 4 960.ie n .IP "$iow = $iow\->stop" 4
904.el .IP "$iow = \f(CW$iow\fR\->stop" 4 961.el .IP "$iow = \f(CW$iow\fR\->stop" 4
905.IX Item "$iow = $iow->stop" 962.IX Item "$iow = $iow->stop"
906Stop watching for events on the given filehandle. 963Stop watching for events on the given filehandle.
964.RE
965.RS 4
907.SH "ENVIRONMENT" 966.SH "ENVIRONMENT"
908.IX Header "ENVIRONMENT" 967.IX Header "ENVIRONMENT"
909.Sh "\s-1URXVT_PERL_VERBOSITY\s0" 968.Sh "\s-1URXVT_PERL_VERBOSITY\s0"
910.IX Subsection "URXVT_PERL_VERBOSITY" 969.IX Subsection "URXVT_PERL_VERBOSITY"
911This variable controls the verbosity level of the perl extension. Higher 970This variable controls the verbosity level of the perl extension. Higher
… …
915.PD 0 974.PD 0
916.IP "=3 \- script loading and management" 4 975.IP "=3 \- script loading and management" 4
917.IX Item "=3 - script loading and management" 976.IX Item "=3 - script loading and management"
918.IP "=10 \- all events received" 4 977.IP "=10 \- all events received" 4
919.IX Item "=10 - all events received" 978.IX Item "=10 - all events received"
979.RE
980.RS 4
920.PD 981.PD
921.SH "AUTHOR" 982.SH "AUTHOR"
922.IX Header "AUTHOR" 983.IX Header "AUTHOR"
923.Vb 2 984.Vb 2
924\& Marc Lehmann <pcg@goof.com> 985\& Marc Lehmann <pcg@goof.com>

Diff Legend

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