WindowInfo plugin for Take Command / TCC / TCC/LE

beta version 0.95.3 2025-03-26

Charles Dye

Purpose:

This plugin adds a few new functions to find windows and return information about them. I also include one new command to list windows using a user-defined format string.

Installation:

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

plugin /l c:\bin\tcmd\test\windowinfo.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 Commands:
`LISTWINDOWS`
New Functions:
`@HWNDPID`	`@PIDHWND`	`@PIDHWNDS`	`@TITLEHWND`	`@WINALPHA`
`@WINMONITOR`	`@WINOWNER`	`@WINPARENT`	`@WINSNAPPED`	`@WINSTYLES`
`@WINSTYLESEX`	`@WINVDESK`

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.

Examples are shown in a gray box:

rem This is an example: listwindows /c:*console*

Some command options take an argument. These are shown with a colon between the option and its argument: /A:arg

If you like, you may substitute an equals sign for the colon: /A=arg This is handy if the arg is a filename, and you want to use tab completion to enter the filename.

Or you can omit the colon: /Aarg

New Commands:

LISTWINDOWS — List windows, using a user-defined format string.

Syntax:
LISTWINDOWS /C:class /E:prog /F:"fmt" /I /L:n /O:flags /P /R /T:title /V /W:win

`/C:`class	filter top-level windows by class name (supports wildcards)
`/E:`prog	list windows created by the specified program (name or PID)
`/F:"`fmt`"`	format string
`/I`	invisible windows only
`/L:`n	line length
`/O:`flags	sort windows
`/P`	page output
`/R`	list child windows recursively
`/T:`class	filter top-level windows by title (supports wildcards)
`/V`	visible windows only
`/W:`win	list child windows of the specified window (title or handle)

With /E:prog, this command lists all top-level windows created by the specified program. With /W:win, this command lists all child windows of the specified window. With neither /E: nor /W:, it lists all top-level windows.

If no /F:"fmt" is given, the default format string is "$08h: $v $-25c \u201c$t\u201d" to list each window’s handle, visibility, class name, and title.

/E:prog lists windows created by a specific program. The prog may be either a process ID or a filename. If it’s a process ID, you can enter it in decimal, or hexadecimal with a leading 0x. Only windows created by that one specific process will be listed.

If it’s a filename, it much match exactly (no wildcards). You can enter either a base name (e.g. /E:tcc.exe ) or a complete pathname (e.g. /E:c:\bin\tcmd34\tcc.exe ). This syntax can match multiple processes — you might have multiple copies of the same program running at once. If you try to combine a process ID with a filename, the process ID wins; the filename will be ignored.

/O: can sort by several criteria. The available sort keys are:

`C`	sort by window class
`P`	sort by process ID
`R`	sort by thread ID
`S`	sort by styles word
`T`	sort by title
`V`	sort by visibility
`W`	sort by window handle
`X`	sort by extended styles word
`-`	reverses the following key

These can be combined, e.g. /O:CT to sort by window class name first, then by title where two windows have the same class. If you do not give any /O:flags, the default is to sort by window handles. To disable sorting altogether, you can use /OU.

Format String:

These are the tokens supported in the format string:

Token:	Gives:
`$c`	the window’s class name
`$h`	the window handle
`$p`	the window owner’s pid
`$s`	the window’s styles word
`$t`	the window’s title
`$v`	`V` for visible or `I` for not visible
`$x`	the window’s extended styles word
`$H`	the window’s height
`$N`	the name of the program which created the window
`$O`	the handle of the window’s owner window
`$P`	the handle of the window’s parent window
`$V`	the name of the window’s virtual desktop, if available
`$W`	the window’s width
`$X`	the window’s left edge
`$Y`	the window’s top edge
`$$`	dollar sign

You can use modifiers between the dollar sign and the letter to change how the value is displayed:

Modifier:	Changes the value:
`-`	left-aligns a field
`0`	zero-pads a numeric field
`#`	uses decimal instead of hex
`!`	forces uppercase
`,`	forces lowercase
width	set the field’s width (decimal only)

A few character escapes are also supported:

Escape:	Gives:
`\e`	ASCII escape
`\k`	backquote
`\n`	newline
`\p`	percent sign
`\q`	double quote
`\r`	carriage return
`\t`	tab
`\\`	backslash
`\u`nnnn	Unicode character, up to U+FFFF
`\U`nnnnnn	Unicode character, up to U+10FFFF

New Functions:

@HWNDPID — Returns the process ID of the process which created a given window.

Syntax:
%@HWNDPID[hwnd,flags]

