Notepad++ Plugin Template for Delphi & Lazarus

An updated version of the Delphi plugin template by Damjan Zobo Cvetko, developer of the popular DBGp plugin for the Xdebug server.

Since Delphi 2009 added Unicode support, and ANSI plugins can’t be loaded in current versions of Notepad++, compiling for Unicode is now the only option.

Compatibility with 64-bit Notepad++ has also been added (requires Delphi XE2 or newer).

Usage

Note
To use the template’s design time components in RAD Studio or Lazarus, download from the default branch and install the appropriate package.

Download one of these tagged revisions to target an appropriate API level:

Tag	Scintilla API version	Supported Notepad++ versions
default	5.5.8	8.8.9+
api-v5.5.7	5.5.7	8.8.2 – 8.8.8
api-v5.5.6	5.5.6	8.8 – 8.8.1
api-v5.5.5	5.5.5	8.7.9
api-v5.5.4	5.5.4	8.7.6 – 8.7.8
api-v5.5.2-3	5.5.2/3	8.7 – 8.7.5
api-v5.5.0	5.5.0	8.6.6 – 8.6.9
api-v5.4.3	5.4.3	8.6.5
api-v5.4.1	5.4.1	8.6.1 – 8.6.4 (all builds)
api-v5.3.7-8	5.3.7/8	8.5.8 – 8.6 (all builds)
api-v5.3.5-6	5.3.5/6	8.5.4 – 8.5.7 (all builds)
api-v5.3.3-4	5.3.3/4	8.5 – 8.5.3 (all builds)
api-v5.3.2	5.3.2	8.4.8 – 8.4.9 (all builds)
api-v5.2.3	5.2.3	8.4.3 – 8.4.7 (all builds)
api-v5.2.2	5.2.2	8.4 – 8.4.2 (all builds)
api-v4	4.4.6	* 7.9.4 – 8.3.3 (32-bit)
		* 8.3 – 8.3.3 (64-bit)
		or, with the NPP_NO_HUGE_FILES compiler definition
		* 7.9.4 – 8.2.1 (64-bit)

Or, clone the repository and check out a tag, for example:

git checkout -f api-v5.3.2

Run the install script with the name of a project directory, e.g.:

install %USERPROFILE%\projects\MyPlugin

Note
Remember to edit the DLL attach hook in DLLExports.pas with the actual name of your plugin class instance and type:

case dwReason of
DLL_PROCESS_ATTACH:
  begin
    // create the main 'Npp' object
    // Npp := THelloWorldPlugin.Create;
    MyPlugin := TMyPlugin.Create;
  end;
// ...
end;

Supported Features

See the API documentation for more details

Dark Mode Icons (Notepad++ 8.0 and later)

Plugin API messages provided by Npp.inc:

• NPPM_ADDTOOLBARICON_FORDARKMODE¹
• NPPM_ADDTOOLBARICON_DEPRECATED²

Note
NPPM_ADDTOOLBARICON_DEPRECATED is defined as an alias for the older NPPM_ADDTOOLBARICON message, so standard toolbar icons will still work in versions of Notepad++ before 8.0. Your plugin can use either message interchangeably.

Types provided by Npp.inc:

• TTbIconsDarkMode³

Methods provided by NppPlugin.pas:

• TNppPlugin.SupportsDarkMode – returns true if the running editor is at least version 8.0

Huge File Support (64-bit Notepad++ 8.3 and later)

Since version 8.3, x64 builds of Notepad++ can open files of >2GiB.
To support these Notepad++ versions, 64-bit plugins that call any Scintilla APIs must be able to handle 64-bit character positions.

The definitions provided in Scintilla.inc will support huge files without any configuration.

64-bit DLLs compiled with the default Scintilla definitions are compatible with Notepad++ >= 8.3 ONLY!

There may be cases where huge file support can be disabled, for example:

