xtermcontrol

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.

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-15] color.

--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.

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.

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.

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.

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:

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.