NAME

tabbedex - tabbed interface to urxvt; extended

DESCRIPTION

This extension implements a tabbed terminal. Once rxvt-unicode starts, slave terminals can be started in their own tabs and switched between. At each point only one terminal is visible. rxvt-unicode exits once all tabs are closed.

Once at least two tabs are created a tab bar is displayed at the top of the window which lists all the slave terminals. Clicking on a number/name of a tab on that bar switches to it.

tabbedex is an extended version of the tabbed plugin distributed with urxvt.

Key bindings

Creating new tabs, switching between them and moving them around can be performed through the following key bindings:

Shift-Down

Creates a new tab.

Shift-Left and Shift-Right

Switches to the tab on the left or on the right of the current tab. Movement wraps around once at the first or last tab.

Meta-F1 through Meta-F12

Switches to the first through twelfth tab.

Control-Left and Control-right

Move current tab to the left or right. Wraps around on the first and last position.

Shift-Up

Allows current tab to be renamed. Tab bar is shown if it was hidden, current tab's name (if any) is cleared and cursor is displayed in its place. Typing text renames the tab, backspace or Ctrl+H delete the last character, Escape or Ctrl+C aborts the rename operation and Enter accepts the new name.

Default key bindings can be disabled using no-tabbedex-keys resource (see below) and replaced with custom ones using urxvt's keysym resource.

CONFIGURATION

The extension can be configured with X resources just like urxvt itself, for example:

    URxvt.tabbedex.tabbar-fg: 4
    URxvt.tabbedex.tabbar-bg: 0

Tabbedex recognises the following resources:

autohide: boolean

If set (the default), the tab bar will be hidden unless there are at least two tabs open. This is irrespective of whether NEW button or tab's title is displayed.

new-button: boolean

If set, a NEW button will be displayed on the left of the tab bar. Clicking the button creates a new tab. It is not displayed by default.

title: boolean

If set (the default), when tab bar is visible and there is enough space left, current tab's title will be displayed after the last tab.

tabbar-fg: [style] colour and tabbar-bg: colour
tab-fg: [style] colour and tab-bg: colour
bell-fg: [style] colour and bell-bg: colour
bell-tab-fg: [style] colour and bell-tab-bg: colour
title-fg: [style] colour and title-bg: colour

Foreground and background styles of respectively: the tab bar (including inactive tabs), the current/active tab on the tab bar and new button, an inactive tab on which bell has rung, an active tab on which bell has rung and finally the tab title.

Colours can be specified as: -2 meaning default foreground, -1 meaning default background, an integer between 0 and 255 specifying index in terminal' colour palette or any other string which X11 recognises as a colour (e.g. #1155CC).

Furthermore, the -fg resource can be prefixed by combination of bold, italic, blink, reverse-video and underline which specify the font-style of the text.

The default values for the settings are as follows:

    Component | *-fg          | *-bg | Description
    ----------+---------------+------+----------------------
    tabbar    |             3 |    0 | brown text on black
    tab       | bold        0 |    1 | black text on red
    bell      |      italic 0 |    3 | black text on brown
    bell-tab  | bold italic 5 |    4 | magenta text on blue
    title     |      italic 2 |    0 | green text on black
bell-timeout: number

Time in seconds, one second by default, a bell is said to be ringing on current tab for after it was rung. Setting this to zero essentially disables the bell-tab-(fg|bg) styling of tabs.

tab-arguments: string

Arguments passed when starting a slave tabs. If not specified, -e command switch used when starting urxvt command is used (if any). If specified, the value is first expanded (see below), then split into words using shell quoting rules and those are passed as arguments to slave terminals when they are started.

This resource can be used to pass any arguments however doing so may have unintended consequences. Options such as -bw or -geometry are especially problematic but others may cause issues as well. Because of this, only -e Bcommand arguments>> is officially supported.

The value is expanded by replacing two-character sequences starting with a percent sign as follows:

%%

Replaced by a literal percent sign.

