From f15f0dabbb28a233d729bff5bf044c0233cca9f7 Mon Sep 17 00:00:00 2001 From: "R. Timothy Edwards" Date: Mon, 13 Apr 2026 13:01:54 -0400 Subject: [PATCH] Added HTML documentation for the "macro" command, after finding that the exiting documentation does not include the handful of options available to the macro command, nor does it explain the relationship between tools and macro sets. --- doc/html/macro.html | 60 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 51 insertions(+), 9 deletions(-) diff --git a/doc/html/macro.html b/doc/html/macro.html index dc568910..073075ff 100644 --- a/doc/html/macro.html +++ b/doc/html/macro.html @@ -20,22 +20,64 @@

macro

-Define or print a macro called char +Define or print a key or button macro binding.

Usage:

- macro [window_type] [key [value]]

+ macro [window_type] [option] [key [value]] +

where key is the name of a valid key (see below), and value is a magic command-line command. If - present, window_type must be one of the four window - types accepted by the specialopen command: layout, - color, netlist, and wind3d. If omitted, - the layout window is assumed by default, unless the command has - been called from inside a window (using the colon or semicolon + present, window_type must be one of the known valid window + types accepted by the specialopen command (color, + netlist, and wind3d), or a known layout tool + (box, wiring, nettool, or pick). If + omitted, the layout window is assumed by default, unless the command + has been called from inside a window (using the colon or semicolon escape to the command-line), in which case that window type is - assumed. + assumed.

+ + In the non-Tcl version of magic, the window_type must be + one of the three valid window types listed above, or layout. + Tool button bindings are hard-coded, fixed, and unknown to the + macro handler.

+ + In the Tcl version of magic, tool types are generated by + procedure and can be modified or overridden. The four tools + listed above are the default tools known to magic. If no window + or tool type is given, then the current tool in the current + active layout window is assumed.

+ + option may be one of the following: +

+
list [-reverse] +
The key bindings are returned in the form of a Tcl list + (Tcl version of magic only). The returned value is a + single list with alternating entries of the macro key and + the macro binding. In Tcl, this list can be treated as a + dictionary type of key:value pairs. With the -reverse + option, the keys and values are reversed, resulting in a + dictionary that can be searched or listed by function. +
help +
Curently, macro help is equivalent to macro + without arguments, and returns a full list of macro names + and their bindings. +
search text +
Return only results which match (all or in part) the string + text. For example, macro search grid will + return all key bindings that include the command grid. +
copy tool_name +
This is a method introduced to allow the interactive creation + of new tools, in the Tcl version of magic. Each tool is defined + specifically by its unique button and key bindings. Because + tools generally keep most of the same default bindings, the + copy option will copy all the existing bindings to the + new tool from the current tool. This can be followed by + switching to the new tool and replacing macros with ones + unique to the tool. +
@@ -72,7 +114,6 @@ Define or print a macro called char etc., the macro command accepts the abbreviated forms Button1, and so forth.

- Finally, key modifiers may be prepended to the key name. Valid key modifiers are Shift_, Control_, Alt_, and Meta_, and may be coupled in any @@ -89,6 +130,7 @@ Define or print a macro called char

See Also:

imacro
+ tool (Tcl version)