NAME

Win32::Mechanize::NotepadPlusPlus::Notepad - The main application object for Notepad++ automation

SYNOPSIS

    use Win32::Mechanize::NotepadPlusPlus ':main';
    my $npp = notepad();    # main application

DESCRIPTION

The editor object for Notepad++ automation using Win32::Mechanize::NotepadPlusPlus

Constructors

The Constructors and similar object methods in this section are purely for class access, and will be called by the NotepadPlusPlus object. They should never need to be referenced directly. (Instead, you will get the notepad, editor1, editor2, and editor instances from the app instance)

notepad
editor1
editor2

editor

    use Win32::Mechanize::NotepadPlusPlus;                      # creates the singleton ::Notepad object
    my $npp = Win32::Mechanize::NotepadPlusPlus::notepad();     # calls ...Notepad::notepad()
    my $ed1 = Win32::Mechanize::NotepadPlusPlus::editor1();     # calls ...Notepad::editor1()
    my $ed2 = Win32::Mechanize::NotepadPlusPlus::editor2();     # calls ...Notepad::editor2()
    my $ed  = Win32::Mechanize::NotepadPlusPlus::editor();      # calls ...Notepad::editor()

API

This API was based on the Notepad++ plugin PythonScript's API for the Notepad object.

Files

These methods open, close, and save files (standard File menu operations).

notepad()->close(): Closes the currently active document
notepad()->closeAll(): Closes all open documents
notepad()->closeAllButCurrent(): Closes all but the currently active document
notepad()->newFile(): Create a new document.
notepad()->open(filename): Opens the given file.
notepad()->save(): Save the current file
notepad()->saveAllFiles(): Saves all currently unsaved files
notepad()->saveAs($filename): Save the current file as the specified $filename
notepad()->saveAsCopy($filename): Save the current file as the specified $filename, but don’t change the filename for the buffer in Notepad++

Sessions

Sessions allow you to make a group of files that you can easily reload by loading the session.

notepad()->saveCurrentSession($filename)

Save the current session (list of open files) to a file.

notepad()->saveSession($filename, @filesList)

Saves a session (list of filenames in @filesList) to a file.

notepad()->loadSession($sessionFilename)

Opens the session by loading all the files listed in the $sessionFilename.

notepad()->getSessionFiles($sessionFilename)

Reads the session stored in $sessionFilename, and returns a list of the file paths that it references.

This does not open the files in the session; to do that, use notepad()->loadSession($sessionFilename)

Buffers and Views

These methods influence which views are available and which file buffers are available in which views; they also read or manipulate the information about the files in these buffers.

Views relate to the one or two editor windows inside Notepad++. Buffers are the individual file-editing buffers in each view. Because each view has a group of buffers, each buffer has an index within that view.

Get/Change Active Buffers

These methods allow you to change which file buffer is active in a given view, and get information about which view and buffer are active.

notepad()->activateBufferID($bufferID): Activates the given $bufferID
notepad()->activateFile($filename): Activates the buffer with the given $filename, regardless of view.
notepad()->activateIndex($view, $index): Activates the document with the given $view and $index. view is 0 or 1.
notepad()->getCurrentBufferID(): Gets the bufferID of the currently active buffer
notepad()->getCurrentDocIndex($view): Gets the current active index for the given $view (0 or 1)
notepad()->getCurrentView()
notepad()->getCurrentScintilla(): Get the currently active view (0 or 1)
notepad()->moveCurrentToOtherView(): Moves the active file from one view to another
notepad()->cloneCurrentToOtherView(): Clones the active file from one view to the other, so it's now available in both views (which makes it easy to look at different sections of the same file)

Get Filename Information

These methods allow you to get the filename for a selected or active buffer, or get the list of all currently-open files.

notepad()->getBufferFilename( $bufferid )

notepad()->getBufferFilename( )

Gets the filename of the selected buffer.

If $bufferid is omitted, it will get the filename of the active document

notepad()->getCurrentFilename()

Gets the filename of the active document

