doc/rxvt.7.pod

   1 =head1 RXVT TECHNICAL REFERENCE
   2
   3 =head1 Definitions
   4
   5 =over 4
   6
   7 =item B<< C<c> >>
   8
   9 The literal character c.
  10
  11 =item B<< C<C> >>
  12
  13 A single (required) character.
  14
  15 =item B<< C<Ps> >>
  16
  17 A single (usually optional) numeric parameter, composed of one or more
  18 digits.
  19
  20 =item B<< C<Pm> >>
  21
  22 A multiple numeric parameter composed of any number of single numeric
  23 parameters, separated by C<;> character(s).
  24
  25 =item B<< C<Pt> >>
  26
  27 A text parameter composed of printable characters.
  28
  29 =back
  30
  31 =head1 Values
  32
  33 =over 4
  34
  35 =item B<< C<ENQ> >>
  36
  37 Enquiry (Ctrl-E) = Send Device Attributes (DA)
  38 request attributes from terminal. See B<< C<ESC [ Ps c> >>.
  39
  40 =item B<< C<BEL> >>
  41
  42 Bell (Ctrl-G)
  43
  44 =item B<< C<BS> >>
  45
  46 Backspace (Ctrl-H)
  47
  48 =item B<< C<TAB> >>
  49
  50 Horizontal Tab (HT) (Ctrl-I)
  51
  52 =item B<< C<LF> >>
  53
  54 Line Feed or New Line (NL) (Ctrl-J)
  55
  56 =item B<< C<VT> >>
  57
  58 Vertical Tab (Ctrl-K) same as B<< C<LF> >>
  59
  60 =item B<< C<FF> >>
  61
  62 Form Feed or New Page (NP) (Ctrl-L) same as B<< C<LF> >>
  63
  64 =item B<< C<CR> >>
  65
  66 Carriage Return (Ctrl-M)
  67
  68 =item B<< C<SO> >>
  69
  70 Shift Out (Ctrl-N), invokes the G1 character set.
  71 Switch to Alternate Character Set
  72
  73 =item B<< C<SI> >>
  74
  75 Shift In (Ctrl-O), invokes the G0 character set (the default).
  76 Switch to Standard Character Set
  77
  78 =item B<< C<SPC> >>
  79
  80 Space Character
  81
  82 =back
  83
  84 =head1 Escape Sequences
  85
  86 =over 4
  87
  88 =item B<< C<ESC # 8> >>
  89
  90 DEC Screen Alignment Test (DECALN)
  91
  92 =item B<< C<ESC 7> >>
  93
  94 Save Cursor (SC)
  95
  96 =item B<< C<ESC 8> >>
  97
  98 Restore Cursor
  99
 100 =item B<< C<ESC => >>
 101
 102 Application Keypad (SMKX). See also next sequence.
 103
 104 =item B<<< C<< ESC >> >>>
 105
 106 Normal Keypad (RMKX)
 107
 108 B<Note:> If the numeric keypad is activated, eg, B<Num_Lock> has been
 109 pressed, numbers or control functions are generated by the numeric keypad
 110 (see Key Codes).
 111
 112 =item B<< C<ESC D> >>
 113
 114 Index (IND)
 115
 116 =item B<< C<ESC E> >>
 117
 118 Next Line (NEL)
 119
 120 =item B<< C<ESC H> >>
 121
 122 Tab Set (HTS)
 123
 124 =item B<< C<ESC M> >>
 125
 126 Reverse Index (RI)
 127
 128 =item B<< C<ESC N> >>
 129
 130 Single Shift Select of G2 Character Set (SS2): affects next character
 131 only I<unimplemented>
 132
 133 =item B<< C<ESC O> >>
 134
 135 Single Shift Select of G3 Character Set (SS3): affects next character
 136 only I<unimplemented>
 137
 138 =item B<< C<ESC Z> >>
 139
 140 Obsolete form of returns: B<< C<ESC[?1;2C> >> I<rxvt-unicode compile-time option>
 141
 142 =item B<< C<ESC c> >>
 143
 144 Full reset (RIS)
 145
 146 =item B<< C<ESC n> >>
 147
 148 Invoke the G2 Character Set (LS2)
 149
 150 =item B<< C<ESC o> >>
 151
 152 Invoke the G3 Character Set (LS3)
 153
 154 =item B<< C<ESC>(C<C> >>
 155
 156 Designate G0 Character Set (ISO 2022), see below for values of C<C>.
 157
 158 =item B<< C<ESC>)C<C> >>
 159
 160 Designate G1 Character Set (ISO 2022), see below for values of C<C>.
 161
 162 =item B<< C<ESC * C> >>
 163
 164 Designate G2 Character Set (ISO 2022), see below for values of C<C>.
 165
 166 =item B<< C<ESC + C> >>
 167
 168 Designate G3 Character Set (ISO 2022), see below for values of C<C>.
 169
 170 =item B<< C<ESC $ C> >>
 171
 172 Designate Kanji Character Set
 173
 174 Where B<< C<C> >> is one of:
 175
 176 =begin table
 177
 178         C = C<0>        DEC Special Character and Line Drawing Set
 179         C = C<A>        United Kingdom (UK)
 180         C = C<B>        United States (USASCII)
 181         C = C<< < >>    Multinational character set I<unimplemented>
 182         C = C<5>        Finnish character set I<unimplemented>
 183         C = C<C>        Finnish character set I<unimplemented>
 184         C = C<K>        German character set I<unimplemented>
 185
 186 =end table
 187
 188 =back
 189
 190 X<CSI>
 191
 192 =head1 CSI (Code Sequence Introducer) Sequences
 193
 194 =over 4
 195
 196 =item B<< C<ESC [ Ps @> >>
 197
 198 Insert B<< C<Ps> >> (Blank) Character(s) [default: 1] (ICH)X<ESCOBPsA>
 199
 200 =item B<< C<ESC [ Ps A> >>
 201
 202 Cursor Up B<< C<Ps> >> Times [default: 1] (CUU)
 203
 204 =item B<< C<ESC [ Ps B> >>
 205
 206 Cursor Down B<< C<Ps> >> Times [default: 1] (CUD)X<ESCOBPsC>
 207
 208 =item B<< C<ESC [ Ps C> >>
 209
 210 Cursor Forward B<< C<Ps> >> Times [default: 1] (CUF)
 211
 212 =item B<< C<ESC [ Ps D> >>
 213
 214 Cursor Backward B<< C<Ps> >> Times [default: 1] (CUB)
 215
 216 =item B<< C<ESC [ Ps E> >>
 217
 218 Cursor Down B<< C<Ps> >> Times [default: 1] and to first column
 219
 220 =item B<< C<ESC [ Ps F> >>
 221
 222 Cursor Up B<< C<Ps> >> Times [default: 1] and to first columnX<ESCOBPsG>
 223
 224 =item B<< C<ESC [ Ps G> >>
 225
 226 Cursor to Column B<< C<Ps> >> (HPA)
 227
 228 =item B<< C<ESC [ Ps;Ps H> >>
 229
 230 Cursor Position [row;column] [default: 1;1] (CUP)
 231
 232 =item B<< C<ESC [ Ps I> >>
 233
 234 Move forward B<< C<Ps> >> tab stops [default: 1]
 235
 236 =item B<< C<ESC [ Ps J> >>
 237
 238 Erase in Display (ED)
 239
 240 =begin table
 241
 242         B<< C<Ps = 0> >>        Clear Below (default)
 243         B<< C<Ps = 1> >>        Clear Above
 244         B<< C<Ps = 2> >>        Clear All
 245
 246 =end table
 247
 248 =item B<< C<ESC [ Ps K> >>
 249
 250 Erase in Line (EL)
 251
 252 =begin table
 253
 254         B<< C<Ps = 0> >>        Clear to Right (default)
 255         B<< C<Ps = 1> >>        Clear to Left
 256         B<< C<Ps = 2> >>        Clear All
 257
 258 =end table
 259
 260 =item B<< C<ESC [ Ps L> >>
 261
 262 Insert B<< C<Ps> >> Line(s) [default: 1] (IL)
 263
 264 =item B<< C<ESC [ Ps M> >>
 265
 266 Delete B<< C<Ps> >> Line(s) [default: 1] (DL)
 267
 268 =item B<< C<ESC [ Ps P> >>
 269
 270 Delete B<< C<Ps> >> Character(s) [default: 1] (DCH)
 271
 272 =item B<< C<ESC [ Ps;Ps;Ps;Ps;Ps T> >>
 273
 274 Initiate . I<unimplemented> Parameters are
 275 [func;startx;starty;firstrow;lastrow].
 276
 277 =item B<< C<ESC [ Ps W> >>
 278
 279 Tabulator functions
 280
 281 =begin table
 282
 283         B<< C<Ps = 0> >>        Tab Set (HTS)
 284         B<< C<Ps = 2> >>        Tab Clear (TBC), Clear Current Column (default)
 285         B<< C<Ps = 5> >>        Tab Clear (TBC), Clear All
 286
 287 =end table
 288
 289 =item B<< C<ESC [ Ps X> >>
 290
 291 Erase B<< C<Ps> >> Character(s) [default: 1] (ECH)
 292
 293 =item B<< C<ESC [ Ps Z> >>
 294
 295 Move backward B<< C<Ps> >> [default: 1] tab stops
 296
 297 =item B<< C<ESC [ Ps '> >>
 298
 299 See B<< C<ESC [ Ps G> >>
 300
 301 =item B<< C<ESC [ Ps a> >>
 302
 303 See B<< C<ESC [ Ps C> >>
 304
 305 =item B<< C<ESC [ Ps c> >>
 306
 307 Send Device Attributes (DA)
 308 B<< C<Ps = 0> >> (or omitted): request attributes from terminal
 309 returns: B<< C<ESC[?1;2c> >> (``I am a VT100 with Advanced Video
 310 Option'')
 311
 312 =item B<< C<ESC [ Ps d> >>
 313
 314 Cursor to Line B<< C<Ps> >> (VPA)
 315
 316 =item B<< C<ESC [ Ps e> >>
 317
 318 See B<< C<ESC [ Ps A> >>
 319
 320 =item B<< C<ESC [ Ps;Ps f> >>
 321
 322 Horizontal and Vertical Position [row;column] (HVP) [default: 1;1]
 323
 324 =item B<< C<ESC [ Ps g> >>
 325
 326 Tab Clear (TBC)
 327
 328 =begin table
 329
 330         B<< C<Ps = 0> >>        Clear Current Column (default)
 331         B<< C<Ps = 3> >>        Clear All (TBC)
 332
 333 =end table
 334
 335 =item B<< C<ESC [ Ps i> >>
 336
 337 Printing
 338
 339 =begin table
 340
 341         B<< C<Ps = 4> >>        disable transparent print mode (MC4)
 342         B<< C<Ps = 5> >>        enable transparent print mode (MC5) I<unimplemented>
 343
 344 =end table
 345
 346 =item B<< C<ESC [ Pm h> >>
 347
 348 Set Mode (SM). See next sequence for description of C<Pm>.
 349
 350 =item B<< C<ESC [ Pm l> >>
 351
 352 Reset Mode (RM)
 353
 354 =over 4
 355
 356 =item B<< C<Ps = 4> >>
 357
 358 =begin table
 359
 360         B<< C<h> >>     Insert Mode (SMIR)
 361         B<< C<l> >>     Replace Mode (RMIR)
 362
 363 =end table
 364
 365 =item B<< C<Ps = 20> >> I<unimplemented>
 366
 367 =begin table
 368
 369         B<< C<h> >>     Automatic Newline (LNM)
 370         B<< C<h> >>     Normal Linefeed (LNM)
 371
 372 =end table
 373
 374 =back
 375
 376 =item B<< C<ESC [ Pm m> >>
 377
 378 Character Attributes (SGR)
 379
 380 =begin table
 381
 382         B<< C<Ps = 0> >>        Normal (default)
 383         B<< C<Ps = 1 / 22> >>   On / Off Bold (bright fg)
 384         B<< C<Ps = 4 / 24> >>   On / Off Underline
 385         B<< C<Ps = 5 / 25> >>   On / Off Blink (bright bg)
 386         B<< C<Ps = 7 / 27> >>   On / Off Inverse
 387         B<< C<Ps = 30 / 40> >>  fg/bg Black
 388         B<< C<Ps = 31 / 41> >>  fg/bg Red
 389         B<< C<Ps = 32 / 42> >>  fg/bg Green
 390         B<< C<Ps = 33 / 43> >>  fg/bg Yellow
 391         B<< C<Ps = 34 / 44> >>  fg/bg Blue
 392         B<< C<Ps = 35 / 45> >>  fg/bg Magenta
 393         B<< C<Ps = 36 / 46> >>  fg/bg Cyan
 394         B<< C<Ps = 37 / 47> >>  fg/bg White
 395         B<< C<Ps = 39 / 49> >>  fg/bg Default
 396
 397 =end table
 398
 399 =item B<< C<ESC [ Ps n> >>
 400
 401 Device Status Report (DSR)
 402
 403 =begin table
 404
 405         B<< C<Ps = 5> >>        Status Report B<< C<ESC [ 0 n> >> (``OK'')
 406         B<< C<Ps = 6> >>        Report Cursor Position (CPR) [row;column] as B<< C<ESC [ r ; c R> >>
 407         B<< C<Ps = 7> >>        Request Display Name
 408         B<< C<Ps = 8> >>        Request Version Number (place in window title)
 409
 410 =end table
 411
 412 =item B<< C<ESC [ Ps;Ps r> >>
 413
 414 Set Scrolling Region [top;bottom]
 415 [default: full size of window] (CSR)
 416
 417 =item B<< C<ESC [ s> >>
 418
 419 Save Cursor (SC)
 420
 421 =item B<< C<ESC [ Ps x> >>
 422
 423 Request Terminal Parameters (DECREQTPARM)
 424
 425 =item B<< C<ESC [ u> >>
 426
 427 Restore Cursor
 428
 429 =back
 430
 431 X<PrivateModes>
 432
 433 =head1 DEC Private Modes
 434
 435 =over 4
 436
 437 =item B<< C<ESC [ ? Pm h> >>
 438
 439 DEC Private Mode Set (DECSET)
 440
 441 =item B<< C<ESC [ ? Pm l> >>
 442
 443 DEC Private Mode Reset (DECRST)
 444
 445 =item B<< C<ESC [ ? Pm r> >>
 446
 447 Restore previously saved DEC Private Mode Values.
 448
 449 =item B<< C<ESC [ ? Pm s> >>
 450
 451 Save DEC Private Mode Values.
 452
 453 =item B<< C<ESC [ ? Pm t> >>
 454
 455 Toggle DEC Private Mode Values (rxvt extension). I<where>
 456
 457 =over 4
 458
 459 =item B<< C<Ps = 1> >> (DECCKM)
 460
 461 =begin table
 462
 463         B<< C<h> >>     Application Cursor Keys
 464         B<< C<l> >>     Normal Cursor Keys
 465
 466 =end table
 467
 468 =item B<< C<Ps = 2> >> (ANSI/VT52 mode)
 469
 470 =begin table
 471
 472         B<< C<h> >>     Enter VT52 mode
 473         B<< C<l> >>     Enter VT52 mode
 474
 475 =end table
 476
 477 =item B<< C<Ps = 3> >>
 478
 479 =begin table
 480
 481         B<< C<h> >>     132 Column Mode (DECCOLM)
 482         B<< C<l> >>     80 Column Mode (DECCOLM)
 483
 484 =end table
 485
 486 =item B<< C<Ps = 4> >>
 487
 488 =begin table
 489
 490         B<< C<h> >>     Smooth (Slow) Scroll (DECSCLM)
 491         B<< C<l> >>     Jump (Fast) Scroll (DECSCLM)
 492
 493 =end table
 494
 495 =item B<< C<Ps = 5> >>
 496
 497 =begin table
 498
 499         B<< C<h> >>     Reverse Video (DECSCNM)
 500         B<< C<l> >>     Normal Video (DECSCNM)
 501
 502 =end table
 503
 504 =item B<< C<Ps = 6> >>
 505
 506 =begin table
 507
 508         B<< C<h> >>     Origin Mode (DECOM)
 509         B<< C<l> >>     Normal Cursor Mode (DECOM)
 510
 511 =end table
 512
 513 =item B<< C<Ps = 7> >>
 514
 515 =begin table
 516
 517         B<< C<h> >>     Wraparound Mode (DECAWM)
 518         B<< C<l> >>     No Wraparound Mode (DECAWM)
 519
 520 =end table
 521
 522 =item B<< C<Ps = 8> >> I<unimplemented>
 523
 524 =begin table
 525
 526         B<< C<h> >>     Auto-repeat Keys (DECARM)
 527         B<< C<l> >>     No Auto-repeat Keys (DECARM)
 528
 529 =end table
 530
 531 =item B<< C<Ps = 9> >> X10 XTerm
 532
 533 =begin table
 534
 535         B<< C<h> >>     Send Mouse X & Y on button press.
 536         B<< C<l> >>     No mouse reporting.
 537
 538 =end table
 539
 540 X<Priv10>
 541
 542 =item B<< C<Ps = 10> >> (B<rxvt>)
 543
 544 =begin table
 545
 546         B<< C<h> >>     visible
 547         B<< C<l> >>     invisible
 548
 549 =end table
 550
 551 =item B<< C<Ps = 25> >>
 552
 553 =begin table
 554
 555         B<< C<h> >>     Visible cursor {cnorm/cvvis}
 556         B<< C<l> >>     Invisible cursor {civis}
 557
 558 =end table
 559
 560 =item B<< C<Ps = 30> >>
 561
 562 =begin table
 563
 564         B<< C<h> >>     scrollBar visisble
 565         B<< C<l> >>     scrollBar invisisble
 566
 567 =end table
 568
 569 =item B<< C<Ps = 35> >> (B<rxvt>)
 570
 571 =begin table
 572
 573         B<< C<h> >>     Allow XTerm Shift+key sequences
 574         B<< C<l> >>     Disallow XTerm Shift+key sequences
 575
 576 =end table
 577
 578 =item B<< C<Ps = 38> >> I<unimplemented>
 579
 580 Enter Tektronix Mode (DECTEK)
 581
 582 =item B<< C<Ps = 40> >>
 583
 584 =begin table
 585
 586         B<< C<h> >>     Allow 80/132 Mode
 587         B<< C<l> >>     Disallow 80/132 Mode
 588
 589 =end table
 590
 591 =item B<< C<Ps = 44> >> I<unimplemented>
 592
 593 =begin table
 594
 595         B<< C<h> >>     Turn On Margin Bell
 596         B<< C<l> >>     Turn Off Margin Bell
 597
 598 =end table
 599
 600 =item B<< C<Ps = 45> >> I<unimplemented>
 601
 602 =begin table
 603
 604         B<< C<h> >>     Reverse-wraparound Mode
 605         B<< C<l> >>     No Reverse-wraparound Mode
 606
 607 =end table
 608
 609 =item B<< C<Ps = 46> >> I<unimplemented>
 610
 611 =item B<< C<Ps = 47> >>
 612
 613 =begin table
 614
 615         B<< C<h> >>     Use Alternate Screen Buffer
 616         B<< C<l> >>     Use Normal Screen Buffer
 617
 618 =end table
 619
 620 X<Priv66>
 621
 622 =item B<< C<Ps = 66> >>
 623
 624 =begin table
 625
 626         B<< C<h> >>     Application Keypad (DECPAM) == C<ESC =>
 627         B<< C<l> >>     Normal Keypad (DECPNM) == C<< ESC > >>
 628
 629 =end table
 630
 631 =item B<< C<Ps = 67> >>
 632
 633 =begin table
 634
 635         B<< C<h> >>     Backspace key sends B<< C<BS> (DECBKM) >>
 636         B<< C<l> >>     Backspace key sends B<< C<DEL> >>
 637
 638 =end table
 639
 640 =item B<< C<Ps = 1000> >> (X11 XTerm)
 641
 642 =begin table
 643
 644         B<< C<h> >>     Send Mouse X & Y on button press and release.
 645         B<< C<l> >>     No mouse reporting.
 646
 647 =end table
 648
 649 =item B<< C<Ps = 1001> >> (X11 XTerm) I<unimplemented>
 650
 651 =begin table
 652
 653         B<< C<h> >>     Use Hilite Mouse Tracking.
 654         B<< C<l> >>     No mouse reporting.
 655
 656 =end table
 657
 658 =item B<< C<Ps = 1010> >>
 659
 660 =begin table
 661
 662         B<< C<h> >>     Don't scroll to bottom on TTY output
 663         B<< C<l> >>     Scroll to bottom on TTY output
 664
 665 =end table
 666
 667 =item B<< C<Ps = 1011> >>
 668
 669 =begin table
 670
 671         B<< C<h> >>     Scroll to bottom when a key is pressed
 672         B<< C<l> >>     Don't scroll to bottom when a key is pressed
 673
 674 =end table
 675
 676 =item B<< C<Ps = 1047> >>
 677
 678 =begin table
 679
 680         B<< C<h> >>     Use Alternate Screen Buffer
 681         B<< C<l> >>     Use Normal Screen Buffer - clear Alternate Screen Buffer if returning from it
 682
 683 =end table
 684
 685 =item B<< C<Ps = 1048> >>
 686
 687 =begin table
 688
 689         B<< C<h> >>     Save cursor position
 690         B<< C<l> >>     Restore cursor position
 691
 692 =end table
 693
 694 =back
 695
 696 =back
 697
 698 X<XTerm>
 699
 700 =head1 XTerm Operating System Commands
 701
 702 =over 4
 703
 704 =item B<< C<ESC ] Ps;Pt ST> >>
 705
 706 Set XTerm Parameters. 8-bit ST: 0x9c, 7-bit ST sequence: ESC \ (0x1b,
 707 0x5c), backwards compatible terminator BEL (0x07) is also accepted. any
 708 B<octet> can be escaped by prefixing it with SYN (0x16, ^V).
 709
 710 =begin table
 711
 712         B<< C<Ps = 0> >>        Change Icon Name and Window Title to B<< C<Pt> >>
 713         B<< C<Ps = 1> >>        Change Icon Name to B<< C<Pt> >>
 714         B<< C<Ps = 2> >>        Change Window Title to B<< C<Pt> >>
 715         B<< C<Ps = 3> >>        If B<< C<Pt> >> starts with a B<< C<?> >>, query the (STRING) property of the window and return it. If B<< C<Pt> >> contains a B<< C<=> >>, set the named property to the given value, else delete the specified property.
 716         B<< C<Ps = 4> >>        B<< C<Pt> >> is a semi-colon separated sequence of one or more semi-colon separated B<number>/B<name> pairs, where B<number> is an index to a colour and B<name> is the name of a colour. Each pair causes the B<number>ed colour to be changed to B<name>. Numbers 0-7 corresponds to low-intensity (normal) colours and 8-15 corresponds to high-intensity colours. 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white
 717         B<< C<Ps = 10> >>       Change colour of text foreground to B<< C<Pt> >> B<(NB: may change in future)>
 718         B<< C<Ps = 11> >>       Change colour of text background to B<< C<Pt> >> B<(NB: may change in future)>
 719         B<< C<Ps = 12> >>       Change colour of text cursor foreground to B<< C<Pt> >>
 720         B<< C<Ps = 13> >>       Change colour of mouse foreground to B<< C<Pt> >>
 721         B<< C<Ps = 17> >>       Change colour of highlight characters to B<< C<Pt> >>
 722         B<< C<Ps = 18> >>       Change colour of bold characters to B<< C<Pt> >>
 723         B<< C<Ps = 19> >>       Change colour of underlined characters to B<< C<Pt> >>
 724         B<< C<Ps = 20> >>       Change default background to B<< C<Pt> >>
 725         B<< C<Ps = 39> >>       Change default foreground colour to B<< C<Pt> >> I<rxvt compile-time option>
 726         B<< C<Ps = 46> >>       Change Log File to B<< C<Pt> >> I<unimplemented>
 727         B<< C<Ps = 49> >>       Change default background colour to B<< C<Pt> >> I<rxvt compile-time option>
 728         B<< C<Ps = 50> >>       Set fontset to B<< C<Pt> >>, with the following special values of B<< C<Pt> >> (B<rxvt>) B<< C<#+n> >> change up B<< C<n> >> B<< C<#-n> >> change down B<< C<n> >> if B<< C<n> >> is missing of 0, a value of 1 is used I<empty> change to font0 B<< C<n> >> change to font B<< C<n> >>
 729         B<< C<Ps = 55> >>       Log all scrollback buffer and all of screen to B<< C<Pt> >>
 730         B<< C<Ps = 701> >>      Change current locale to B<< C<Pt> >>, or, if B<< C<Pt> >> is B<< C<?> >>, return the current locale (@@RXVT_NAME@@ extension)
 731         B<< C<Ps = 702> >>      find font for character, used for debugging (@@RXVT_NAME@@ extension)
 732         B<< C<Ps = 703> >>      command B<< C<Pt> >> I<rxvt compile-time option> (@@RXVT_NAME@@ extension)
 733
 734 =end table
 735
 736 =back
 737
 738 X<menuBar>
 739
 740 =head1 menuBar
 741
 742 B<< The exact syntax used is I<almost> solidified. >>
 743 In the menus, B<DON'T> try to use menuBar commands that add or remove a
 744 menuBar.
 745
 746 Note that in all of the commands, the B<< I</path/> >> I<cannot> be
 747 omitted: use B<./> to specify a menu relative to the current menu.
 748
 749 =head2 Overview of menuBar operation
 750
 751 For the menuBar XTerm escape sequence C<ESC ] 703 ; Pt ST>, the syntax
 752 of C<Pt> can be used for a variety of tasks:
 753
 754 At the top level is the current menuBar which is a member of a circular
 755 linked-list of other such menuBars.
 756
 757 The menuBar acts as a parent for the various drop-down menus, which in
 758 turn, may have labels, separator lines, menuItems and subMenus.
 759
 760 The menuItems are the useful bits: you can use them to mimic keyboard
 761 input or even to send text or escape sequences back to rxvt.
 762
 763 The menuBar syntax is intended to provide a simple yet robust method of
 764 constructing and manipulating menus and navigating through the
 765 menuBars.
 766
 767 The first step is to use the tag B<< [menu:I<name>] >> which creates
 768 the menuBar called I<name> and allows access. You may now or menus,
 769 subMenus, and menuItems. Finally, use the tag B<[done]> to set the
 770 menuBar access as B<readonly> to prevent accidental corruption of the
 771 menus. To re-access the current menuBar for alterations, use the tag
 772 B<[menu]>, make the alterations and then use B<[done]>
 773
 774 X<menuBarCommands>
 775
 776 =head2 Commands
 777
 778 =over 4
 779
 780 =item B<< [menu:+I<name>] >>
 781
 782 access the named menuBar for creation or alteration. If a new menuBar
 783 is created, it is called I<name> (max of 15 chars) and the current
 784 menuBar is pushed onto the stack
 785
 786 =item B<[menu]>
 787
 788 access the current menuBar for alteration
 789
 790 =item B<< [title:+I<string>] >>
 791
 792 set the current menuBar's title to I<string>, which may contain the
 793 following format specifiers:
 794 B<%%> : literal B<%> character
 795 B<%n> : rxvt name (as per the B<-name> command-line option)
 796 B<%v> : rxvt version
 797
 798 =item B<[done]>
 799
 800 set menuBar access as B<readonly>.
 801 End-of-file tag for B<< [read:+I<file>] >> operations.
 802
 803 =item B<< [read:+I<file>] >>
 804
 805 read menu commands directly from I<file> (extension ".menu" will be
 806 appended if required.) Start reading at a line with B<[menu]> or B<<
 807 [menu:+I<name> >> and continuing until B<[done]> is encountered.
 808
 809 Blank and comment lines (starting with B<#>) are ignored. Actually,
 810 since any invalid menu commands are also ignored, almost anything could
 811 be construed as a comment line, but this may be tightened up in the
 812 future ... so don't count on it!.
 813
 814 =item B<< [read:+I<file>;+I<name>] >>
 815
 816 The same as B<< [read:+I<file>] >>, but start reading at a line with
 817 B<< [menu:+I<name>] >> and continuing until B<< [done:+I<name>] >> or
 818 B<[done]> is encountered.
 819
 820 =item B<[dump]>
 821
 822 dump all menuBars to the file B</tmp/rxvt-PID> in a format suitable for
 823 later rereading.
 824
 825 =item B<[rm:name]>
 826
 827 remove the named menuBar
 828
 829 =item B<[rm] [rm:]>
 830
 831 remove the current menuBar
 832
 833 =item B<[rm*] [rm:*]>
 834
 835 remove all menuBars
 836
 837 =item B<[swap]>
 838
 839 swap the top two menuBars
 840
 841 =item B<[prev]>
 842
 843 access the previous menuBar
 844
 845 =item B<[next]>
 846
 847 access the next menuBar
 848
 849 =item B<[show]>
 850
 851 Enable display of the menuBar
 852
 853 =item B<[hide]>
 854
 855 Disable display of the menuBar
 856
 857 =item B<< [pixmap:+I<name>] >>
 858
 859 =item B<< [pixmap:+I<name>;I<scaling>] >>
 860
 861 (set the background pixmap globally
 862
 863 B<< A Future implementation I<may> make this local to the menubar >>)
 864
 865 =item B<< [:+I<command>:] >>
 866
 867 ignore the menu readonly status and issue a I<command> to or a menu or
 868 menuitem or change the ; a useful shortcut for setting the quick arrows
 869 from a menuBar.
 870
 871 =back
 872
 873 X<menuBarAdd>
 874
 875 =head2 Adding and accessing menus
 876
 877 The following commands may also be B<+> prefixed.
 878
 879 =over 4
 880
 881 =item B</+>
 882
 883 access menuBar top level
 884
 885 =item B<./+>
 886
 887 access current menu level
 888
 889 =item B<../+>
 890
 891 access parent menu (1 level up)
 892
 893 =item B<../../>
 894
 895 access parent menu (multiple levels up)
 896
 897 =item B<< I</path/>menu >>
 898
 899 add/access menu
 900
 901 =item B<< I</path/>menu/* >>
 902
 903 add/access menu and clear it if it exists
 904
 905 =item B<< I</path/>{-} >>
 906
 907 add separator
 908
 909 =item B<< I</path/>{item} >>
 910
 911 add B<item> as a label
 912
 913 =item B<< I</path/>{item} action >>
 914
 915 add/alter I<menuitem> with an associated I<action>
 916
 917 =item B<< I</path/>{item}{right-text} >>
 918
 919 add/alter I<menuitem> with B<right-text> as the right-justified text
 920 and as the associated I<action>
 921
 922 =item B<< I</path/>{item}{rtext} action >>
 923
 924 add/alter I<menuitem> with an associated I<action> and with B<rtext> as
 925 the right-justified text.
 926
 927 =back
 928
 929 =over 4
 930
 931 =item Special characters in I<action> must be backslash-escaped:
 932
 933 B<\a \b \E \e \n \r \t \octal>
 934
 935 =item or in control-character notation:
 936
 937 B<^@, ^A .. ^Z .. ^_, ^?>
 938
 939 =back
 940
 941 To send a string starting with a B<NUL> (B<^@>) character to the
 942 program, start I<action> with a pair of B<NUL> characters (B<^@^@>),
 943 the first of which will be stripped off and the balance directed to the
 944 program. Otherwise if I<action> begins with B<NUL> followed by
 945 non-+B<NUL> characters, the leading B<NUL> is stripped off and the
 946 balance is sent back to rxvt.
 947
 948 As a convenience for the many Emacs-type editors, I<action> may start
 949 with B<M-> (eg, B<M-$> is equivalent to B<\E$>) and a B<CR> will be
 950 appended if missed from B<M-x> commands.
 951
 952 As a convenience for issuing XTerm B<ESC]> sequences from a menubar (or
 953 quick arrow), a B<BEL> (B<^G>) will be appended if needed.
 954
 955 =over 4
 956
 957 =item For example,
 958
 959 B<M-xapropos> is equivalent to B<\Exapropos\r>
 960
 961 =item and
 962
 963 B<\E]703;mona;100> is equivalent to B<\E]703;mona;100\a>
 964
 965 =back
 966
 967 The option B<< {I<right-rtext>} >> will be right-justified. In the
 968 absence of a specified action, this text will be used as the I<action>
 969 as well.
 970
 971 =over 4
 972
 973 =item For example,
 974
 975 B</File/{Open}{^X^F}> is equivalent to B</File/{Open}{^X^F} ^X^F>
 976
 977 =back
 978
 979 The left label I<is> necessary, since it's used for matching, but
 980 implicitly hiding the left label (by using same name for both left and
 981 right labels), or explicitly hiding the left label (by preceeding it
 982 with a dot), makes it possible to have right-justified text only.
 983
 984 =over 4
 985
 986 =item For example,
 987
 988 B</File/{Open}{Open} Open-File-Action>
 989
 990 =item or hiding it
 991
 992 B</File/{.anylabel}{Open} Open-File-Action>
 993
 994 =back
 995
 996 X<menuBarRemove>
 997
 998 =head2 Removing menus
 999
1000 =over 4
1001
1002 =item B<< -/*+ >>
1003
1004 remove all menus from the menuBar, the same as B<[clear]>
1005
1006 =item B<< -+I</path>menu+ >>
1007
1008 remove menu
1009
1010 =item B<< -+I</path>{item}+ >>
1011
1012 remove item
1013
1014 =item B<< -+I</path>{-} >>
1015
1016 remove separator)
1017
1018 =item B<-/path/menu/*>
1019
1020 remove all items, separators and submenus from menu
1021
1022 =back
1023
1024 X<menuBarArrows>
1025
1026 =head2 Quick Arrows
1027
1028 The menus also provide a hook for I<quick arrows> to provide easier
1029 user access. If nothing has been explicitly set, the default is to
1030 emulate the curror keys. The syntax permits each arrow to be altered
1031 individually or all four at once without re-entering their common
1032 beginning/end text. For example, to explicitly associate cursor actions
1033 with the arrows, any of the following forms could be used:
1034
1035 =over 4
1036
1037 =item B<< <r>+I<Right> >>
1038
1039 =item B<< <l>+I<Left> >>
1040
1041 =item B<< <u>+I<Up> >>
1042
1043 =item B<< <d>+I<Down> >>
1044
1045 Define actions for the respective arrow buttons
1046
1047 =item B<< <b>+I<Begin> >>
1048
1049 =item B<< <e>+I<End> >>
1050
1051 Define common beginning/end parts for I<quick arrows> which used in
1052 conjunction with the above <r> <l> <u> <d> constructs
1053
1054 =back
1055
1056 =over 4
1057
1058 =item For example, define arrows individually,
1059
1060  <u>\E[A
1061
1062  <d>\E[B
1063
1064  <r>\E[C
1065
1066  <l>\E[D
1067
1068 =item or all at once
1069
1070  <u>\E[AZ<><d>\E[BZ<><r>\E[CZ<><l>\E[D
1071
1072 =item or more compactly (factoring out common parts)
1073
1074  <b>\E[<u>AZ<><d>BZ<><r>CZ<><l>D
1075
1076 =back
1077
1078 X<menuBarSummary>
1079
1080 =head2 Command Summary
1081
1082 A short summary of the most I<common> commands:
1083
1084 =over 4
1085
1086 =item [menu:name]
1087
1088 use an existing named menuBar or start a new one
1089
1090 =item [menu]
1091
1092 use the current menuBar
1093
1094 =item [title:string]
1095
1096 set menuBar title
1097
1098 =item [done]
1099
1100 set menu access to readonly and, if reading from a file, signal EOF
1101
1102 =item [done:name]
1103
1104 if reading from a file using [read:file;name] signal EOF
1105
1106 =item [rm:name]
1107
1108 remove named menuBar(s)
1109
1110 =item [rm] [rm:]
1111
1112 remove current menuBar
1113
1114 =item [rm*] [rm:*]
1115
1116 remove all menuBar(s)
1117
1118 =item [swap]
1119
1120 swap top two menuBars
1121
1122 =item [prev]
1123
1124 access the previous menuBar
1125
1126 =item [next]
1127
1128 access the next menuBar
1129
1130 =item [show]
1131
1132 map menuBar
1133
1134 =item [hide]
1135
1136 unmap menuBar
1137
1138 =item [pixmap;file]
1139
1140 =item [pixmap;file;scaling]
1141
1142 set a background pixmap
1143
1144 =item [read:file]
1145
1146 =item [read:file;name]
1147
1148 read in a menu from a file
1149
1150 =item [dump]
1151
1152 dump out all menuBars to /tmp/rxvt-PID
1153
1154 =item /
1155
1156 access menuBar top level
1157
1158 =item ./
1159
1160 =item ../
1161
1162 =item ../../
1163
1164 access current or parent menu level
1165
1166 =item /path/menu
1167
1168 add/access menu
1169
1170 =item /path/{-}
1171
1172 add separator
1173
1174 =item /path/{item}{rtext} action
1175
1176 add/alter menu item
1177
1178 =item -/*
1179
1180 remove all menus from the menuBar
1181
1182 =item -/path/menu
1183
1184 remove menu items, separators and submenus from menu
1185
1186 =item -/path/menu
1187
1188 remove menu
1189
1190 =item -/path/{item}
1191
1192 remove item
1193
1194 =item -/path/{-}
1195
1196 remove separator
1197
1198 =item <b>Begin<r>Right<l>Left<u>Up<d>Down<e>End
1199
1200 menu quick arrows
1201
1202 =back
1203 X<XPM>
1204
1205 =head1 XPM
1206
1207 For the XPM XTerm escape sequence B<< C<ESC ] 20 ; Pt ST> >> then value
1208 of B<< C<Pt> >> can be the name of the background pixmap followed by a
1209 sequence of scaling/positioning commands separated by semi-colons. The
1210 scaling/positioning commands are as follows:
1211
1212 =over 4
1213
1214 =item query scale/position
1215
1216 B<?>
1217
1218 =item change scale and position
1219
1220 B<WxH+X+Y>
1221
1222 B<WxH+X> (== B<WxH+X+X>)
1223
1224 B<WxH> (same as B<WxH+50+50>)
1225
1226 B<W+X+Y> (same as B<WxW+X+Y>)
1227
1228 B<W+X> (same as B<WxW+X+X>)
1229
1230 B<W> (same as B<WxW+50+50>)
1231
1232 =item change position (absolute)
1233
1234 B<=+X+Y>
1235
1236 B<=+X> (same as B<=+X+Y>)
1237
1238 =item change position (relative)
1239
1240 B<+X+Y>
1241
1242 B<+X> (same as B<+X+Y>)
1243
1244 =item rescale (relative)
1245
1246 B<Wx0> -> B<W *= (W/100)>
1247
1248 B<0xH> -> B<H *= (H/100)>
1249
1250 =back
1251
1252 For example:
1253
1254 =over 4
1255
1256 =item B<\E]20;funky\a>
1257
1258 load B<funky.xpm> as a tiled image
1259
1260 =item B<\E]20;mona;100\a>
1261
1262 load B<mona.xpm> with a scaling of 100%
1263
1264 =item B<\E]20;;200;?\a>
1265
1266 rescale the current pixmap to 200% and display the image geometry in
1267 the title
1268
1269 =back
1270 X<Mouse>
1271
1272 =head1 Mouse Reporting
1273
1274 =over 4
1275
1276 =item B<< C<< ESC [ M <b> <x> <y> >> >>
1277
1278 report mouse position
1279
1280 =back
1281
1282 The lower 2 bits of B<< C<< <b> >> >> indicate the button:
1283
1284 =over 4
1285
1286 =item Button = B<< C<< (<b> - SPACE) & 3 >> >>
1287
1288 =begin table
1289
1290         0       Button1 pressed
1291         1       Button2 pressed
1292         2       Button3 pressed
1293         3       button released (X11 mouse report)
1294
1295 =end table
1296
1297 =back
1298
1299 The upper bits of B<< C<< <b> >> >> indicate the modifiers when the
1300 button was pressed and are added together (X11 mouse report only):
1301
1302 =over 4
1303
1304 =item State = B<< C<< (<b> - SPACE) & 60 >> >>
1305
1306 =begin table
1307
1308         4       Shift
1309         8       Meta
1310         16      Control
1311         32      Double Click I<(Rxvt extension)>
1312
1313 =end table
1314
1315 Col = B<< C<< <x> - SPACE >> >>
1316
1317 Row = B<< C<< <y> - SPACE >> >>
1318
1319 =back
1320 X<KeyCodes>
1321
1322 =head1 Key Codes
1323
1324 Note: B<Shift> + B<F1>-B<F10> generates B<F11>-B<F20>
1325
1326 For the keypad, use B<Shift> to temporarily override Application-Keypad
1327 setting use B<Num_Lock> to toggle Application-Keypad setting if
1328 B<Num_Lock> is off, toggle Application-Keypad setting. Also note that
1329 values of B<Home>, B<End>, B<Delete> may have been compiled differently on
1330 your system.
1331
1332 =begin table
1333
1334                 B<Normal>       B<Shift>        B<Control>      B<Ctrl+Shift>
1335         Tab     ^I      ESC [ Z ^I      ESC [ Z
1336         BackSpace       ^H      ^?      ^?      ^?
1337         Find    ESC [ 1 ~       ESC [ 1 $       ESC [ 1 ^       ESC [ 1 @
1338         Insert  ESC [ 2 ~       I<paste>        ESC [ 2 ^       ESC [ 2 @
1339         Execute ESC [ 3 ~       ESC [ 3 $       ESC [ 3 ^       ESC [ 3 @
1340         Select  ESC [ 4 ~       ESC [ 4 $       ESC [ 4 ^       ESC [ 4 @
1341         Prior   ESC [ 5 ~       I<scroll-up>    ESC [ 5 ^       ESC [ 5 @
1342         Next    ESC [ 6 ~       I<scroll-down>  ESC [ 6 ^       ESC [ 6 @
1343         Home    ESC [ 7 ~       ESC [ 7 $       ESC [ 7 ^       ESC [ 7 @
1344         End     ESC [ 8 ~       ESC [ 8 $       ESC [ 8 ^       ESC [ 8 @
1345         Delete  ESC [ 3 ~       ESC [ 3 $       ESC [ 3 ^       ESC [ 3 @
1346         F1      ESC [ 11 ~      ESC [ 23 ~      ESC [ 11 ^      ESC [ 23 ^
1347         F2      ESC [ 12 ~      ESC [ 24 ~      ESC [ 12 ^      ESC [ 24 ^
1348         F3      ESC [ 13 ~      ESC [ 25 ~      ESC [ 13 ^      ESC [ 25 ^
1349         F4      ESC [ 14 ~      ESC [ 26 ~      ESC [ 14 ^      ESC [ 26 ^
1350         F5      ESC [ 15 ~      ESC [ 28 ~      ESC [ 15 ^      ESC [ 28 ^
1351         F6      ESC [ 17 ~      ESC [ 29 ~      ESC [ 17 ^      ESC [ 29 ^
1352         F7      ESC [ 18 ~      ESC [ 31 ~      ESC [ 18 ^      ESC [ 31 ^
1353         F8      ESC [ 19 ~      ESC [ 32 ~      ESC [ 19 ^      ESC [ 32 ^
1354         F9      ESC [ 20 ~      ESC [ 33 ~      ESC [ 20 ^      ESC [ 33 ^
1355         F10     ESC [ 21 ~      ESC [ 34 ~      ESC [ 21 ^      ESC [ 34 ^
1356         F11     ESC [ 23 ~      ESC [ 23 $      ESC [ 23 ^      ESC [ 23 @
1357         F12     ESC [ 24 ~      ESC [ 24 $      ESC [ 24 ^      ESC [ 24 @
1358         F13     ESC [ 25 ~      ESC [ 25 $      ESC [ 25 ^      ESC [ 25 @
1359         F14     ESC [ 26 ~      ESC [ 26 $      ESC [ 26 ^      ESC [ 26 @
1360         F15 (Help)      ESC [ 28 ~      ESC [ 28 $      ESC [ 28 ^      ESC [ 28 @
1361         F16 (Menu)      ESC [ 29 ~      ESC [ 29 $      ESC [ 29 ^      ESC [ 29 @
1362         F17     ESC [ 31 ~      ESC [ 31 $      ESC [ 31 ^      ESC [ 31 @
1363         F18     ESC [ 32 ~      ESC [ 32 $      ESC [ 32 ^      ESC [ 32 @
1364         F19     ESC [ 33 ~      ESC [ 33 $      ESC [ 33 ^      ESC [ 33 @
1365         F20     ESC [ 34 ~      ESC [ 34 $      ESC [ 34 ^      ESC [ 34 @
1366                                         B<Application>
1367         Up      ESC [ A ESC [ a ESC O a ESC O A
1368         Down    ESC [ B ESC [ b ESC O b ESC O B
1369         Right   ESC [ C ESC [ c ESC O c ESC O C
1370         Left    ESC [ D ESC [ d ESC O d ESC O D
1371         KP_Enter        ^M                      ESC O M
1372         KP_F1   ESC O P                 ESC O P
1373         KP_F2   ESC O Q                 ESC O Q
1374         KP_F3   ESC O R                 ESC O R
1375         KP_F4   ESC O S                 ESC O S
1376         XK_KP_Multiply  *                       ESC O j
1377         XK_KP_Add       +                       ESC O k
1378         XK_KP_Separator ,                       ESC O l
1379         XK_KP_Subtract  -                       ESC O m
1380         XK_KP_Decimal   .                       ESC O n
1381         XK_KP_Divide    /                       ESC O o
1382         XK_KP_0 0                       ESC O p
1383         XK_KP_1 1                       ESC O q
1384         XK_KP_2 2                       ESC O r
1385         XK_KP_3 3                       ESC O s
1386         XK_KP_4 4                       ESC O t
1387         XK_KP_5 5                       ESC O u
1388         XK_KP_6 6                       ESC O v
1389         XK_KP_7 7                       ESC O w
1390         XK_KP_8 8                       ESC O x
1391         XK_KP_9 9                       ESC O y
1392
1393 =end table
1394
1395 =head1 AUTHORS
1396
1397 Marc Lehmann <rxvt@schmorp.de>, converted this document to pod and
1398 reworked it from the original Rxvt documentation, which was done by Geoff
1399 Wing <gcw@pobox.com>, who in turn used the XTerm documentation and other
1400 sources.
1401