This is a template for Notepad++ plugins written in C#. The vast majority of the code (certainly all the parts that were really hard to implement) come from kbilsted's now-archived NotepadPlusPlusPluginPack.Net
, with some significant changes, including:
- A simpler architecture in which the PluginInfrastructure folder is side-by-side with the rest of the plugin's code, rather than in a separate directory tree.
- An example of a non-docking (pop-up) dialog opened from the plugin menu, a docking form, and a non-docking non-pop-up form.
- A settings form that makes it easy for the maintainer to add, remove or edit settings.
- A template for automated tests that can be run inside Notepad++, including a template for user interface tests that automatically test forms.
If you have any issues, see if updating to the latest release helps, and then feel free to raise an issue on GitHub. Please be sure to include diagnostic information about your system, Notepad++ version, and plugin version (go to ?->Debug Info...
from the Notepad++ main menu).
Read information about the plugin architecture (some of this may be out of date)
- Download the source code in one of the following ways:
- clone the repository
- download the source code for the repo, then create a git repo inside
- fork this repo
- download the source code for a release (see the Releases page)
- Open NppCSharpPluginPack/NppCSharpPluginPack.sln in Visual Studio 2022
- Configure the security settings of
%ProgramFiles%/Notepad++/plugins
so that Visual Studio can write to%ProgramFiles%/Notepad++/plugins/CSharpPluginPack
. I do this in the following way:- Open
%ProgramFiles%/Notepad++
in the File Explorer. - Right-click on the
plugins
folder. - Choose
Properties
from the drop-down menu - Select the
Security
tab. - Click the
Edit...
checkbox - Select
Users
from theGroup or user names
menu, then click the checkbox in theFull Control
row of theAllow
column. - Click the
Apply
button.
- Open
- Try building the project using Visual Studio using
x64
build target (this build for 64-bit Notepad++). You will know that the project is working correctly when Notepad++ starts up, andCSharpPluginPack
appears on the list of plugins. - Try changing the assembly version in NppCSharpPluginPack/Properties/AssemblyInfo.cs to
1.0.3.0
. - Try building the project again, then select
Plugins->CSharpPluginPack->About
from the Notepad++ dropdown menu. The title of the about form should readNppCSharpPluginPack v1.0.3
. If it does not, your project is not building correctly. - Copy the
testfiles
directory of the repo to the%ProgramFiles%/Notepad++/plugins/CSharpPluginPack
directory. - Run the tests. The third line of the test results file should read
No tests failed
. If you seeTests failed: Performance of something
on the third line, that's because you forgot step 7. - To test your project for 32-bit Notepad++, repeat steps 3-8 for
%ProgramFiles (x86)%/Notepad++/plugins
and change your build target tox86
.
This plugin is verified to work on versions of Notepad++ as old as v7.3.3, but it may have some bugs (see the CHANGELOG to see the what bugs may still exist).
It has also been tested and verified to work normally on the newest versions of Notepad++, v8.6.1 and v8.6.2 RC.
Every version of the template works on Windows 10 May 2019 update or later, or you must install .NET Framework 4.8.
If you are interested in helping users of your plugin who don't speak English, this plugin pack makes it easy to translate your plugin to other languages beginning in v0.0.3.7.
Translator.cs
infers your preferred language and attempts to translate in the following way:
- It checks your Notepad++
nativeLang.xml
config file (at XPath path/NotepadPlus/Native-Langue/@name
) to determine what language you prefer to use, and setslowerEnglishName
to the appropriate value and skips to step 3. For example, if this file saysgalician
, we will attempt to translate your plugin togalician
. If the Notepad++ native language isenglish
or if your plugin does not have a translation file for the Notepad++ native language,Translator.cs
then does the following:Translator.cs
looks up yourcurrent culture
(which can be checked using theget-culture
command in Powershell).- Next, we find the
EnglishName
property of thecurrent culture
(which can be found by the$foo = get-culture; $foo.EnglishName
command in Powershell), take the first word, and convert it to lowercase. Call thislowerEnglishName
.- Example: the
EnglishName
of theen-us
culture isEnglish (United States)
, solowerEnglishName
isenglish
- Example: the
EnglishName
of theit-it
culture isItalian (Italy)
, solowerEnglishName
isitalian
- Example: the
Translator.cs
then does one of the following:- If
lowerEnglishName
isenglish
, it does nothing (because the plugin is naturally in English) - Otherwise, it looks in the
translation
subdirectory of theCSharpPluginPack
plugin folder (whereCSharpPluginPack.dll
lives) for a file named{lowerEnglishName}.json5
- NOTE: because the translation files are in a subdirectory of the plugin folder, translation does not work for versions of Notepad++ older than version 8, since those older versions do not have separate folders for each plugin.
- If
- If
Translator.cs
foundtranslation\{lowerEnglishName}.json5
, it attempts to parse the file. If parsing fails, a message box will appear warning the user of this.- If no translation file was found, or if parsing failed, the default English will be used.
- If parsing was successful,
Translator.cs
will use the translation file as described below.
For versions of NppCSharpPluginPack older than v0.0.3.11, translation is only done once, when Notepad++ starts up. If the user changes their Notepad++ UI language, this change is only reflected in the plugin after the user closes and re-opens Notepad++. For versions of NppCSharpPluginPack v0.0.3.11 or newer, it is possible to also change the plugin's UI language whenever the user changes their language preference in the Notepad++ preferences form, although this capability is turned off by default to improve performance.
To be clear, the plugin may not be in the same language of the Notepad++ UI. The steps described above represent my best effort to automatically translate the plugin into a language that the user will find useful, without requiring the user to select their language from a list of available languages in the settings form.
To translate your plugin to another language, just look at english.json5
in the translations directory of this repo and follow the instructions in that file.
Currently NppCSharpPluginPack has been translated into the following languages:
Language | First version with translation | Translator(s) | Translator is native speaker? |
---|---|---|---|
Spanish | v3.7 | molsonkiko | NO |
The following aspects of NppCSharpPluginPack can be translated:
- Forms (including all controls and items in drop-down menus) (see the
TranslateForm
method inTranslator.cs
) - Items in the NppCSharpPluginPack sub-menu of the Notepad++ Plugins menu (see the
GetTranslatedMenuItem
method inTranslator.cs
) - The descriptions of settings in the
CSharpPluginPack.ini
config file and settings form (see theTranslateSettingsDescription
method inTranslator.cs
) - Message boxes (includes warnings, errors, requests for confirmation) (see the
ShowTranslatedMessageBox
method inTranslator.cs
)
The following aspects of NppCSharpPluginPack may eventually be translated:
- This documentation
- The messages of user-defined exceptions (for example, if your plugin
FooHasNoBarException
, there is currently no way to translate the message that the user sees when this error is thrown and caught) - Generic modal dialogs (for example, file-opening dialogs, directory selection dialogs)
- Kasper B. Graversen for creating the plugin pack that this is based on.
- jokedst for making the CsvQuery plugin to which I owe the original ideas behind my settings form and my adaptive styling of forms.
- And of course, Don Ho for creating Notepad++!