ScreenShot plugin for Take Command / TCC / TCC/LE

Version 1.1.3.2 2024-04-02

Charles Dye

Purpose:

This plugin provides an easy way to create screen shots from the command line or a batch file. It adds one new command, SCREENSHOT, and one new variable, _LASTSSFILE.

Installation:

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

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

If you copy this file to a subdirectory named PlugIns within your Take Command program directory, it will be loaded automatically when TCC starts.

Plugin Features:

New command: SCREENSHOT

New variable: _LASTSSFILE

Syntax Note:

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

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

New Command:

SCREENSHOT — Save a picture of a window or the desktop.

Syntax:
SCREENSHOT /A /C /D /E /F /H:hwnd /K:class /M:n /O /P:pid /Q /R:resize /T /W:title /X:text filename

`/A`	desktop, all monitors
`/C`	client area of the window only
`/D`	desktop (default)
`/E`	entire window area
`/F`	the foreground window
`/H:`hwnd	window handle
`/K:`class	window class; wildcards are okay
`/M:`n	monitor number, 0-based; implies `/D`
`/O`	overwrite any existing file
`/P:`pid	process ID; decimal or hex with leading `0x`
`/R:`resize	resize the image
`/Q`	quietly (no success message)
`/T`	Take Command’s window
`/W:`title	window title; wildcards are supported
`/X:`text	add text to the snapshot
filename	may be `CLIP:` or `PRINT:` Directory aliases are OK

This command saves a picture of a window, or of the desktop, to a file or to the clipboard. To capture the desktop, specify /D — or no options; /D is the default mode. In a multiple-monitor system, you can specify a monitor with /M:n. The monitor number n is zero based; use /M:0 for the first monitor, /M:1 for the second, and so on. You can also use /M:128 to capture the entire virtual desktop.

screenshot /d

/A captures the entire desktop across all monitors. /A is just an abbreviation for /M:128.

To capture a single window, use either /F, /H:, /T, or any combination of /K:, /W:, and /P: to specify the window:

/F captures the foreground window.
/H:hwnd captures the window with the specified window handle.
/T captures the Take Command window.
/W:, /P:, and /K: search for a window matching the specified conditions; these three may be combined as needed.

/W:title finds a window with a matching title; you can use wildcards in title. /P:pid finds a window owned by the specified process ID. /K:class finds a window of the specified window class; you can use wildcards in class also. SCREENSHOT will capture the first top-level window it finds which matches all of the given conditions.

With any of the above window options, you can also add /C to capture only the window’s client area, minus the window frame and title bar. Note that /C may fail horribly with programs such as Google Chrome and Microsoft Edge, which use video acceleration.

screenshot /w:*notepad

/E uses the window’s own context to capture the entire window. This is the old behavior, the way ScreenShot worked before version 1.1. It may fail with programs such as Google Chrome and Microsoft Edge, which use video acceleration. /E might be useful for capturing windows which are partly or completely off-screen.

You can specify the filename for the image file. If the specified filename exists, SCREENSHOT will give an error message unless you also specify /O. Directory aliases and CLIP: are supported. The filename must end in one of these supported extensions:

`.bmp`
`.jpg` or `.jpeg`
`.png`
`.gif`
`.tif` or `.tiff`

If filename is not specified, or if it names a directory, SCREENSHOT will generate a filename from the current date and time. Generated filenames will end in .png by default. You can choose a different file type for auto-generated filenames by setting an environment variable SCREENSHOTEXT to one of the supported extensions above. Only the extensions listed above will work, and the leading dot is required. The file will be created in the current working directory, unless you specify a directory on the command line or set an environment variable SCREENSHOTPATH.

screenshot /d desktop.jpg set screenshotext=.jpeg screenshot /d

You may also specify PRINT: as a filename. In this case, SCREENSHOT will dump the screen shot to your default printer. Printing is very basic; there is no header or footer, and your printer’s default preferences will be used. For more sophisticated printing, use CLIP: instead and paste the image into any graphics editing program.

The /R: option allows you to resize the image when saving it to a file. You can specify the new size as a percentage, or as a pixel width and height. To give a percentage, type two percent signs after the value:

screensave /r:85%% test.jpg

You need to double the percent sign because TCC’s variable expansion will swallow a single percent sign.

Alternatively, you can specify an absolute pixel width and height:

screensave /r:1024,768 test.jpg

You can omit either the new width or the new height, but not both:

