Functions Executed by Commands
When a command is executed, the function assigned to the command is called. The expressions passed to this function aren't necessarily just the highlighted expression. There are several different ways this can happen depending on the properties of the Command object and on the content that is highlighted.
A command is defined by creating an object definition in the Commands namespace that has type of Command. See Creating and Editing Commands for more details. In order to be useful, a command has to include at least the Function: property. Without this, the command won't know which function it's supposed to call. A command can also have a short cut key assigned to it using the ShortcutKey property. Not all commands have shortcut keys. Some only appear in the lists of commands that are shown by other commands. For example, by the All command.
In addition, commands can also have a CommandParameters property that controls the expressions that are passed to the function assigned to the command.
Commands that act on the highlighted term
Examples include the Simplify command. These commands don't normally have a CommandParameters property in their definition. If the function needs to be defined on more than one parameter, it can have the CommandParameters property with HighlightExpression as the first parameter.
These commands can have any type definition of the form:
U → V
where "U" and "V" are any type. These functions are always one parameter functions (not U → V → W, for example, which would be a two parameter function).
Typically, the expression returned by the function replaces the highlighted expression in the document window. If the function returns an object of the Null type, then the highlighted expression is left as is. If the returned expression is an Exception object an error message will be displayed. If the returned expression is just the Null object (as opposed to another object that has the Null type), then the application does nothing to the highlighted expression. See Null Typed Objects for more details.
Note that if there is more than one expression highlighted in the document window and the user invokes a command that is typed as described above then the application simply applies the command to each highlighted expression in turn. The result is equivalent to having the user highlight each expression separately and invoke the command once for each highlight.
Commands that act on an entire expression
Examples include the Right command, Left command, and the Move command where the highlighted term is moved to a different location in the expression. Note that in these commands, the term that is changed is one of the parent terms of the highlighted term.
To make this possible, the entire expression is passed to the function not just the highlighted term. This is controlled by having a CommandParameter property with Expression as it's first parameter in the definition of the command.
The expression passed to the function will include a Highlight object that indicates the current location of the highlight.
When a command is invoked that has a CommandParameter property with Expression as the command parameter type and there are multiple expressions highlighted, the function is called once for each highlighted expression in the module.
Managing the highlight location in expressions returned from a command
For a clause that just acts on the highlighted expression, the highlight will stay on the expression that is returned unless a highlight is specifically set in the result expression contains the Highlight object (in the Settings namespace).
If the command only acts on the highlighted expression, there is always a highlight on the top level of the expression, so the Highlight object is omitted in this case.
In both the case where a function acts on highlighted expression or the whole expression, you can control where the highlight is in the result expression by adding the Highlight object. For example,
forces the highlight to the first "a". It doesn't matter where the highlight originally was in the expression.