• your plugin is only offered in 32-bit versions
• your plugin does not call any Scintilla APIs like SCI_GETTEXTRANGE, SCI_GETLENGTH, etc.
• you intend to only support 8.2.1 and earlier versions of Notepad++. Read the documented instructions on how to indicate a plugin’s maximum supported Notepad++ version

The template provides two (very basic) options to configure huge file support:

1. Set the NPP_NO_HUGE_FILES compiler definition to limit character positions to the size of System.Integer, even on x64 architecture

In the IDE, select ‘Project > Options’, or press Ctrl + Shift + F11.
Go to ‘Building > Delphi Compiler > Conditional Defines’ and add ‘NPP_NO_HUGE_FILES’.

2. The TNppPlugin base class implements a SupportsBigFiles method that returns true if the running editor is version 8.3 or greater.
   Note that it does not check CPU architecture; you still need to use conditional expressions, for example:

{$IFDEF CPUx64}
{$IFNDEF NPP_NO_HUGE_FILES}
  if MyPlugin.SupportsBigFiles then
  begin
    // code for Npp 8.3+
  end;
{$ENDIF}
{$ENDIF}

Dark Mode Notification API (Notepad++ 8.4.1 and later)

API messages provided by Npp.inc:

• NPPM_ISDARKMODEENABLED⁴
• NPPM_GETDARKMODECOLORS⁵
• NPPN_DARKMODECHANGED⁶

Constants defined in Docking.inc:

• DWS_USEOWNDARKMODE⁷

Types provided by DarkMode.inc:

• TDarkModeColors⁸

Methods provided by NppPlugin.pas:

• TNppPlugin.IsDarkModeEnabled – returns true if the dark mode setting can be detected by sending the NPPM_ISDARKMODEENABLED message
• TNppPlugin.GetDarkModeColors – initializes an instance of TDarkModeColors with the editor’s active dark mode styles; use them to dynamically style form components at runtime

SCI_REPLACETARGETMINIMAL and SCI_GETSTYLEDTEXTFULL (Notepad++ 8.4.8 and later)

Added to Scintilla 5.3.2 to minimize the visual impact of text replacement when change history is enabled.
SCI_GETSTYLEDTEXTFULL was a late addition to the 64-bit APIs introduced in 5.2.3.

Types provided by SciApi.inc:

• TSciApiLevel.sciApi_GTE_532 – the running editor’s version of Scintilla is at least 5.3.2

Methods provided by NppPlugin.pas:

• TNppPlugin.HasMinimalReplacementApi – returns true if the SCI_REPLACETARGETMINIMAL and SCI_GETSTYLEDTEXTFULL APIs are available

Dark Mode Theme API (Notepad++ 8.5.4 and later)

API messages provided by Npp.inc:

• NPPM_DARKMODESUBCLASSANDTHEME⁹

Bit masks defined in DarkMode.inc:

• dmfInit¹⁰
• dmfHandleChange¹¹

Methods provided by NppPlugin.pas:

• TNppPlugin.SupportsDarkModeSubclassing – returns true if the NPPM_DARKMODESUBCLASSANDTHEME API is available; accessed through the CanSubclass property

Menu Localization API (Notepad++ 8.7 and later)

API messages provided by Npp.inc:

• NPPM_GETNATIVELANGFILENAME¹²
• NPPN_NATIVELANGCHANGED¹³

64-bit Scintilla APIs for Windows (Notepad++ 8.4.3 and later)

Scintilla began supporting 64-bit character positions on the Windows platform in version 5.2.3.
Notepad++ added these APIs in 8.4.3:

• SCI_FINDTEXTFULL
• SCI_FORMATRANGEFULL
• SCI_GETTEXTRANGEFULL

Note that, since Notepad++ 8.3, all of the former APIs return 64-bit values also; these include:

• SCI_FINDTEXT
• SCI_FORMATRANGE
• SCI_GETTEXTRANGE