hwnd	the window’s handle; decimal or hex with a leading `0x`
flags	bitmapped:
	1: return process ID in hexadecimal

This function only takes a window handle, not a title. It’s basically a wrapper around the Windows GetWindowThreadProcessId() function.

If the specified window does not exist, or on any other error, this function returns 0.

@PIDHWND — Searches for a window created by the specified process, and returns its handle.

Syntax:
%@PIDHWND[program,flags]

program	program name or process ID; wildcards are supported
flags	bitmapped:
	1: return handle in hexadecimal

You can specify the program as:

a filename with extension, e.g. NOTEPAD.EXE
a base name, e.g. NOTEPAD; .* is assumed
a fully-qualified filename, e.g. C:\WINDOWS\SYSTEM32\NOTEPAD.EXE
a process ID in decimal, e.g. =5892
a process ID in hexadecimal, e.g. =0x1704

@PIDHWND returns the window handle (HWND) of a matching window. If no matching window is found, @PIDHWND returns 0.

Note that a process may have no windows, one window, or many windows. The window that @PIDHWND chooses may not necessarily be the same one that you would pick. To get a list of all top-level windows created by a process, use @PIDHWNDS.

@PIDHWNDS — Returns a list of windows created by the specified process.

Syntax:
%@PIDHWNDS[program,flags]

program	program name or process ID; wildcards are supported
flags	bitmapped:
	1: return handles in hexadecimal
	128: sort the list into ascending order

You can specify the program as:

a filename with extension, e.g. NOTEPAD.EXE
a base name, e.g. NOTEPAD; .* is assumed
a fully-qualified filename, e.g. C:\WINDOWS\SYSTEM32\NOTEPAD.EXE
a process ID in decimal, e.g. =5892
a process ID in hexadecimal, e.g. =0x1704

Window handles will be returned as a space-separated list of decimal or hexadecimal numbers.

If no matching process is found, or if no windows belong to that process, then @PIDHWNDS will return an empty string.

@TITLEHWND — Searches for a window with a matching title, and returns its handle.

Syntax:
%@TITLEHWND[title,flags]

title	wildcards are supported
flags	bitmapped:
	1: return handle in hexadecimal

@TITLEHWND returns the window handle (HWND) of a matching window. If no matching window is found, @TITLEHWND returns 0.

@WINALPHA — Searches for a matching window, and returns its alpha transparency.

Syntax:
%@WINALPHA[window,flags]

window	window title, program name, PID, or HWND
flags	bitmapped:
	1: return alpha value in hexadecimal

The return value ranges from 0 (completely transparent; invisible) to 255 (completely opaque). If the window is not using alpha transparency, the return value is 255. If no matching window is found, @WINALPHA will return 00.

@WINMONITOR — Searches for a matching window, and returns the monitor on which it appears.

Syntax:
%@WINMONITOR[window,flags]

window	window title, program name, PID, or HWND
flags	bitmapped:
	1: return a monitor name; otherwise it’s a monitor number

@WINMONITOR returns a monitor index: 1 for the first monitor, 2 for the second, and so on. If no matching window was found, or if the window does not overlap any display monitor, @WINMONITOR returns 0.

@WINOWNER — Searches for a window, and returns its owner window’s handle.

Syntax:
%@WINOWNER[window,flags]

window	window title, program name, PID, or HWND
flags	bitmapped:
	1: return window handle in hexadecimal

If no matching window is found, the return value will be 0.

Windows Searches:

Most of the functions in this plugin have a window argument to search for a window. You can specify the window in a number of ways. If you want to match against titles, quote this parameter. If you want to match against program names, do not quote it.

• Search for a matching window title:	`"VISUAL"`
• Search for a filename with an extension:	`NOTEPAD.EXE`
• Search for a base name:	`NOTEPAD` (`.*` is assumed)
• Search for a fully-qualified filename:	`C:\WINDOWS\SYSTEM32\NOTEPAD.EXE`
• Search for a process ID in decimal:	`=5892`
• Search for a process ID in hexadecimal:	`=0x1704`
• Pass a window handle:	`HWND==0x002D0B12` (NB: two equals signs)
• Use TCC’s own display window:	`ME`
• Use the current foreground window:	`FG`

The first four support wildcards.

When you search by titles, the function will temporarily set TCC’s console window title to an empty string. This step prevents accidental wildcard matches against the console window, Take Command’s window, or the Windows Terminal window.

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.

WindowInfo 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 this plugin from https://charlesdye.net/dl/windowinfo.zip.

— Quick Links —