rem To specify a new width (the height will be kept proportional) screensave /r:512 test.jpg ren To specify a new height (the width will be kept proportional) screensave /r:,384 test.jpg

/R: is ignored if the filename is PRINT:

You can add text to the snapshot with /X:text. Quote the text if it contains spaces or other special characters. There is also a handful of options to format the text; these must come before the /X:text.

`/XS:`size	specify the text size	`/XS:12`
`/XF:`face	specify the typeface	`/XF:Georgia`
`/XC:`color	specify the color	`/XC:Orange`
`/XX:`x	specify the left edge	`/XX:50`
`/XY:`y	specify the top edge	`/XY:0`
`/XB`	boldface text
`/XI`	italic text
`/XU`	underline text
`/XN`	regular text

These options only affect /X:text options which follow them.

Note that /XC: uses W3C color names, not the (much shorter) list of CGA colors supported by most TCC commands. You can find a list of W3C colors here or here or here. You can also specify RGB values in hexadecimal, as /XC:#rrggbb.

rem Add a big yellow date and time: screenshot /d /xs:48 /xx:10 /xy:10 /xc:yellow /x:"%_date %_time" test.png

SCREENSHOT returns:

0	success
1	error on command line: unknown option, bad value, etc.
2	operational error: can’t find window, file error, etc.

New Variable:

_LASTSSFILE — Returns the filename of the last screen shot.

Syntax:
%_LASTSSFILE

If the last call to SCREENSHOT saved successfully to a file or the clipboard, this function will return the complete filename. If an error was encountered, it will return *Error*. If SCREENSHOT has not been called yet, this variable returns an empty string.

echo %_lastssfile

This might be useful after SCREENSHOT generates its own filename.

Control Variables:

You can set environment variables to control the default behavior of SCREENSHOT.

SCREENSHOTEXT: Sets the extension used when generating a filename. It must be one of the following, and the leading period is required.

`.bmp`
`.jpg` or `.jpeg`
`.png`
`.gif`
`.tif` or `.tiff`

SCREENSHOTPATH: Sets the default location for screenshot files. The default is the current directory.

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

Changes:

1.1.3.2	2024-04-02	Minor tweak to FindMyWindow.cpp: now Windows Terminal detection does not rely on the `WT_SESSION` environment variable.
1.1.3.1	2024-03-13	Minor tweaks to ForceForegroundWindow().
1.1.3	2023-12-06	In the default operating mode (without `/C` or `/E`), does a better job of finding the window’s edges. Replaced GetTakeCommandWindow() with FindMyWindow.cpp; now `/T` should also find Windows Terminal, ConEmu, and Console2 windows. If the window is of a class known to use hardware acceleration (Google Chrome, MS Edge, Firefox, Windows Terminal), `/C` and `/E` will be disabled automatically. Cosmetic: Changed a bunch of ASCII apostrophes to fancy Unicode quotes, mostly in error messages.
1.1.2.3	2023-10-15	Tweaked ShowCmdHelp() to include `VER_PATCH`.
1.1.2.2	2023-10-12	Updated the plugin’s web address.
1.1.2.1	2023-07-25	Updated ParseArgs.cpp and w3ccolors.cpp to the current versions.
1.1.2	2021-12-22	No longer call TakeCommandIPC() dynamically. That hasn’t been necessary for a long, long time.
1.1.1	2021-12-21	Fixed an issue calling TakeCommandIPC() from 64-bit TCC.
1.1.0	2021-11-11	Now it works, mostly, with programs like Chrome and Edge which use video acceleration. (`/C` still fails.) Added `/E` to return to the original behavior. Now `/D` with no monitor specified defaults to the default monitor, not necessarily monitor #0. Now `SCREENSHOT` gets the correct resolution for monitors with differing DPI scaling. Documented `/A`; removed `/C` from the `/?` help text.
1.0.1	2021-07-08	Changes to the VerInfo structure. Switched the filenames; now ScreenShot.dll is the 64-bit file.
1.0.0	2017-11-29	First release.

Status and Licensing:

This plugin is © Copyright 2024, Charles Dye. Unaltered copies of the binary and documentation files may be freely distributed without restriction. I make no guarantee and give no warranty for its operation. If you find a problem, you can report it in the JP Software support forum.

Download:

You can download the current version of the plugin from http://charlesdye.net/dl/screenshot.zip.

— Quick Links —