Navigational TextCommands are those which pertain to the movement of the current text insertion point. The insertion point is the point at which text will be emitted during the execution of a template or other TextDocument manipulation.
Some example Navigational TextCommands are «GotoFileTop» and «GotoFileBottom» which, as you might guess, move the insertion point to the top and bottom of the current file respectively.
But what if you want to jump to one of these locations, emit some text and the jump back to where you started?
Well this has also been thought of.
The «StoreInsertionPoint» and «GotoInsertionPoint» TextCommands are for exactly this purpose. The «StoreInsertionPoint» will store the current location of the insertion point, using a lookup key passed to the command as its first parameter. The «GotoInsertionPoint» will retrieve a previously stored location likewise using a lookup key passed to it as a first parameter.
Consider the following template:
-------------------------------------------------------------
«StoreInsertionPoint(Origin)»«GotoFileTop»using System.Data;
«GotoInsertionPoint(Origin)»DataSet MyDataSet;
-------------------------------------------------------------
It performs the following steps:
- Store the current location of the insertion point in a variable called Origin
- Move the insertion point to the top of the current file.
- Emit using System.Data; followed by a newline
- Move the insertion point back to the location previously stored.
- Emit DataSet MyDataSet; followed by another newline
As you can see, this places the using statement at the top of the file, whilst emitting the new DataSet variable at the point the user invoked the template.
Navigational TextCommands are certainly a powerful concept. We’ll be providing more of these commands in the future and also showing you how you can create your own.