xtermcontrol

Home | Contact

Xtermcontrol enables dynamic control of xterm properties. It makes it easy to change colors, title, font and geometry of a running xterm, as well as to report the current settings of these properties. Window manipulations de-/iconify, raise/lower, maximize/restore and reset are also supported.

To complete the feature set; xtermcontrol lets advanced users issue any xterm control sequence of their choosing.

The Make Test Video showcase most of xtermcontrol's options.

Index

Download

Install by issuing 'configure && make install'.

Packages are known to be available for Debian, Ubunto, Gentoo, Arch Linux, NetBSD, FreeBSD, MacPorts via their respective Package Management Systems. Thanks to the maintainers of these packages!

It's also possible to install with Homebrew on macOS as: 

brew create http://www.thrysoee.dk/xtermcontrol/xtermcontrol-3.8.tar.gz
brew install xtermcontrol

Synopsis

xtermcontrol [OPTIONS]...

Options

--fg=COLOR
Set foreground color to COLOR.
--bg=COLOR
Set background color to COLOR.
--colorN=COLOR
Set N'th [0-255] color to COLOR, e.g. --color88=COLOR.
--highlight=COLOR
Set highlight color to COLOR.
--cursor=COLOR
Set cursor color to COLOR.
--mouse-fg=COLOR
Set mouse pointer foreground color to COLOR.
--mouse-bg=COLOR
Set mouse pointer background color to COLOR.
--font=FONT
Set font name to FONT. Alternatively it is possible to specify a fontmenu index as '#[0-6]' or navigate the fontmenu by relative sizes as '#+N' or '#-N', where N is an optional integer.
--title=STRING
Set window title. Note that mechanisms like the Bash PROMPT_COMMAND may overwrite the title. Se also How to change the title of an xterm.
--geometry=WIDTHxHEIGHT+XOFF+YOFF
Set size and/or position. Through its control sequences the xterm only recognize positive XOFF and YOFF offsets, which are pixels relative to the upper left hand corner of the display. xtermcontrol is therefore unable to handle negative offsets as described in the X Geometry Specifications and therefore truncates negative values to zero.
--get-fg
Report foreground color.
--get-bg
Report background color.
--get-colorN
Report N'th [0-255] color, e.g. --get-color88.
--get-highlight
Report highlight color.
--get-cursor
Report cursor color.
--get-mouse-fg
Report mouse pointer foreground color.
--get-mouse-bg
Report mouse pointer background color.
--get-font
Report font.
--get-title
Report window title.
--get-geometry
Report size and position. The size of the text area is reported in characters and the position is reported in pixels relative to the upper left hand corner of the display.
--maximize
Maximize window.
--restore
Restore maximized window.
--iconify
Iconify window.
--de-iconify
De-iconify window.
--raise
Raise window.
--lower
Lower window.
--reset
Full reset.
--raw=CTLSEQS
Issue the raw control sequences CTLSEQS.
--file=FILE
Source a configuration FILE.
--force, -f
Skip TERM environment variable check.
--verbose, -v
Print verbose reports.
--help, -h
Print help and exit.
--version
Print the version number and exit.

Configuration

The default configuration file ~/.xtermcontrol is sourced if xtermcontrol is run without options or if specifically requested, e.g. 'xtermcontrol --file=~/.xtermcontrol'.

Each line in a configuration file is either a comment or contains an attribute. Attributes consist of a keyword and an associated value:

keyword = value # comment

The valid keyword/value combinations are:

foreground="COLOR"
background="COLOR"
cursor="COLOR"
mouse-foreground="COLOR"
mouse-background="COLOR"
geometry="WIDTHxHEIGHT+XOFF+YOFF"
font="FONT"
color0="COLOR"
color1="COLOR"
color2="COLOR"
color3="COLOR"
color4="COLOR"
color5="COLOR"
color6="COLOR"
color7="COLOR"
color8="COLOR"
color9="COLOR"
color10="COLOR"
color11="COLOR"
color12="COLOR"
color13="COLOR"
color14="COLOR"
color15="COLOR"

Whitespace is ignored in attributes unless within a quoted value. The character '#' is taken to begin a comment. Each '#' and all remaining characters on that line is ignored.

Font Names

xtermcontrol accepts any X Font Name.

Font names like '-adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1' are very cumbersome to write, so it is convenient to make use of aliases, e.g. 'fixed' or '8x13', if present in fonts.alias files of the font directories.

Color Names

xtermcontrol accepts any X Color Name.

Basically this means that colors are specified by name or rgb value, e.g. 'blue', 'rgb:0000/0000/FFFF' or '#00F'. Colors are typically reported by the xterm in a device-dependent numerical form, e.g. 'rgb:0000/0000/FFFF'.

Note that old syntax rgb values should always be quoted to avoid '#' being interpreted as the beginning of a comment by the shell.

Xterm Control Sequences

