OSD plugin for Take Command / TCC / TCC/LE
Version 1.0.11.6 2024-04-02
Charles Dye
Purpose:
This plugin implements an enhanced version of the OSD
command. It’s intended to be backwards-compatible with the built-in
OSD, while providing nicer syntax and many more features. Of course,
using any of the new features or syntax will break TCC compatibility.
Installation:
To use this plugin, copy OSD.dll to
some known location on your hard drive. (If you are using the 32-bit
version of Take Command, take OSD-x86.dll
instead of OSD.dll.) Load it with a
PLUGIN /L command, for example:
plugin /l c:\bin\tcmd\test\osd.dll
If you copy this file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.
Plugin Features:
New commands: OSD, OSDIMG,
PCTBAR
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 Commands:
OSD — Display text on the screen.
Syntax:
OSD /C=n /FONT=n /ID=n /N /POS=y,x /RGB=r,g,b /TIME=n /V text
| Compatible features: | |
/C | close any OSD windows with ID #0 |
/C=n | close any OSD windows with ID #n |
/FONT=n | text height in pixels; the default is 18 |
/ID=n | specify an ID number; defaults to 0 |
/N | don’t wait for the OSD window to time out |
/POS=y,x | set OSD window position; defaults to 0,0 |
/RGB=r,g,b | text color; the default is 0,255,0 (bright green) |
/TIME=n | in seconds; the default is 10 |
/V | vertical text |
/LEFT, /RIGHT, /HCENTER | override any /POS= x value |
/TOP, /BOTTOM, /VCENTER | override any /POS= y value |
| text | any leading or trailing whitespace will be stripped |
| New features — incompatible with TCC: | ||
/FONT=n | /H=n | may be abbreviated |
/TIME=n | /T=n | may be abbreviated |
/LEFT | /L | may be abbreviated |
/RIGHT | /R | may be abbreviated |
/TOP | /T | may be abbreviated |
/BOTTOM | /B | may be abbreviated |
/HCENTER | /HC | may be abbreviated |
/VCENTER | /VC | may be abbreviated |
/CENTER | /CTR | combines /HCENTER and /VCENTER |
/MONITOR=n | /M=n | monitor number |
/TAB | position relative to Take Command tab window | |
/OFFSET | /POS=y,x coordinates are relative to /TOP, /BOTTOM, /LEFT, etc. | |
/CA | close all OSD windows, regardless of ID | |
/FADE | /F | fade the window out when the time expires |
/FADENOW | fade out and close any OSD windows with ID #0 | |
/FADENOW=n | fade out and close any OSD windows with ID #n | |
/CJ | center-justify text; useful with multiline text and @files | |
/RJ | right-justify text; useful with multiline text and @files | |
/LJ | left-justify text; useful with multiline text and @files (default) | |
/UC | uppercase text | |
/FACE=name | /F=name | typeface name; quote it if it contains spaces |
/ITALIC | /I | italic typeface |
/UNDERLINE | /U | underline text |
/BOLD=n | /B=n | text weight, 0 - 9; 0 don’t care, 1 thin, 4 normal, 7 bold, 9 heavy |
/MS=n | specify time in milliseconds rather than seconds | |
/COLOR=n | /K=n | specify color as a TCC color number, 0 - 15 |
/HUE=name | specify color as a W3C color name | |
/SHADOW | /DS | add a drop shadow |
/ALPHA=n | /A=n | transparency; n is 48 (ghostly) to 255 (opaque) |
/FADEIN | /FI | fade the OSD window in before starting the timer |
/BLINK | flash the text obnoxiously | |
/UP | rotate the window 90° left | |
/DOWN | rotate the window 90° right | |
/Q | with /C, suppress window-not-found error messages | |
/X | expand escape sequences in the text string | |
/MAXLINES=n | maximum lines to read from an @file, 1 to 64; default 5; 0 disables @files | |
/CP=n | specify the code page for an @file | |
/SAVE=n | save a style for use in later OSD calls | |
/STYLE=n | /n | recall a style saved by /SAVE |
• text may instead be an @file; up to five lines (or per /MAXLINES) will be read. | ||
| • Option-argument separator: You can use a colon instead of an equals sign. | ||
• Integer arguments: You can give these in hexadecimal with a leading 0x. | ||
| • Window ID: May be 0 - 1023 (the internal command’s range is 0 - 9) | ||
• /C=n or /CA may be combined with text. | ||
• Exit code: OSD returns 3 if it was interrupted by Ctrl-Break or Ctrl-C. | ||
Using any of the options listed under “New features” will break compatibility with TCC.
Leading and trailing spaces will be stripped from the text.
If you really want leading (or trailing) spaces, you can protect them with a leading
(or trailing) %@CHAR[0x200B]. This is the Unicode “Zero
Width Space”, which iswspace() doesn’t recognize as
whitespace. (This trick also works in TCC’s native OSD.)
The /MONITOR=n
option allows you to specify the monitor used by the /LEFT, /RIGHT,
/HCENTER, /TOP, /BOTTOM, /VCENTER,
and /CENTER options. (It does not affect absolute screen coordinates
specified via /POS=y,x.)
n is 0 to the number of monitors. If
n is 0 or greater than the number of monitors
present, the default monitor (the one with the taskbar) will be used instead.
You can also type /MONITOR=-1 to use the entire virtual desktop
area spanning all monitors. Of course, this option is only useful in a
multiple-monitor system.
The /FACE=name
option allows you to specify the typeface used for the text.
If you don’t use this option, the default is Verdana. If the typeface name
contains spaces, double-quote it. Instead of a typeface name, you can give a
family name in parentheses, and OSD will use the first TrueType font of that
type that it finds. These are the supported families; note that the parentheses
are required:
| family | description | example |
(Roman) | a serif typeface | Times New Roman |
(Swiss) | a sans-serif typeface | Arial |
(Modern) | an unstressed typeface; most are fixed-pitch | Courier New |
(Script) | a handwriting typeface | Comic Sans MS |
(Decorative) | decorative, fantasy, wingdings, etc. | Bauhaus 93 |
The /FADE option causes the OSD window
to fade away smoothly when the timeout expires. This fadeout only happens at the
timeout. If the OSD window is closed for any other reason — Ctrl-Break
was pressed (without /N) or a later OSD /C closes a window
opened with /N, or if the plugin is unloaded — the fade will
not be performed. /FADE will not work in 256-color mode.
If /N is used, you may specify a timeout
of zero, and the OSD window will hang around indefinitely. Use OSD /C
to close it. If /N is not specified, the timeout must be nonzero.
/HUE=name
lets you specify the color as a W3C color name.
Case is not significant, and color names containing ‘gray’ may be spelled
using ‘grey’ if you prefer. You can also use hexadecimal color values like
/HUE=#E6E6FA or /HUE=#6CF (the value must be either three or
six hex digits).
/SAVE=n
saves the current text style for use in later OSD commands. The
valid range for n is 1 to 4096. Only text appearance
settings will be saved; /SAVE does not record behavior settings
like the timeout, screen position, fading, and so on. The settings that are
saved include:
| • the typeface | /FACE |
| • the text height | /FONT |
| • the text weight | /BOLD |
| • italics and underlining | /I and /U |
| • the color | /RGB, /COLOR, or /HUE |
| • drop shadows | /SHADOW |
| • the alpha value | /ALPHA |
Use this option to simplify batch files with many OSD commands by
eliminating repeated /FACE, /FONT, /COLOR,
etc. options. If n is in the range 1 to
100, the text appearance will be saved as a global style: it will
affect other instances of TCC, and it will be remembered after you unload the
plugin or exit the shell. If n is greater than 100,
the new style will only affect the current shell, and it will be lost when you
unload the plugin or exit the shell. In most cases you should use private
styles, i.e. values greater than 100.
/STYLE=n
reloads a style saved by a previous /SAVE=n.
N is 1 to 4096. /STYLE=n
can be abbreviated to just /n. For
example, /101 is equivalent to /STYLE=101.
/C and its variants only close OSD
windows created by this plugin in the current instance of TCC;
it will not close OSD windows created by TCC’s internal OSD,
or by other shells.
You may combine /C, /C=n,
/CA, or /FADENOW with text
to close old OSD windows while creating a new one. For example, you could use:
osd /n /time=0 /c=5 This is a test.
... to close all OSD windows with ID #5 while creating a new one, also with
ID #5. You can use this feature to smoothly replace one OSD with another.
Note that this syntax is not compatible with TCC’s internal OSD
command.
When displaying an OEM text file with
@file, you can use
/CP:n to specify the code page.
Supported values for /CP include:
| 437 | United States (OEM) | 1250 | Central Europe |
| 720 | Arabic (OEM) | 1251 | Cyrillic |
| 737 | Greek (OEM) | 1252 | Latin I |
| 775 | Baltic (OEM) | 1253 | Greek |
| 850 | Multilingual Latin I (OEM) | 1254 | Turkish |
| 852 | Latin II (OEM) | 1255 | Hebrew |
| 855 | Cyrillic (OEM) | 1256 | Arabic |
| 857 | Turkish (OEM) | 1257 | Baltic |
| 858 | Latin I with Euro sign (OEM) | 1258 | Vietnam |
| 862 | Hebrew (OEM) | 10000 | Mac OS Roman |
| 866 | Russian (OEM) | 20866 | KOI8-R (Russia) |
| 874 | Thai (OEM) | 21866 | KOI8-U (Ukraine) |
| A or ANSI | the current Windows code page | ||
| O or OEM | the current OEM code page | ||
This option does not affect Unicode text files, including UTF-8. If you do
not use /CP:n, the default is the
current Windows code page.
Examples:
rem Using TCC-compatible syntax:
osd /time=3 /hcenter /top /font=54 This is only a test!
rem This does the same thing, but is shorter:
osd /t:3 /hc /t /h:54 This is only a test!
rem Add some fancy options:
osd /t:3 /hc /t /h:54 /face:Georgia /k:11 /ds /fade This is only a test!
rem Create a style #201 ...
osd /face:"Century Gothic" /h:36 /hue:NavajoWhite /shadow /save:201
rem ... and use it in later calls to OSD:
for /l %i in ( 0, 50, 300 ) osd /n /pos:%i,%i /t:5 /201 This is a test.
OSDIMG — Display a graphical
image on-screen.
Syntax:
OSDIMG /N /POS=y,x /TIME=n /SIZE=w,h /ID=n /C /I=n /BG filename
/N | don’t wait for the OSD window to time out |
/POS=y,x | set OSD window position; defaults to 0,0 |
/TIME=n | in seconds; the default is 4 |
/SIZE=w,h | set the window size, in pixels (200,0) |
/ID=n | specify an ID number; defaults to 998 |
/C | also close any OSD windows with the same ID |
/ALPHA=n | transparency; n is 48 (ghostly) to 255 (opaque) |
/FADE | fade the window out when the time expires |
/LEFT, /RIGHT, /HCENTER | override any /POS= x value |
/TOP, /BOTTOM, /VCENTER | override any /POS= y value |
/I=n | icon index |
/BG | make the color at the top left corner transparent |
| filename | the file containing the image to display |
This command displays a graphic in an OSD window. OSDIMG
suports many of the same options and abbreviations as OSD,
including some not listed in the table above.
The filename may be a BMP, GIF, JPEG, PNG, or
TIFF file. You can also extract an icon from an .exe
or .dll file; use /I=n
if the file contains more then one icon.
/SIZE=w,h
sets the size of the OSD window, in pixels. At present, these can range from
16 to 1024, or 0 for ‘unspecified’. If one dimension is unspecified,
OSDIMG will scale the image to fit the other, while preventing
either dimension from exceeding 1024.
The /C option works differently than
in the OSD command. You use it together with a
num argument, to display a new graphic and
simultaneously close any open OSD windows with the same ID number
(998 by default). If you want to close an open OSDIMG window
without creating a new one, use OSD /C=998. Note that any old
windows are closed after the new one is created — this is
to reduce flicker. If for some reason the new window cannot be created, then
the /C close operation will not be performed.
Examples:
rem Show a little enterprise:
osdimg /ctr /size=500 /fade NCC-1701.jpg
ren How about an icon?
osdimg /size=128 /bg /i=12 "%windir\system32\shell32.dll"
• Note: This command does not exist in TCC.
PCTBAR — Display an on-screen
percentage bar.
Syntax:
PCTBAR /N /POS=y,x /RGB=r,g,b /TIME=n /SIZE=w,h /ID=n /C /COLOR=n /ALPHA=n /FADE num/denum
/N | don’t wait for the OSD window to time out |
/POS=y,x | set OSD window position; defaults to 0,0 |
/RGB=r,g,b | text color; the default is 0,255,0 (bright green) |
/TIME=n | in seconds; the default is 4 |
/SIZE=w,h | set the window size, in pixels (200,40) |
/ID=n | specify an ID number; defaults to 999 |
/C | also close any OSD windows with the same ID |
/V | also show the value as a percentage |
/COLOR=n | specify color as a TCC color number, 0 - 15 |
/ALPHA=n | transparency; n is 48 (ghostly) to 255 (opaque) |
/FADE | fade the window out when the time expires |
/LEFT, /RIGHT, /HCENTER | override any /POS= x value |
/TOP, /BOTTOM, /VCENTER | override any /POS= y value |
| num | the numerator; required |
/denom | the denominator; defaults to 100 |
This command displays a simple percentage bar on the screen. It might be
useful for a sound-volume indicator or a progress bar. PCTBAR
supports many of the same options and abbreviations as
OSD, including many not listed here. You may use a colon
instead of an equals sign as the option-argument separator.
The /C option works differently than
in the OSD command. You use it together with a
num argument, to display a new percentage bar and
simultaneously close any open OSD windows with the same ID number
(999 by default). You can use this to create the illusion of animation,
replacing an old window with a new one. If you want to close an open
PCTBAR window without creating a new one, use
OSD /C=999. Note that any old windows are closed after
the new one is created — this is to reduce flicker. If for some
reason the new window cannot be created, then the /C close
operation will not be performed.
/V causes the value to also be
shown as a numeric percentage. This option will be ignored if the window
is less than 40×16 pixels.
Example:
rem Display a progress bar at 42% :
pctbar /top /hcenter 42
rem Animate it:
for /l %i in ( 0, 4, 100 ) do ( pctbar /n /c /t /hc /fade %i & delay /m 100 )
• Note: This command does not exist in TCC.
New Variables:
_OSD — Returns the number of OSD
windows currently open.
Syntax:
%_OSD
If you have opened OSD windows with OSD /N,
OSDIMG /N, or
PCTBAR /N, you can use this variable to
check whether any are still present. Only OSD windows opened by this plugin, in
the current shell, will be counted.
• Note: This variable does not exist in TCC.
_OSDVER — Returns the version
of OSD in this plugin.
Syntax:
%_OSDVER
• Note: This variable does not exist in TCC.
New Function:
@OSD — Returns the number of OSD
windows with the given ID currently open.
Syntax:
%@OSD[id]
If you have opened OSD windows with OSD /N,
OSDIMG /N, or
PCTBAR /N, you can use this function to
check whether any are still open. Only OSD windows with the specified ID, opened
by this plugin in the current shell, will be counted. If you do not specify an
id, the default is zero.
• Note: This function does not exist in TCC.
Common Options:
These options are supported by OSD,
OSDIMG, and PCTBAR:
/LEFT | /L | position at left of monitor/desktop/tab |
/RIGHT | /R | position at right of monitor/desktop/tab |
/HCENTER | /HC | center horizontally on monitor/desktop/tab |
/TOP | /T | position at top of monitor/desktop/tab |
/BOTTOM | /B | position at bottom of monitor/desktop/tab |
/VCENTER | /VC | center vertically on monitor/desktop/tab |
/CENTER | /CTR | center on monitor/desktop/tab |
/POS=y,x | position OSD window | |
/ALPHA=n | /A=n | transparency; n is 48 (ghostly) to 255 (opaque) |
/FADE | /F | fade the window out |
/FADEIN | /FI | fade the window in |
/OFFSET | /POS=y,x coordinates are relative to /TOP, /BOTTOM, /LEFT, etc. | |
/MONITOR=n | /M=n | monitor number |
/TAB | /TOP, /BOTTOM, etc. are relative to TCmd tab window |
Character Escapes:
These may be used in OSD’s
text string when you specify /X.
| Escape: | Expands to: | Example: |
|---|---|---|
\b | backspace | |
\k | grave accent | |
\n | newline | |
\p | percent sign | |
\q | double quote | |
\uxxxx | Unicode character, up to U+FFFF | \u03a3 → Σ |
\Uxxxxxxxx | Unicode character, up to U+10FFFF | \U1f63a → 😺 |
\nnn | octal value, up to 777 | \101 → A |
\xnnnn | hexadecimal value, up to FFFF | \x41 → A |
\#nnnnn | decimal value, up to 65535 | \#65 → A |
\\ | backslash |
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:
| Version | Date | Changes |
|---|---|---|
| 1.0.11.6 | 2024-04-11 | Minor tweak to FindMyWindow.cpp:
now Windows Terminal detection does not rely on the WT_SESSION environment variable. |
| 1.0.11.5 | 2023-12-05 | Updated FindMyWindow.cpp. These may slightly improve compatibility with Take Command and Console2. |
| 1.0.11.4 | 2023-11-16 | The “Plugin not loaded” error message is not displayed in pipe and transient shells. When it is displayed, it now includes the plugin’s name. |
| 1.0.11.3 | 2023-10-14 | Tweaked ShowCmdHelp() to include
VER_PATCH. |
| 1.0.11.2 | 2023-10-12 | Updated the plugin’s web address. |
| 1.0.11 | 2023-07-06 | Added /FADEIN. |
| 1.0.10 | 2022-12-27 | Added an (otherwise undocumented)
/J option to PCTBAR. |
| 1.0.9 | 2022-11-21 | Adds /TAB option. Finally documented
/OFFSET. |
| 1.0.8 | 2022-09-09 | Bug fix:
/FADENOW was not closing windows opened with
/FADE. Made the default drop shadow darker. |
| 1.0.7.2 | 2021-11-23 | Updated mmfiles.cpp to version 1.4.4.0. Tweaks to error messages, and other minor code cleanup. |
| 1.0.7.1 | 2021-11-01 | Help text is now displayed via ShowCmdHelp().
\p now expands to a percent sign. |
| 1.0.7 | 2021-10-11 | Minor improvements
to escape expansion: added \k for grave accent, \q for double quote,
\# for decimal character values. Also tweaked the handling of malformed escape sequences. |
| 1.0.6 | 2021-07-28 | Changes to drop shadows. Tweaked the version info resource to include the platform (x64 or x86). |
| 1.0.5 | 2021-06-19 | Added
/RJ, /LJ, and /X to OSD. |
| 1.0.4 | 2021-06-18 | Increased the drop shadow distance for larger font sizes. |
| 1.0.3 | 2021-05-15 | Made the fade slower and smoother. Reduced the minimum alpha value to 48. Moved the multiline/TextAngle test into MakeOsdWindow(). |
| 1.0.2 | 2020-12-24 | Restored the WS_EX_NOACTIVATE style bit to prevent OSD from deactivating the TCC window, as it occasionally does. |
| 1.0.1 | 2020-12-21 | Tweaked the window style bits to make OSD windows “click-throughable”. Switched the filenames; now they are OSD.dll (for 64-bit Take Command) and OSD-x86.dll (for 32-bit). |
| 1.0.0 | 2020-02-19 | First
release. Removed /EBCDIC. Documented a few previously undocumented features, and
included some demo batch files which hint at others. |
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/osd.zip.