NppScripts is a framework for developing and hosting automation scripts (Notepad++ light-weight plugins).
NppScripts itself is a typical Notepad++ plugin implemented with NppPlugin.NET (courtesy of
donho). At this stage the plugin is available for download from CodePlex but eventually it will be available from
Notepad++ Plugin Manager.
The automation scripts are written in C# and hosted at runtime with
CS-Script script engine. The script can be created and edited with Notepad++ just out of box though it is recommended that you use the C# intellisense and code execution plugin
"CS-Script for Notepad++". You can enable it from Notepad++ Plugin Manager:
A typical automation script is a C# class derived from
NppScripts.NppScript class of NppScripts.dll. The automation business logic is implemented by overriding
public class Script : NppScript
public override void Run()
//business logic implementation
From the Run implementation you have access to all helper API provided by
NppPlugin.NET core and the NppScripts itself.
Win32.SendMessage(Npp.NppHandle, NppMsg.NPPM_GETFULLCURRENTPATH, 0, out path);
In the code above
NppMsg are implemented in the namespace
Of course this API only provides access to the basic Notepad++ functionality and you may want to encapsulate any useful reusable automation routines into the common script file, which can be shared with (included) other automation scripts
(see Automation sample).
The scripts can be executed by either:
Despite the script nature of the the automation model implemented by NppScripts
it demonstrates a remarkable performance. Tanks the embedded CS-Script engine the scripts are not interpreted but compiled when it is loaded at runtime. Thus any script exhibits the same performance as the fully compiled assembly shows.
NppScripts is optimized to allow script execution with the minimal affect on
Notepad++ performance. Thus the scripts are note loaded/compiled until the first script execution.
The scripts are stored in the dedicated directory in the User Profile and the script file name supposed to comply with the following naming convention:
Npp.<xxx script index>.<script name>[.disabled].cs
|'Dockable Dialog Demo' script
||Npp.120.Dockable Dialog Demo.cs
|Disabled 'Custom Print' script
However if you use Script Manager to create the script you will need to specify the script name only and the valid file name will be generated by the plugin:
The scripts shortcut bindings are established at the Notepad++ startup. The nature of the Notepad++ keyboard events monitoring makes it very difficult (if possible) to change the binding on-fly. Thus if you change
the shortcut binding definition it will not be enabled until Notepad++ is restarted.
A typical script development use-case is as follows:
- Create a new script by pressing the 'Create New Script' button.
- Define the script toolbar button and/or define the shortcut key combination. Note this step is optional.
- Implement your script business logic in the overridden
You will have the following classes to you disposal to assist you with controlling the
NppScripts.Npp - This class contains very generic wrappers (e.g. editor handlers, a few generic text manipulation routines) for basic Notepad++ functionality.
NppScripts.NppMsg - This enum defines all
NppScripts.SciMsg - This enum defines all Scintilla text control messages.
NppScripts.Win32 - This class encapsulates the major Interop functionality (e.g. sending messages).
- Select the script in the Script Manager panel and press "Check script for errors" button.
- When the script contains no errors select it in the Script Manager panel and press "Run selected script" button.
It is highly recommended that you use CS-Script for Notepad++ Notepad++ plugin. With this plugin you will not only be able to utilize the true Intellisense allows but
also "Go to Definition", "Find All References", "Format Document" and many other feature commonly found in the IDEs like Visual Studio. Thus a simple pressing F12 when the caret is on the
generate the whole public API of the class including the XML documentation.
You can also quickly access the Scintilla and Notepad++ public reference documentation by pressing 'NppScript Documentation' button:
It is also recommended if you review all the sample scripts the plugin comes with. These scripts demonstrate not only the approaches for controlling
Notepad++ but also general scripting techniques (e.g. referencing third-party assemblies, including (referencing) additional scripts from the primary one).
Th plugin comes with the comprehensive set of samples. All samples are available from the
Script Manager panel. The panel can be activated either from Notepad++
menu (Plugins->Automation Scripts->Script Manager) or from the
Each sample is dedicated to the specific automation scenario. Many of the scripts with the name starting with "Sample - " prefix (top group in the script list) are the original
NppPlugin.NET samples ported to the C# script form. The rest is the samples developed specifically for
The following is the brief overview of the most interesting samples:
- Sample - HelloFX
The script demonstrates interacting with Notepad++ menu. Sending messages to
Notepad++ and Scintilla (current document). Changing the zoom from a separate thread.
- Sample - WhatIsNpp
Simulation of 'typing' - appending the text character by character with the controllable delay.
- Sample - Close HTMLXML tag automatically
This script demonstrates how to create the 'background' script. The script that monitors all user input and injects automatically matching end-tag for the when an opening tag has been typed in the HTML documents.
- Sample - Debug
Shows how to enable script debugging. Start the script and when prompted select the CLR-Debugger to attach.
- Sample - Automation
This a very important sample, which demonstrates how to call the method from another script (automation.cs). It also demonstrates how to encapsulate the major string manipulation routines in the separate reusable script that can be utilized by
other automation scripts.
The reusable automation.cs is only a starting point for something that you can eventually make a full scale automation API library.
- Sample - HTML Preview
This script renders the current HTML document preview in the Notepad++ dockable panel.
Important point is that the panel is implemented in the separate assembly (source code is available). In fact this assembly is a standalone executable that can be run on it's own. It hosts IE WebBrowser control. The script also demonstrates how to ensure a
specific version of IE to be hosted.
- Sample - Custom Autocomplete
This is the example of how to implement context sensitive auto-completion. The sample implements a typical DSL auto-completion scenario when editor suggests male and female names based on the aleady typed characters.
Running the sample:
- create and open .dsl file
- start typing (e.g. character 'A') and press "Alt+."
- observe auto-completion suggestions (e.g. "Aaron, Adam, ...");
- use arrow keys and to select the suggestion
- press 'Enter' to accept the selected suggestion
- Edit - Format XML Document
This is a very useful script that allows instant formatting of any valid XML document.
- Open Document Folder
Another usability script. It allows opening the Windows Explorer with the current document file selected. It demonstrates how to place a button (with a specific icon) on the
- Command Prompt
This script demonstrates how to create a dockable panel that can interact with the user. The panel has very simple user interface allowing execution of the DOS commands and printing the commands output:
- Integration - Custom Output Panel
This script demonstrates how to create and use Notepad++ output panels (CS-Script needs to be enabled from Plugin Manager).
This technique can be useful when you want to output some information from your automation script.