The secret behind xtermcontrol is xterm control sequences. All the possible (there are a plethora of them) control sequences are documented in ctlseqs.ms, found in the xterm distribution. This file is troff formated, so in order to make sense of it, a text file could be generated as follows:

$ nroff -t -c -ms ctlseqs.ms | col -b > ctlseqs.txt

Both ctlseqs.ms and ctlseqs.txt are distributed with xtermcontrol, and can be found in the docs directory.

macOS Terminal.app

The macOS Terminal.app emulates an extended set of the VTxxx series commands, closely resembling dtterm. Therefore the following subset of xtermcontrol options works as expected:

--title
--geometry
--get-geometry
--maximize
--restore
--iconify
--de-iconify
--raise
--lower
--reset

Color names are ignored, but device-dependent numerical form and rgb values works as expected for the following subset of xtermcontrol options (see also COLOR):

--fg
--get-fg
--bg
--get-bg
--cursor
--get-cursor
--mouse-fg
--get-mouse-fg
--mouse-bg
--get-mouse-bg

Examples

It can be very useful to use xterm colors to indicate which is your current user ID. As an example, configure the ~/.xtermcontrol of the login user to:

foreground="black"
and the ~root/.xtermcontrol to: 
foreground="red"

Now the red foreground color works as a reminder of the privileges when logged into the root account.

To change back to current ID preferences after a session, include the following code snippet in the .bashrc shell initialization file of the effected accounts.

# .bashrc example

## customize this and put it in ~/.bashrc to control the xterm

## change preferences to ~/.xtermcontrol defaults
xtermcontrol

## change preferences back to ~/.xtermcontrol defaults after 'su' session
su() {
   command su "$@"
   xtermcontrol
}

## change preferences back to ~/.xtermcontrol defaults after 'ssh' session
ssh() {
   command ssh "$@"
   xtermcontrol
}

This will work equally well when logging into remote accounts. Of course xtermcontrol must be installed on the remote servers in order for it to work.

For further examples of xtermcontrol capabilities view the tests/xtermcontrol.sh in the distribution tarball. Issue 'make test' to execute it.

Troubleshooting

If read/write permissions on the tty's are changed so that special group membership is required to be able to write to the pseudo terminal, the easiest workaround is to install xtermcontrol setuid root.

Xterm has three resources, allowWindowOps, allowTitleOps, and allowFontOps, that enables or disables special operations which xtermcontrol relies on. If any of these resources are set (or defaults) to false xtermcontrol may hang. The resources corresponds to xtermcontrol options as:

allowWindowOps:
--raise
--lower
--restore
--maximize
--iconify
--de-iconify
--get-title
--geometry
--get-geometry
allowTitleOps:
--title
allowFontOps:
--font
--get-font

All three resources can usually be enabled for the current xterm session via a menu; ctrl+rightclick and look for menu item names like 'Allow Window Ops'. To set these resource values persistently you can add the following to either your local ~/.Xdefaults file, or to a system-wide resource file like /etc/X11/app-defaults/XTerm: 

*VT100.allowWindowOps: true
*VT100.allowTitleOps: true
*VT100.allowFontOps: true

Make Test Video

ChangeLog

2021-05-04  Jess Thrysoee

   * Version 3.8

   * tests/xtermcontrol.test: Add ForeAndBackground and CursorAndMouse RGB tests.

   * doc/xtermcontrol.roff: macOS documentation changes

2019-03-27  Jess Thrysoee

   * Version 3.7

   * doc/xtermcontrol.c: Handle negative top left position reported by PuTTY.
	See also https://github.com/JessThrysoee/xtermcontrol/issues/10

2018-12-09  Jess Thrysoee

   * Version 3.6

   * doc/xtermcontrol.c: Add --get-color[0-255] and --color[0-255]
	See also https://github.com/JessThrysoee/xtermcontrol/issues/7

2018-12-09  Jess Thrysoee

   * Version 3.5

   * doc/xtermcontrol.c: OSC string terminator: Always send ST, but accept either ST or BEL. 
	See also https://github.com/JessThrysoee/xtermcontrol/issues/8

   * all: format with clang-format and fix compiler warnings

2018-03-07  Jess Thrysoee

   * Version 3.4

   * doc/xtermcontrol.roff: Correct NAME section in manpage without using a
	 user-defined string.

   * doc/xtermcontrol.roff: Fix minus-vs-hyphen cases in manpage.

2015-12-13  Jess Thrysoee

   * Version 3.3

   * src/xtermcontrol.c: Handle raw read returning -1 and EAGAIN
	See also https://github.com/JessThrysoee/xtermcontrol/issues/6

2013-08-20  Jess Thrysoee

   * Version 3.2

   * doc/xtermcontrol.roff: Document the options that works on OS X Terminal.app

2013-06-09  Jess Thrysoee

   * Version 3.1

   * getopt.c: remove build warning for unused parameter argc and argv

   * autotools: use XTC_PACKAGE_YEAR macro to update copyright year