%e

Replaced by properly quoted -e command arguments if they were given when urxvt was started or an empty string otherwise. See also %E which may be easier for some uses.

Remember that if neither %e nor %E is used, -e switch passed when starting urxvt will be completely ignored.

%E

Similar to %e but -e is not included in the expansion and if %e would expand to an empty string %E expands to value of SHELL environment variable or /bin/sh if that's empty. This means that %E is always a valid command.

For example, here's how the sequence can be used to set TABBEDEX_NUM environment variables when running a command:

    URxvt.tabbedex.tab-arguments: -e /usr/bin/env TABBEDEX_NUM=%n %E
%n

Replaced by the total number of tabs opened during the lifetime of the extension. Not to be confused with number of tabs currently open. The counter starts at zero and always increments for each subsequent tab.

%p

Replaced by ID of a process group which is running in foreground of the pseudo terminal in the current tab (as in, not the new tab being created but the tab where the new tab request originated from) or -1 if there are no active tabs (or that information could not be determined).

This can be used to guess the current working directory of current tab.

%~

Replaced by a properly quoted value of HOME environment variable or / if it's not set.

Unrecognised sequences are replaced with an empty string.

See command-runner.sample file distributed with this extension for some ideas how this resource can be used to start different commands in different tabs or how to use the same current working directory for new tabs as the active tab has.

no-tabbedex-keys: boolean

If set, the default key bindings (described at the beginning of this document) are not set up. The mappings can be recreated using urxvt's keysym.* resources:

    URxvt.tabbedex.no-tabbedex-keys: yes
    URxvt.keysym.Shift-Left:    tabbedex:prev_tab
    URxvt.keysym.Shift-Right:   tabbedex:next_tab
    URxvt.keysym.Shift-Down:    tabbedex:new_tab
    URxvt.keysym.Shift-Up:      tabbedex:rename_tab
    URxvt.keysym.Control-Left:  tabbedex:move_tab_left
    URxvt.keysym.Control-Right: tabbedex:move_tab_right
    URxvt.keysym.Meta-F1:       tabbedex:goto_tab_1
    URxvt.keysym.Meta-F2:       tabbedex:goto_tab_2
    URxvt.keysym.Meta-F3:       tabbedex:goto_tab_3
    URxvt.keysym.Meta-F4:       tabbedex:goto_tab_4
    URxvt.keysym.Meta-F5:       tabbedex:goto_tab_5
    URxvt.keysym.Meta-F6:       tabbedex:goto_tab_6
    URxvt.keysym.Meta-F7:       tabbedex:goto_tab_7
    URxvt.keysym.Meta-F8:       tabbedex:goto_tab_8
    URxvt.keysym.Meta-F9:       tabbedex:goto_tab_9
    URxvt.keysym.Meta-F10:      tabbedex:goto_tab_10
    URxvt.keysym.Meta-F11:      tabbedex:goto_tab_11
    URxvt.keysym.Meta-F12:      tabbedex:goto_tab_12

See ACTIONS AND USER COMMANDS below for list of available actions.

perl-ext-blacklist: string

A comma-separated list of extensions that must not be loaded into the slave terminals (tabs). tabbedex plugin is implicitly added onto the list.

reopen-on-close: boolean

If set, whenever last tab is destroyed a new one will be created.

tabbar-timeouts: string

When new text is written to an inactive tab, activity marks are displayed around its number (or name if it has one) on the tab bar. By default Unicode characters are used to display a block which grows with time the longer it was since last time there was any activity in the tab.

This resource allows for this to be customised. It's format is

    ( <timeout> ":" <character> ":" )* <timeout> ":" <character> ":"