Calling any of the six APIs above is functionally equivalent in Notepad++ 8.4.3 or later.
However, a future version of Scintilla will deprecate the former APIs (the ones without the *FULL suffix).
For forward compatibility, the following types are provided by Scintilla.inc:

• TSciTextRangeFull
• TSciTextToFindFull
• TSciRangeToFormatFull

Types provided by SciApi.inc:

• TSciApiLevel.sciApi_GTE_523 – the running editor’s version of Scintilla is at least 5.2.3

Methods provided by NppPlugin.pas:

• TNppPlugin.HasFullRangeApis – returns true if the SCI_FINDTEXTFULL, SCI_FORMATRANGEFULL and SCI_GETTEXTRANGEFULL APIs are available

Breaking Changes in Notepad++ 8.4.3 and later

Scintilla.inc no longer provides the TSearchResultMarking type.

Notepad++ replaced the underlying Scintilla structure with a custom type that can’t be implemented in Object Pascal.

Breaking Changes in Notepad++ 8.4 and later

Loading an external lexer from a plugin

An overview of the new Lexilla protocol is provided here.
Note that the following messages are no longer provided:

• SCI_SETLEXER
• SCI_SETLEXERLANGUAGE
• SCI_LOADLEXERLIBRARY

SCI_GETTEXT, SCI_GETSELTEXT and SCI_GETCURLINE

Since Scintilla version 5.1.5, calling any of these three APIs with an empty buffer returns a string length that does not count the final NULL character.
Code paths depending on the old implementation should add 1 to the return value.

Types provided by SciApi.inc:

• TSciApiLevel.sciApi_LT_5 – the running editor’s version of Scintilla is <= 4.4.6
• TSciApiLevel.sciApi_GTE_515 – the Scintilla version is at least 5.1.5

Methods provided by NppPlugin.pas:

• TNppPlugin.HasV5Apis – returns true if the running editor is at least version 8.4, the first release with a Scintilla v5 API

Optional Scintilla Features (as of v5.5.8)¹⁴

Use these compiler definitions to enable or disable features.

INCLUDE_DEPRECATED_FEATURES

Exposes the following API messages

SCI_SETKEYSUNICODE
SCI_GETKEYSUNICODE
SCI_GETTWOPHASEDRAW
SCI_SETTWOPHASEDRAW
SCI_SETSTYLEBITS
SCI_GETSTYLEBITS
SCI_GETSTYLEBITSNEEDED
INDIC0_MASK
INDIC1_MASK
INDIC2_MASK
INDICS_MASK

The following type aliases will also become available:

Alias	Type
CharacterRange	TSciCharacterRange
TextRange	TSciTextRange
TextToFind	TSciTextToFind
RangeToFormat	TSciRangeToFormat
NotifyHeader	TNotifyHeader

SCI_DISABLE_PROVISIONAL

Hides the following API messages

SC_BIDIRECTIONAL_DISABLED
SC_BIDIRECTIONAL_L2R
SC_BIDIRECTIONAL_R2L
SCI_GETBIDIRECTIONAL
SCI_SETBIDIRECTIONAL

Plugin API Reference

¹ NPPM_ADDTOOLBARICON_FORDARKMODE

² NPPM_ADDTOOLBARICON_DEPRECATED

³ TTbIconsDarkMode

⁴ NPPM_ISDARKMODEENABLED

⁵ NPPM_GETDARKMODECOLORS

⁶ NPPN_DARKMODECHANGED

⁷ DWS_USEOWNDARKMODE

⁸ TDarkModeColors

⁹ NPPM_DARKMODESUBCLASSANDTHEME

¹⁰ NppDarkMode::dmfInit

¹¹ NppDarkMode::dmfHandleChange

¹² NPPM_GETNATIVELANGFILENAME

¹³ NPPN_NATIVELANGCHANGED

¹⁴ Scintilla 5.5.8 definitions