Background

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:

Overview

A typical automation script is a C# class derived from NppScripts.NppScript class of NppScripts.dll. The automation business logic is implemented by overriding  NppScript.Run:

using System;
using NppScripts;
 
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.

string path;         
Win32.SendMessage(Npp.NppHandle, NppMsg.NPPM_GETFULLCURRENTPATH, 0, out path); 

In the code above Win32, Npp and NppMsg are implemented in the namespace NppScripts.

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:

  • Selecting the corresponding script in the Script Manager panel and pressing 'Run' button:


  • Selecting the corresponding menu item from the menu:


  • Pressing the toolbar button defined in the automation script with the NppScripts directive '//npp_toolbar_image <resource file>|<icon index>':
    //npp_toolbar_image Shell32.dll|3 
    using System;
    using NppScripts;
    ...

  • Pressing the shortcut combination defined in the automation script with the NppScripts directive '//npp_shortcut [Ctrl+][Alt+][Shift+]<Key>':
    Note: 'Key' is the name of the System.Windows.Forms.Keys enum value
    //npp_shortcut Alt+OemPeriod 
    using System;
    using NppScripts;
    ...

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:

   Naming pattern:   Npp.<xxx script index>.<script name>[.disabled].cs

'Dockable Dialog Demo' script Npp.120.Dockable Dialog Demo.cs
Disabled 'Custom Print' script Npp.140.Custom Print.disabled.cs
Menu separator Npp.130.---.cs 

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:  

Limitations

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.   

Using

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 NppScript.Run.
    You will have the following classes to you disposal to assist you with controlling the Notepad++ behavior:
    • 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 Notepad++ messages.
    • 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 NppScripts.Npp will 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).

Samples

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 Notepad++ toolbar:

 

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 NppScripts.

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 Notepad++ toolbar. 
  • 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.

 

Last edited Jun 5, 2014 at 7:46 AM by oleg_s, version 34