2013-04-30  Jess Thrysoee

   * Version 3.0

   * all: Major version bump because the strategy of when a configuration
	file is read has changed. Now xtermcontrol only reads the ~/.xtermcontrol file
	if run without options, or if specifically requested by the --file option.
	See also https://github.com/JessThrysoee/xtermcontrol/issues/1

   * src/configuration.c: Prevent the terminal from becomming unresponsive
	when attempting to report the current setting of an unsupported or
	disallowed property.

2013-04-26  Jess Thrysoee

   * Version 2.11

   * src/xtermcontrol.c: Add basic tmux support. Contributed by turlutux.

2009-10-16  Jess Thrysoee

   * Version 2.10

   * doc/xtermcontrol.roff: Update troubleshooting section. Add list
	of which xtermcontrol options are effected by which of the three
	xterm resources allowWindowOps, allowTitleOps, and allowFontOps.
	All of these resorces can be changed in the xterm ctrl+rightclick
	menu, or persistently in ~/.Xdefaults, to avoid xtermcontrol hangs.

   * all: remove compile warnings.

2007-09-03  Jess Thrysoee

   * Version 2.9

   * doc/xtermcontrol.roff: Add note that xterm resource allowWindowOps
	should be set true, to allow xtermcontrol to use extended window
	control sequences, and avoid that it hangs.

2006-02-04  Jess Thrysoee

   * Version 2.8

   * src/configuration.c: Fix regexp, so the '#rrggbb' way to specify a
	color works in configuration file. Reported by Olle Mulmo.

   * doc/xtermcontrol.roff: add BUGS section describing how install needs
	to setuid root on some broken systems.

2004-12-22  Jess Thrysoee

   * Version 2.7

   * configure.ac, src/Makefile.am: remove all dependencies on Xlib.
	Reported by Rich Paul.

2004-10-11  Jess Thrysoee

   * Version 2.6

   * src/xtermcontrol.c: rewrite of --get-* methods. On Cygwin chars are simply
   read (VMIN=)1 at a time.

   *config.guess, config.sub: removed. No need for specific Cygwin test.

   * all: remove --get-raw option. 

2004-10-03  Jess Thrysoee

   * Version 2.5

   * configure.ac: update autotool scripts.

   * all: remove --timeout option. Use VMIN=1 && VTIME=1, this blocks until at
   least one char is available and makes --get-* much faster.
   
   Cygwin does not seem to get this right, as it reads only one char before
   blocking again, i.e. it uses VMIN as the maximum of chars to read in raw
   mode. The workaround is to set VMIN=0 and read nonblocking after a fixed
   timeout. Patch by Mark Paulus.

2004-04-21  Jess Thrysoee

   * Version 2.4

   * doc/xtermcontrol.roff, src/xtermcontrol.h, doc/xtermcontrol.roff: Added
   new option: --timeout

   * doc/ctlseqs.ms, doc/ctlseqs.txt: updated from xterm-186

2004-01-07  Jess Thrysoee

   * Version 2.3

   * src/xtermcontrol.h: don't include X11/Xlib.h, it not needed.

   * doc/xtermcontrol.roff, src/xtermcontrol.c, src/configuration.c,
   src/xtermcontrol.h, src/configuration.h: Update Copyright year. 

   * doc/xtermcontrol.roff: update documentation of the --font option with the
   syntax of how to access the fontmenu.

   NOTE: The implementation of the negative relative size fontmenu navigation
   at xterm patch level #184 has a typo preventing it from working correctly.
   This has been reported to the xterm maintainer.

2003-09-07  Jess Thrysoee

   * Version 2.2

   * src/configuration.c, src/xtermcontrol.c: compile without errors and
   warnings with g++

2003-08-17  Jess Thrysoee

   * Version 2.1 (only one minor version number is needed)

   * geometry.c: Source file removed. As of xterm patch #168 the window
   position bug has been fixed, so the Xlib workaround is no longer needed.

   * all: Added new options: --[get-]colorN
                             --[get-]highlight
                             --force
                             --reset
                             --get-raw

   NOTE: Setting highlight does not work at xterm patch level #179. A patch
   for this has been accepted by the xterm maintainer, so presumably, it
   should be fixed in the next release, i.e. #180.

2002-10-26  Jess Thrysoee

   * Version 2.0.2

   * src/configuration.c: Problem: configuration files take no effect.
   Solution: remove newline from fgets input when reading key/value pairs
   from configuration file.

   * src/xtermcontrol.c: remove trailing whitespace from configuration file


2002-10-20  Jess Thrysoee

   * Version 2.0.1

   * src/configuration.c: included OpenPKG.org patch.

   * configure.in: exit configure when X libs/includes not located

   * doc/xtermcontrol.spec: added rpm spec file.

2002-09-19  Jess Thrysoee

   * Version 2.0.0

   * all: Complete rewrite. Rename project from xtermcolors
   to xtermcontrol.

2002-05-18  Jess Thrysoee

   * Version 1.0.0

   * all: Initial version.
©2002-2024 THRYSOEE