Macros

From Notepad++ Wiki
Jump to: navigation, search
Sequences of actions, aka macros


Basically, a macro is a sequence of actions you can record, save and play back. Because "action" needs to be made more precise, there are some technical points to know for optimal use of this simple, yet powerful tool.

Recording a macro

This is done by using the Macro -> Start recording menu entry, or hitting the corrsponding toolbar button. Both are inactive while recording is on. The default keyboard shortcut for this action is Ctrl+Shift+R.

But what is being recorded? To answer this, the first question is: by whom? Answer: the active Scintilla component. When recording is on, the Scintilla component that receives keystrokes and other commands informs the Notepad++ application of which actions it performed. Notepad++ saves these in a form suitable for persistent store and for playback, in shortcuts.xml.

Because Scintilla actions are being stored, there is no memory of whether user clicked a button, a menu entry or a key. And the macro will play back on a different machine, with a different localisation of Notepad++ and different keyboard shortcuts. This design is excellent for portability, that is, the ability for someone's macro to be reused by as many unknown users as possible. However, it makes the recording of plugin actions tricky, because these actions may lead to different sequences of Scintilla commands. Notepad++ handles find and replace actions recording itself, as they would present the same difficulty.

Stopping the recording

Click on the Stop recording entry menu or toolbar button, or enter the keyboard shortcut for Start recording. Actually, the shortcut is for toggling recording, this is how you'll find it named on the Shortcut mpper.

You cannot suspend recording and resume it later.

Saving the macro

Hit the Save macro button or menu entry. If you don't save a macro and then start recording another, your previous work is gone without a warning.

On saving the macro, you are asked for a name (mandatory) and a keyboard shortcut (optional). Several macros with the same name may coexist. When done, the Macro menu has a new entry with the macro name, and the keyboard binding if there was any.

You can change the name and keyboard shortcut of the macro in the Shortcut mapper. You can choose to remoe it from there too. The Macros -> Modify shortcut / Delete macro command brings this dialog up.

If you start hosting many macros, plugins or custom commands, you'll want to check whether some combonaytion of keys is available prior. There is no warning about overwriting an existing shortcut. This is not a bug, as you may wish to override some command with a customised, related macro.

Playing the macro back

This is where a macro not only is a useful can, but can also act as a roadmap.

Single playback

The macro starts playing and sending messages to Notepad++ and the active Scintilla, plainly repeating the whole recorded sequence. Always remember that you never entered parameters while recording a macro, so that you cannot customise a macro playback. A macro cannot detect special cases or make decisions. That would be called a sxript instead. See the ANSI only SimpleScript plugin for such an extension. Or NppJavaScript.

Multiple playback

On clicking the "Run a macro multiple times..." button or menu entry opens a dialog where to choose

  • which macro to execute; the macro may be the last recorded one, even if not saved yet
  • whether the number of run is fixed or not
  • the fixed number of runs, should this option be chosen.

When a macro is not run a fixed number of times, it runs till it hits the end of the current document. Less than careful design can lead to infinite loops. Careful design leads to macro that nearly emulate roadmaps.

For instance, you wish to record some sort of find/replace operation. This is not directly possible. Record your macro so that it jumps to the next bookmark at the end. That way, it will hit the bottom when no more bookmarks are found. Perform the first search, use the Mark lines option to place a bookmark on all occurrences. Then launch the macro. First run does its thing and goes to second bookmark. Second run does its thing and goes to third bookmark. Last run does its thing and goes to bottom of document. Then Notepad++ stops the whole thing, and all the job is done. Remember that an unsuccesful Find Next does not stop a macro; only going over the end of document does.