← Back to branch summary

~kklimonda/ubuntu/lucid/rxvt-unicode/lp-514821

« back to all changes in this revision

Viewing changes to src/urxvt.pm

  • Committer: Bazaar Package Importer
  • Author(s): Decklin Foster
  • Date: 2006-09-01 14:44:58 UTC
  • mfrom: (1.1.8 upstream) (3.1.1 etch)
  • Revision ID: james.westby@ubuntu.com-20060901144458-98hrz8zg01w8a3vy
Tags: 7.9-2
http://bugs.debian.org/385481
* Edit the comments in the app-defaults file, and disable all settings by
  default. If font autoselection fails, I would prefer to open a new bug
  specifically for that. (Closes: #385481)
* Reorganize and edit README.Debian, pushing as much as possible into FAQ
  format (with resource setting issues first).

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/urxvt.pm
19
19
 
20
20
=head1 DESCRIPTION
21
21
 
22
 
Everytime a terminal object gets created, extension scripts specified via
 
22
Every time a terminal object gets created, extension scripts specified via
23
23
the C<perl> resource are loaded and associated with it.
24
24
 
25
25
Scripts are compiled in a 'use strict' and 'use utf8' environment, and
64
64
 
65
65
The index number (0, 1...) must not have any holes, and each regex must
66
66
contain at least one pair of capturing parentheses, which will be used for
67
 
the match. For example, the followign adds a regex that matches everything
 
67
the match. For example, the following adds a regex that matches everything
68
68
between two vertical bars:
69
69
 
70
70
   URxvt.selection.pattern-0: \\|([^|]+)\\|
124
124
popup is being displayed.
125
125
 
126
126
It's sole argument is the popup menu, which can be modified. The selection
127
 
is in C<$_>, which can be used to decide wether to add something or not.
 
127
is in C<$_>, which can be used to decide whether to add something or not.
128
128
It should either return nothing or a string and a code reference. The
129
129
string will be used as button text and the code reference will be called
130
130
when the button gets activated and should transform C<$_>.
153
153
additionally stores the first match in the current line into the primary
154
154
selection.
155
155
 
 
156
The regex defaults to "(?i)", resulting in a case-insensitive search. To
 
157
get a case-sensitive search you can delete this prefix using C<BackSpace>
 
158
or simply use an uppercase character which removes the "(?i)" prefix.
 
159
 
 
160
See L<perlre> for more info about perl regular expression syntax.
 
161
 
156
162
=item readline (enabled by default)
157
163
 
158
164
A support package that tries to make editing with readline easier. At
216
222
=item tabbed
217
223
 
218
224
This transforms the terminal into a tabbar with additional terminals, that
219
 
is, it implements what is commonly refered to as "tabbed terminal". The topmost line
 
225
is, it implements what is commonly referred to as "tabbed terminal". The topmost line
220
226
displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
221
227
button per tab.
222
228
 
255
261
 
256
262
   @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
257
263
 
 
264
=item kuake<hotkey>
 
265
 
 
266
A very primitive quake-console-like extension. It was inspired by a
 
267
description of how the programs C<kuake> and C<yakuake> work: Whenever the
 
268
user presses a global accelerator key (by default C<F10>), the terminal
 
269
will show or hide itself. Another press of the accelerator key will hide
 
270
or show it again.
 
271
 
 
272
Initially, the window will not be shown when using this extension.
 
273
 
 
274
This is useful if you need a single terminal thats not using any desktop
 
275
space most of the time but is quickly available at the press of a key.
 
276
 
 
277
The accelerator key is grabbed regardless of any modifiers, so this
 
278
extension will actually grab a physical key just for this function.
 
279
 
 
280
If you want a quake-like animation, tell your window manager to do so
 
281
(fvwm can do it).
 
282
 
258
283
=item automove-background
259
284
 
260
 
This is basically a one-line extension that dynamically changes the background pixmap offset
261
 
to the window position, in effect creating the same effect as pseudo transparency with
262
 
a custom pixmap. No scaling is supported in this mode. Exmaple:
 
285
This is basically a very small extension that dynamically changes the
 
286
background pixmap offset to the window position, in effect creating the
 
287
same effect as pseudo transparency with a custom pixmap. No scaling is
 
288
supported in this mode. Example:
263
289
 
264
290
   @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
265
291
 
266
292
=item block-graphics-to-ascii
267
293
 
268
 
A not very useful example of filtering all text output to the terminal,
 
294
A not very useful example of filtering all text output to the terminal
269
295
by replacing all line-drawing characters (U+2500 .. U+259F) by a
270
296
similar-looking ascii character.
271
297
 
370
396
 
371
397
=head2 Extension Objects
372
398
 
373
 
Very perl extension is a perl class. A separate perl object is created
 
399
Every perl extension is a perl class. A separate perl object is created
374
400
for each terminal and each extension and passed as the first parameter to
375
401
hooks. So extensions can use their C<$self> object without having to think
376
402
about other extensions, with the exception of methods and members that
406
432
The following subroutines can be declared in extension files, and will be
407
433
called whenever the relevant event happens.
408
434
 
409
 
The first argument passed to them is an extension oject as described in
 
435
The first argument passed to them is an extension object as described in
410
436
the in the C<Extension Objects> section.
411
437
 
412
438
B<All> of these hooks must return a boolean value. If any of the called
429
455
=item on_start $term
430
456
 
431
457
Called at the very end of initialisation of a new terminal, just before
432
 
trying to map (display) the toplevel and returning to the mainloop.
 
458
trying to map (display) the toplevel and returning to the main loop.
433
459
 
434
460
=item on_destroy $term
435
461
 
466
492
requested from the server.  The selection text can be queried and changed
467
493
by calling C<< $term->selection >>.
468
494
 
469
 
Returning a true value aborts selection grabbing. It will still be hilighted.
 
495
Returning a true value aborts selection grabbing. It will still be highlighted.
470
496
 
471
497
=item on_sel_extend $term
472
498
 
473
499
Called whenever the user tries to extend the selection (e.g. with a double
474
500
click) and is either supposed to return false (normal operation), or
475
 
should extend the selection itelf and return true to suppress the built-in
 
501
should extend the selection itself and return true to suppress the built-in
476
502
processing. This can happen multiple times, as long as the callback
477
503
returns true, it will be called on every further click by the user and is
478
504
supposed to enlarge the selection more and more, if possible.
481
507
 
482
508
=item on_view_change $term, $offset
483
509
 
484
 
Called whenever the view offset changes, i..e the user or program
 
510
Called whenever the view offset changes, i.e. the user or program
485
511
scrolls. Offset C<0> means display the normal terminal, positive values
486
512
show this many lines of scrollback.
487
513
 
495
521
$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
496
522
number of lines that will be in the scrollback buffer.
497
523
 
498
 
=item on_osc_seq $term, $string
 
524
=item on_osc_seq $term, $op, $args
 
525
 
 
526
Called on every OSC sequence and can be used to suppress it or modify its
 
527
behaviour.  The default should be to return an empty list. A true value
 
528
suppresses execution of the request completely. Make sure you don't get
 
529
confused by recursive invocations when you output an osc sequence within
 
530
this callback.
 
531
 
 
532
C<on_osc_seq_perl> should be used for new behaviour.
 
533
 
 
534
=item on_osc_seq_perl $term, $string
499
535
 
500
536
Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
501
537
operating system command) is processed. Cursor position and other state
505
541
future.
506
542
 