where <timeout> is timeout in seconds and <character> is a single activity character. If activity character is (, [, { or < it will be used as left activity mark and matching character will be used on the right side.

tabbed.tabbedex-rs-prefix: string

A deprecated alternative resource name prefix. It's always specified with tabbed prefix which is also its default value.

If resource using extension's name as well as one using the alternate prefix are found, the former takes precedence. If only the latter is present, its value is used but a warning is issued as well, for example:

    URxvt.tabbed.tabbar-fg:   5   -- ignored
    URxvt.tabbed.tabbar-bg:   0   -- used but issues a warning
    URxvt.tabbedex.tabbar-fg: 4   -- used

For best backwards compatibility, all options should use tabbedex prefix and the <tabbedex-rs-prefix> resource should be to percent sign as in:

    URxvt.tabbed.tabbedex-rs-prefix: %

Extension's behaviour is also influenced by some of URxvt's configuration options as well. (See RESOURCES in the urxvt(1) manpage for more information about them). The options include:

mapAlert

If set, when bell rings in an inactive tab, the tab is made active.

urgentOnBell

If set, when bell rings in an inactive tab, the master terminal's urgency hint is set.

ACTIONS AND USER COMMANDS

tabbedex supports actions which can be bound to keystrokes using URxvt.keysym.keysym resource. For example:

    URxvt.keysym.Control-t:            tabbedex:new_tab
    URxvt.keysym.Control-Tab:          tabbedex:next_tab
    URxvt.keysym.Control-Shift-Tab:    tabbedex:prev_tab
    ! Shift-Tab is often bound to ISO_Left_Tab in X keyboard
    ! layouts.  In those layouts Control-Shift-Tab won't
    ! work and Control-ISO_Left_Tab is needed instead:
    URxvt.keysym.Control-ISO_Left_Tab: tabbedex:prev_tab

makes Ctrl+T create a new tab and Ctrl+Tab and Ctrl+Shift+Tab switch between existing tabs. Using the name of the extension as the prefix of the keysym binding is preferred but when running an ancient urxvt (i.e. anything prior to 9.21) an alternative perl:tabbedex must be used instead.

Supported actions are:

tabbedex:new_tab and tabbedex:new_tab:arguments

Creates a new tab, puts it at the end of the tab list and switches to it. In the second form, arguments temporarily override value of the tab-arguments resource. This makes it possible to create bindings which start particular commands, for example:

    URxvt.keysym.F1:    tabbedex:new_tab:-e info

makes it such that pressing F1 will open a new tab running info command. (Remember that arguments are passed as arguments to urxvt so to run a command -e is required as in example above).

tabbedex:new_tab_side_this and tabbedex:new_tab_side_this:arguments

Like tabbedex:new_tab but puts the new tab before (if side is before) or after (if side is after) the current tab on the tab list. For example,

    URxvt.keysym.C-t:   tabbedex:new_tab_after_this

makes Ctrl+T start a new tab next to the current one.

tabbedex:next_tab and tabbedex:prev_tab

Switches to the tab on the right or left of the current tab.

tabbedex:move_tab_left and tabbedex:move_tab_right

Moves the current tab left or right.

goto_tab_N

If N is a positive integer, switches to the Nth tab. If N is negative, switches to the -Nth tab counting from the last one.

tabbedex:kill_tab

Kills/destroys current tab.

tabbedex:rename_tab

Start renaming the tab.

OSC SEQUENCES

tabbedex supports a single OSC sequence which can be invoked by programs running in the terminal by writing a special sequence, namely ESC ] 777 ; string ST where string is the command to execute. For example:

    printf '\033]777;tabbedex;set_tab_name;%s\007' "foo"
tabbedex;set_tab_name;name

Sets name of the current tab to name.

SEE ALSO

urxvt(1), urxvt-tabbed(1), tabbedex-command-runner(1) and tabbedex-pgid-cd(1)

COPYRIGHT

Copyright 2006-2019 tabbed and tabbedex authors

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

tabbedex has been created (as a fork of urxvt-tabbed(1)) and is maintained by Michal Nazarewicz. For list of authors see AUTHORS file distributed with the extension. Send bug reports and comments to mina86@mina86.com or file them at https://github.com/mina86/urxvt-tabbedex.