Ruler plugin for Take Command
Version 1.0.2.4 2023-10-15
Charles Dye
Purpose:
This plugin displays an on-screen ruler in Take Command. This will be helpful if you need to count characters on a line or in a string.
Installation:
To use this plugin, copy Ruler.dll to some
known location on your hard drive. (If you are using the 32-bit version of
Take Command, take Ruler-x86.dll instead of
Ruler.dll.) Load the .DLL file with a
PLUGIN /L command, for example:
plugin /l c:\bin\tcmd\test\ruler.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:
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:
RULER — View and set ruler options.
Syntax:
RULER /A:alpha /B:color /C:color /D /E:n /H:color /I:altcols /J:altrows /K:key /L /M:n /P:n /Q /R /S /U:n /W:n /X:n /Z:n
/A:alpha | set the ruler’s alpha transparency (alpha mode) | 128 |
/B:color | set the ruler’s background color (alpha mode) | #B0E0E6 |
/C:color | set the ruler color (color-key mode) | varies |
/D | restore the built-in plugin defaults | |
/E:n | enable or disable (show or hide) the ruler | 1 |
/H:color | set the color of the ruler’s hash marks (alpha mode) | #000000 |
/I:altcols | set alternate-color column marks | none |
/J:altrows | set alternate-color row marks | none |
/K:key | set the hotkey | Shift-F12 |
/L | list all supported hotkeys | |
/M:n | set the hotkey mode | 1 |
/P:n | set the ruler’s position | 0 |
/Q | quietly | |
/R | restore saved settings from the registry | |
/S | save the current settings to the registry | |
/U:n | intercept the LIST command | 1 |
/W:n | set the width of the hash marks | 1 |
/X:n | set the ruler’s transparency mode | 0 |
/Z:n | set whether the ruler is hidden at startup | 0 |
RULER with no options displays the plugin’s current
settings.
/K:key
allows you to change the plugin’s hotkey. To see
a list of all supported hotkeys, use /L. (The list can vary between
versions of Take Command, because the plugin hotkey interface changed in version 24.)
Note that some key combinations may not work for you — they might be
intercepted by the console, by a keystroke alias, or by Take Command itself. If your
hotkey doesn’t work, try changing it back to its default value,
Shift-F12.
You can disable the hotkey with /K:NONE.
/M:n lets you
control what the hotkey does. The default value is 1.
| Value: | Hotkey action: |
| 0 | Enabled ↔ Disabled |
| 1 | Top → Bottom → Disabled → repeat |
| 2 | Top → Bottom → Left → Disabled → repeat |
| 3 | Top → Bottom → Left → Right → Disabled → repeat |
| 4 | Top ↔ Bottom |
| 5 | Top → Bottom → Left → repeat |
| 6 | Top → Bottom → Left → Right → repeat |
| 7 | Top → Left → Disabled → repeat |
| 8 | Top ↔ Left |
| 9 | Enable |
| 10 | Disable |
| 11 | Enable, Top |
| 12 | Enable, Bottom |
| 13 | Enable, Left |
| 14 | Enable, Right |
| 15 | Left → Right → Disabled → repeat |
| 16 | Left → Right → repeat |
ruler /k:alt-r /m:8
Multiple hotkeys: You can define up to five different hotkeys. The syntax is:
RULER /Kd:key /Md:n
… where d is a digit from 1 to 5. (If omitted, it defaults to 1.)
ruler /k1:alt-t /m1:11 /k2:alt-b /m2:12 /k3:alt-d /m3:10
Alt-T shows the ruler at the top of the tab window, Alt-B puts it at the bottom, and Alt-D disables it.
The ruler is drawn as a transparent, OSD-style window
over the Take Command window. /X:n selects
the type of transparency used.
/X:0 selects color-key transparency. In this mode, the ruler background
is invisible, and only the hash marks are visible. Use
/C:color to
set the ruler color. This is the default.
/X:1 selects alpha transparency. In this mode, both the ruler’s
background and hash marks are visible, and both are equally transparent. Use
/A:n to
adjust the ruler’s transparency, and
/B:color and
/H:color to
set its colors.
Color-Key Mode Customization:
/C:color
sets the ruler color (in color-key mode). You may specify the
color in several different ways:
| Method: | Example: | Gives: |
|---|---|---|
| • as a W3C color name: | /C:Orange | Orange |
| • as a hexadecimal RGB value: | /C:#ADFF2F | GreenYellow |
| • three-digit hex RGB is okay too: | /C:#0FF | Aqua |
| • comma-separated red, green, and blue values: | /C:255,215,0 | Gold |
| • hexadecimal is okay too: | /C:0xBA,0x55,0xD3 | MediumOrchid |
| • as a console color index: | /C:$14 | bright yellow |
In color-key mode, this plugin stores a different ruler color for each of the 16
possible console background colors. For example, the ruler defaults to ‘DeepSkyBlue’
when the console background is black, but ‘CadetBlue’ when it’s
bright white. When you change the ruler’s color with /C:, you
are setting the ruler color for the current console background color. If you change
the console’s colors, e.g. with CLS /C, you will get a
different ruler color — which you can again customize with /C:.
/W:n sets the
width of the hash marks. Legal values are 0 to 3; the default is 1.
Alpha Mode Customization:
/B:color
sets the background color of the ruler (in alpha mode). You may specify the
color in several different ways:
| Method: | Example: | Gives: |
|---|---|---|
| • as a W3C color name: | /B:Orange | Orange |
| • as a hexadecimal RGB value: | /B:#ADFF2F | GreenYellow |
| • three-digit hex RGB is okay too: | /B:#0FF | Aqua |
| • comma-separated red, green, and blue values: | /B:255,215,0 | Gold |
| • hexadecimal is okay too: | /B:0xBA,0x55,0xD3 | MediumOrchid |
| • as a console color index: | /B:$14 | bright yellow |
Because the ruler is transparent, the color you actually see will be a combination of the ruler’s background color and whatever is underneath it. For example, an orange ruler will appear to be a very dark orange if it’s over a black background, but it will look much brighter over a white background.
/H:color
specifies the color of the hash marks on the ruler (in alpha mode). /H:
supports all the same color formats
as /B:.
If you give a /B: but no /H:, RULER
will make the hash marks either black or white, whichever gives the better
contrast.
/A:alpha
lets you set the ruler’s transparency (in alpha mode). Values range from 64
(very faint) to 255 (completely opaque). The default is 128.
/W:n sets the width of the
hash marks. Legal values are 0 to 3; the default is 1.
/P:n
sets the ruler’s current position. The default is /P:0.
(You can also move the ruler with the hotkey.)
| Value | Position |
| 0 | The ruler is at the top of the tab window. |
| 1 | The ruler is at the bottom of the tab window. |
| 2 | The ruler is at the left of the tab window. |
| 3 | The ruler is at the right of the tab window. |
/E:n
lets you toggle the ruler on or off. (You can also enable or disable the ruler
with the hotkey.)
/Z:n
determines whether the ruler is hidden the next time this plugin is loaded.
/Z:0 shows the ruler at startup; /Z:1 hides it.
The default is /Z:0. This option does not show or hide the
current ruler; it only affects future instances of this plugin.
/U:n
controls whether or not this plugin intercepts the
LIST command. /U:1 allows the
plugin to intercept LIST; /U:0 disables this feature.
The default is /U:1. This option does not affect the current
instance; it only takes effect the next time you load this plugin.
/I:n[,n…]=color :
You may want to emphasize particular columns. /I: lets you
draw hash marks in a different color at a few specific columns. Pass it up
to sixteen column numbers separated by commas, followed by an equals sign
and a color name:
ruler /i:80,100=yellow
… to make the marks at columns 80 and 100 yellow.
Alternate syntax: /I:*n=color
will draw every nth hash mark in the
alternate color. For example:
ruler /i:*20=yellow
… will mark every 20th column in yellow.
This option
does not do much sanity checking on the color. It’s up to you to make
sure that your alternate color is easily distinguished from the regular hash
marks color, console background, and ruler background (if any). Note that
there is only one alternate column color; it does not change according to the
console background color, as the /C:
color does. Also note that /I: colors specific columns;
it does not affect vertical rulers.
/I by itself removes all alternate-color column marks.
/J:n[,n…]=color
lets you draw different-colored hash marks at a few specific rows. The
syntax is the same as for /I:
above, but the values are row numbers instead of columns. Note that this
option only affects vertical rulers. /J by itself removes
all alternate-color row marks.
ruler /j:25=yellow
/D restores the original plugin
default settings (shown in the third column of the
table above). /R restores the settings saved to the registry,
if any. You cannot combine the two.
/S saves the current settings to
the registry. They will be loaded automatically the next time you load this
plugin.
LIST: This plugin intercepts the
LIST command to adjust the position of the ruler. The ruler will
be restored to its normal position the next time the prompt is displayed.
LIST’s operation is unchanged otherwise.
You can use RULER /U: to disable or
enable this feature the next time the plugin is loaded.
New Hotkey:
Shift-F12 — Hides, unhides, or moves the ruler.
You can change the default key assignment with
RULER /K:key. You can use
RULER /M:n to change the way the
hotkey works.
You can define as many as five hotkeys by using the extended syntax.
Color Formats:
Several of RULER’s options expect
a color argument. Several different methods of
specifying a color are supported:
• As a W3C color name: As in CSS. This is the most intuitive syntax. Case is not significant, and color names containing ‘gray’ may be spelled using ‘grey’ instead if you prefer.
• As hexadecimal RGB, with a leading # sign. Again, as in in CSS.
Use either six digits (#rrggbb) or three digits
(#rgb).
• As red, green, and blue values, 0 to 255, separated by commas. This just happens
to be the format returned by the @COLOR function. You can give values in hexadecimal
with a leading 0x — although the #rrggbb
syntax is probably more convenient if you prefer hex.
• Finally, you can specify colors as console color numbers, as in many internal
commands. Use a leading $ to indicate a console color. The value must, of course,
be 0 to 15. Under Windows Vista or later, the current RGB value for the given color will be read
from the console. Under Windows XP
the necessary API
doesn’t exist, so the $n syntax will instead
return a default value from an internal list.
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.2.4 | 2023-10-15 | Tweaked ShowCmdHelp() to report
VER_PATCH. |
| 1.0.2.3 | 2023-10-12 | Updated the plugin’s web address. |
| 1.0.2.2 | 2023-07-24 | Updated ParseArgs.cpp to the current version. |
| 1.0.2.1 | 2023-06-13 | Removes a call to QueryIsFile(), which appears to have issues in TCC v30.00.20. |
| 1.0.2 | 2021-12-22 | No longer links to TakeCommandIPC() dynamically. That hasn’t been necessary for a long, long time. |
| 1.0.1 | 2021-12-21 | Fixed a problem calling TakeCommandIPC() in 32-bit TCC. |
| 1.0.0 | 2021-10-02 | First release. |
Status and Licensing:
This plugin is © Copyright 2023, 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/ruler.zip.