507
543
Be careful not ever to trust (in a security sense) the data you receive,
508
 
as its source can not easily be controleld (e-mail content, messages from
 
544
as its source can not easily be controlled (e-mail content, messages from
509
545
other users on the same system etc.).
510
546
 
511
547
=item on_add_lines $term, $string
548
584
 
549
585
=item on_user_command $term, $string
550
586
 
551
 
Called whenever the a user-configured event is being activated (e.g. via
 
587
Called whenever a user-configured event is being activated (e.g. via
552
588
a C<perl:string> action bound to a key, see description of the B<keysym>
553
589
resource in the @@RXVT_NAME@@(1) manpage).
554
590
 
557
593
 
558
594
=item on_resize_all_windows $tern, $new_width, $new_height
559
595
 
560
 
Called just after the new window size has been calculcated, but before
 
596
Called just after the new window size has been calculated, but before
561
597
windows are actually being resized or hints are being set. If this hook
562
598
returns TRUE, setting of the window hints is being skipped.
563
599
 
567
603
windows). Should only be used as a last resort. Most event structure
568
604
members are not passed.
569
605
 
 
606
=item on_root_event $term, $event
 
607
 
 
608
Like C<on_x_event>, but is called for events on the root window.
 
609
 
570
610
=item on_focus_in $term
571
611
 
572
612
Called whenever the window gets the keyboard focus, before rxvt-unicode
574
614
 
575
615
=item on_focus_out $term
576
616
 
577
 
Called wheneever the window loses keyboard focus, before rxvt-unicode does
 
617
Called whenever the window loses keyboard focus, before rxvt-unicode does
578
618
focus out processing.
579
619
 
580
620
=item on_configure_notify $term, $event
667
707
 
668
708
=item @urxvt::TERM_INIT
669
709
 
670
 
All coderefs in this array will be called as methods of the next newly
 
710
All code references in this array will be called as methods of the next newly
671
711
created C<urxvt::term> object (during the C<on_init> phase). The array
672
 
gets cleared before the codereferences that were in it are being executed,
673
 
so coderefs can push themselves onto it again if they so desire.
 
712
gets cleared before the code references that were in it are being executed,
 
713
so references can push themselves onto it again if they so desire.
674
714
 
675
 
This complements to the perl-eval commandline option, but gets executed
 
715
This complements to the perl-eval command line option, but gets executed
676
716
first.
677
717
 
678
718
=item @urxvt::TERM_EXT
707
747
=item @terms = urxvt::termlist
708
748
 
709
749
Returns all urxvt::term objects that exist in this process, regardless of
710
 
wether they are started, being destroyed etc., so be careful. Only term
 
750
whether they are started, being destroyed etc., so be careful. Only term
711
751
objects that have perl extensions attached will be returned (because there
712
752
is no urxvt::term objet associated with others).
713
753
 
899
939
      verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
900
940
         if $verbosity >= 10;
901
941
 
902
 
      keys %$cb;
903
 
 
904
 
      while (my ($pkg, $cb) = each %$cb) {
905
 
         my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
 
942
      for my $pkg (keys %$cb) {
 
943
         my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
906
944
         $retval ||= $retval_;
907
945
 
908
946
         if ($@) {
1157
1195
optionally change it. All option values are stored by name in the hash
1158
1196
C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1159
1197
 
1160
 
Here is a a likely non-exhaustive list of option names, please see the
 
1198
Here is a likely non-exhaustive list of option names, please see the
1161
1199
source file F</src/optinc.h> to see the actual list:
1162
1200
 
1163
1201
 borderLess console cursorBlink cursorUnderline hold iconic insecure
1184
1222
Please note that resource strings will currently only be freed when the
1185
1223
terminal is destroyed, so changing options frequently will eat memory.
1186
1224
 
1187
 
Here is a a likely non-exhaustive list of resource names, not all of which
 
1225
Here is a likely non-exhaustive list of resource names, not all of which
1188
1226
are supported in every build, please see the source file F</src/rsinc.h>
1189
1227
to see the actual list:
1190
1228
 
1506
1544
 
1507
1545
=item $cursor_is_hidden = $term->hidden_cursor
1508
1546
 
1509
 
Returns wether the cursor is currently hidden or not.
 
1547
Returns whether the cursor is currently hidden or not.
1510
1548
 
1511
1549
=item $view_start = $term->view_start ([$newvalue])
1512
1550
 
1693
1731
 
1694
1732
=item $string = $term->special_decode $text
1695
1733
 
1696
 
Converts rxvt-unicodes text reprsentation into a perl string. See
 
1734
Converts rxvt-unicodes text representation into a perl string. See
1697
1735
C<< $term->ROW_t >> for details.
1698
1736
 
1699
1737
=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1706
1744
=item $success = $term->grab ($eventtime[, $sync])
1707
1745
 
1708
1746
Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1709
 
synchronous (C<$sync> is true). Also remembers the grab timestampe.
 
1747
synchronous (C<$sync> is true). Also remembers the grab timestamp.
1710
1748
 
1711
1749
=item $term->allow_events_async
1712
1750
 
1983
2021
 
1984
2022
=item $iow = $iow->fd ($fd)
1985
2023
 
1986
 
Set the filedescriptor (not handle) to watch.
 
2024
Set the file descriptor (not handle) to watch.
1987
2025
 
1988
2026
=item $iow = $iow->events ($eventmask)
1989
2027
 
1997
2035
 
1998
2036
=item $iow = $iow->stop
1999
2037
 
2000
 
Stop watching for events on the given filehandle.
 
2038
Stop watching for events on the given file handle.
2001
2039
 
2002
2040
=back
2003
2041
 
2054
2092
 
2055
2093
=item $pw = $timer->start ($pid)
2056
2094
 
2057
 
Tells the wqtcher to start watching for process C<$pid>.
 
2095
Tells the watcher to start watching for process C<$pid>.
2058
2096
 
2059
2097
=item $pw = $pw->stop
2060
2098
 
2077
2115
 
2078
2116
=item >=10 - all called hooks
2079
2117
 
2080
 
=item >=11 - hook reutrn values
 
2118
=item >=11 - hook return values
2081
2119
 
2082
2120
=back
2083
2121