ReadColor plugin for Take Command / TCC / TCC/LE

beta version 0.91.0     2021-08-08

Charles Dye

Purpose:

This plugin provides a @READCOLOR function, which returns console attributes much as @READSCR returns console characters.

Installation:

To use this plugin, copy ReadColor.dll to to some known location on your hard drive. (If you are using the 32-bit version of Take Command, take ReadColor-x86.dll instead of ReadColor.dll.) Load the .DLL file with a PLUGIN /L command, for example:

plugin /l c:\bin\tcmd\test\readcolor.dll

If you copy these files to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.

Plugin Features:

New function: @READCOLOR

Syntax Note:

The syntax definitions in the following text use these conventions for clarity:

BOLD CODEindicates text which must be typed exactly as shown.
CODEindicates optional text, which may be typed as shown or omitted.
Bold italicnames a required argument; a value must be supplied.
Regular italicnames an optional argument.
ellipsis…after an argument means that more than one may be given.

New Function:

@READCOLOR — Reads one or more character attribute cells.

Syntax:
%@READCOLOR[row,col,len,flags]

rowthe row at which to begin reading
colthe column at which to begin reading
lenthe number of attribute cells to read
flagsthe output format

If row or col begins with a + or - sign, it is relative to the cursor; otherwise it’s relative to the top left of the visible window. The row must be within the visible window.

Len may be 1 to 1024; the default is 1.

Flags controls the output format:

Flags:Format:Example:
0decimal (the default)11
1hexadecimal0B
2hexadecimal with leading 0x0x0B
3color namesBright Cyan on Black
4color names, abbreviatedBri Cya on Bla
5foreground color name onlyBright Cyan
6foreground color name, abbreviatedBri Cya

For the numeric formats (0 through 2), you can add 128 to the flags value to return only the low bytes of the attributes, or add 256 to return only the high bytes.


set scrattr=%@readcolor[0,0,20]



Startup Message:

This plugin displays an informational line when it initializes. The message will be suppressed in transient or pipe shells. You can disable it for all shells by defining an environment variable named NOLOADMSG, for example:

set /e /u noloadmsg=1

Status and Licensing:

Consider this beta software. It may well have issues. Try it at your own risk. If you find a problem, you can report it in the JP Software support forum.

ReadColor is currently licensed only for testing purposes. I may make binaries and source code available under some free license once I consider it ready for use.

Download:

You can download the current version of the plugin from http://prospero.unm.edu/dl/readcolor.zip or ftp://prospero.unm.edu/readcolor.zip.