notepad()->getFiles()

Gets a list of the open filenames.

Returns: A reference to an array-of-arrays, one row for each file, with filename, bufferID, index, and view as the elements of each row:

[ [$filename1, $bufferID1, $index1, $view1], ... [$filenameN, $bufferIDN, $indexN, $viewN] ]

notepad()->getNumberOpenFiles($view)

notepad()->getNumberOpenFiles()

Returns the number of open files in $view, which should be 0 or 1. If undef or $view not given, return total number of files open in either view.

Get/Set Language Parser

These methods allow you to determine or change the active language parser for the buffers.

notepad()->getCurrentLang()

Get the current language type

Returns: LANGTYPE

notepad()->getLangType($bufferID)

notepad()->getLangType()

Gets the language type of the given $bufferID. If no $bufferID is given, then the language of the currently active buffer is returned.

Returns: An integer that corresponds to

TODO: will eventually map those integers to names for the language

notepad()->setCurrentLang($langType)

Set the language type for the currently-active buffer.

notepad()->setLangType($langType, $bufferID)

notepad()->setLangType($langType)

Sets the language type of the given bufferID. If not bufferID is given, sets the language for the currently active buffer.

notepad()->getLanguageName($langType)

notepad()->getLanguageDesc($langType)

Get the name and or longer description for the given language $langType.

Encoding and EOL Information

Determines the encoding for a given file, and determines or changes the EOL-style for the file buffer.

notepad()->getEncoding($bufferID)

notepad()->getEncoding()

Gets the encoding of the given bufferID. If no bufferID is given, then the encoding of the currently active buffer is returned.

Returns: An integer corresponding to how the buffer is encoded

TODO = need to see if there are appropriate messages for setting/changing encoding

TODO = need to map encoding to meaningful words

notepad()->getFormatType($bufferID)

notepad()->getFormatType()

Gets the EOL format type (i.e. Windows [0], Unix [1] or old Mac EOL [2]) of the given bufferID. If no bufferID is given, then the format of the currently active buffer is returned.

Returns: The integers 0,1,or 2, corresponding to Windows EOL (CRLF), Unix/Linux (LF), or the old Mac EOL (CR).

notepad()->setFormatType($formatType, $bufferID)

notepad()->setFormatType($formatType)

Sets the EOL format type (i.e. Windows [0], Unix [1] or old Mac EOL [2]) of the specified buffer ID. If not bufferID is passed, then the format type of the currently active buffer is set.

Reload Buffers

These methods allow you to reload the contents of the appropriate buffer from what is on disk.

notepad()->reloadBuffer($bufferID): Reloads the given $bufferID
notepad()->reloadCurrentDocument(): Reloads the buffer of the current document
notepad()->reloadFile($filename): Reloads the buffer for the given $filename

Hidden Scintilla Instances

When automating Notepad++, there are times when you may want an extra Scintilla Editor instance, even though it never needs to be seen inside the Notepad++ window. You can create and destroy hidden instances using these methods

notepad()->createScintilla()

notepad()->createScintilla( $parentHwnd )

Create a new Scintilla handle. Returns an Editor object. This Scintilla editor instance is not available to be displayed in either view, but in all other ways behaves like the main Scintilla Editor instances.

If $parentHwnd is passed (non-zero), that HWND will be used as the parent window for the new Scintilla; otherwise, Notepad++ itself will be used as the parent.

Please note: as of v7.8, there is no way to properly destroy the created Scintilla handle. There are a limited number of Scintilla handles that can be allocated before.

notepad()->destroyScintilla($editor)

This method always returns a true, and warns that the method is deprecated.

In Notepad++ v7.7.1 and earlier, the NPPM_DESTROYSCINTILLAHANDLE tried to destroy the scintilla instance. However, this could crash Notepad++, so as of v7.8, Notepad++ ignores this message. To prevent Win32::Mechanize::NotepadPlusPlus from crashing Notepad++, the destroyScintilla() does not bother to send the message (in case it's Notepad++ v7.7.1 or earlier).