diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index 7339c4d0..1322e745 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -1,4 +1,4 @@
-Introduction
+Introduction
============
.. highlight:: python
@@ -11,20 +11,20 @@ Don't worry if you've not seen, or never even heard of Python_, it's incredibly
To whet your appetite, here's a quick (complete) sample script that shows some of the power of Python Script.::
editor.replace("old", "new")
- editor.pyreplace(r"^Code: ([A-Z]{4,8})", r"The code is \1")
-
- notepad.runMenuCommand("TextFX Tools", "Delete Blank Lines")
+
+ notepad.runMenuCommand("Line Operations", "Remove Empty Lines")
+
notepad.save()
-Line 1 performs a normal search and replace on the current document, replacing the word "old" with the word "new".
-
-Line 2 also performs a search and replace, but uses Python_ regular expressions, which is a much more complete implementation of regular expressions than is natively supported in Notepad++.
+Line 1 performs a normal search and replace on the current document, replacing the word "old" with the word "new".
-Line 4 runs the menu command called "Delete Blank Lines" from the TextFX Tools menu.
+Line 3 runs the menu command called "Remove Empty Lines" from menu: Edit -> Line Operations.
Line 5 saves the current document (equivalent to clicking File, Save).
+WARNING: While for the most part, a PythonScript script will behave like a Python script run by a Python interpreter, one important difference is that ``exit()``, ``quit()`` and related functions like ``sys.exit()`` and ``os._exit(0)``, that normally terminate the script and exit the Python interpreter, in PythonScript they will also abruptly terminate Notepad++ (crash it without saving your unsaved files and other data). So, you best avoid them, and use other techniques for early exiting from your code (like ``return`` inside a function, for example).
+
Objects
========
@@ -76,11 +76,13 @@ append ``.decode('utf8')`` to the string. Obviously if your string is in a diffe
To put text back to Scintilla (so editor.something()), use .encode('utf8') from a unicode string.
For example::
-
+
+ # -*- coding: utf-8 -*-
+
# define a unicode variable
someUnicodeString = u'This häs fünny ünicode chäractêrs in it'
- # append the text to the current buffer - assuming the current buffer is set to utf8
+ # add the string to the current buffer at current position - assuming the current buffer is set to utf8
editor.addText(someUnicodeString.encode('utf8'))
# grab the first line
@@ -93,7 +95,7 @@ For example::
firstLineUnicode = firstLineUnicode.upper()
# and put the line back
- editor.replaceWholeLine(firstLineUnicode.encode('utf8')
+ editor.replaceWholeLine(0, firstLineUnicode.encode('utf8') )
.. _Notifications:
@@ -106,14 +108,14 @@ Overview
You can call a Python function when events occur in Notepad++ or Scintilla_. Events in Notepad++ are things like the active document changing, a file being opened or saved etc. Events in Scintilla are things like a character being added, a *save point* being reached, the document being made *dirty* and so on.
-Basically, you register in a script a Python_ function to call when an event occurs, and thereafter the function always runs whenever that event occurs. One function can be registered to handle more than one event.
+Basically, you register in a script a Python_ function to call when an event occurs, and thereafter the function always runs whenever that event occurs. A function in such a role will be called an event handler or a "callback". One function can be registered to handle more than one event.
You can unregister the callback later, either by using the name of the function, or the event names, or a combination.
A simple example
----------------
-Let's register a callback for the FILEBEFORESAVE event - the occurs just before the file is saved,
+Let's register a callback for the FILEBEFORESAVE event - which occurs just before the file is saved,
and we'll add a "saved on" log entry to the end of the file, if the filename ends in '.log'.::
import datetime
@@ -124,19 +126,21 @@ and we'll add a "saved on" log entry to the end of the file, if the filename end
notepad.callback(addSaveStamp, [NOTIFICATION.FILEBEFORESAVE])
+Note: the actual registration happens when you run the script. If run this script N times, then N registrations will occur: once the event occurs, N times the callback function will be called. Callbacks will be active until you close Notepad++, or disable them in a script as explained later in this section.
+
Line 1 imports the datetime module so we can get today's date.
Line 3 defines a function called ``addSaveStamp``.
-Line 4 checks that the extension of the file is '.log'.
+Line 4 checks that the extension of the currently-active file is '.log'.
Line 5 appends text like ``"File saved on 2009-07-15"`` to the file.
Line 7 registers the callback function for the FILEBEFORESAVE event. Notice the square brackets around the ``NOTIFICATION.FILEBEFORESAVE``. This is a list, and can contain more than one item (so that the function is called when any of the events are triggered).
-Really, we should improve this function a little. Currently, it assumes the file being saved is the active document - in the case of using "Save All", it isn't necessarily. However, it's easy to fix...
+Really, we should improve this function a little. Currently, it assumes the file being saved is the active document - but in the case of using "Save All", it isn't necessarily. However, it's easy to fix...
-The ``args`` parameter to the function is a map (similar a dictionary in C# or a hashmap in Java), that contains the arguments for the event - many events are signalled for a ``BufferID``, which is the Notepad++ internal number for a particular file or tab. We can do things with the bufferID like get the filename, switch to it to make it active and so on.
+The ``args`` parameter to the function is a map (similar to a dictionary in C# or a hashmap in Java), that when the callback is registered, will contain the arguments from (details of) the event. Many events are signalled for a specific ``BufferID``, which is the Notepad++ internal number for a particular file or tab. We can do things with the bufferID like get the filename, switch to it to make it active and so on.
So, first we'll change it so that we check the filename of the bufferID being saved, rather than the active document.
Then, if the filename has a '.log' extension, we'll change to it and add our "File saved on ....." line.::
@@ -152,7 +156,7 @@ Then, if the filename has a '.log' extension, we'll change to it and add our "Fi
-Great, now it works properly. There's a side effect though, if we do use save-all, we might change the active document,
+Great, now it works properly. There's a side effect though, if we do use save-all when the current document is other than a ".log" file, the callback will make that ".log" file the active document,
which might seem a bit strange when we use it. Again, very easy to fix.::
@@ -169,7 +173,7 @@ which might seem a bit strange when we use it. Again, very easy to fix.::
Now everything works as should, and it's nice and easy to see what's going on, and we leave the user with the same document they had open if they use Save-All.
-See the :class:`NOTIFICATION` enum for more details on what arguments are provided for each notification, and the different events that are available.
+See the :class:`NOTIFICATION` enum for more details on what arguments are provided from each notification, and the different events that are available.
Cancelling Callbacks
--------------------
@@ -180,42 +184,87 @@ The simplest form is::
notepad.clearCallbacks()
-This unregisters all callbacks for all events. If you want to just clear one or more events, just pass the list of :class:`NOTIFICATION` events you wish to clear.::
+This unregisters all callbacks for all new events. If you want to just clear one or more events, just pass the list of :class:`NOTIFICATION` events you wish to clear.::
notepad.clearCallbacks([NOTIFICATION.FILEBEFORESAVE, NOTIFICATION.FILESAVED])
*Note that if you want to clear the callback for just one event, you still need to pass a list (i.e. surrounded with square brackets)*
-To unregister a callback for a particular function, just pass the function.::
+To unregister all callback for a particular function, just pass the function::
notepad.clearCallbacks(addSaveStamp)
-To unregister a callback for a particular function, for particular events (perhaps you want to keep the function registered for FILEBEFORESAVE, but don't want FILESAVED anymore)
+To unregister a callback for a particular function, for particular events (perhaps you want to keep the function registered for FILEBEFORESAVE, but not for FILESAVED anymore)::
notepad.clearCallbacks(addSaveStamp, [NOTIFICATION.FILESAVED])
-*Note that redefining the function (in this case ``addSaveStamp``) will mean that this method no longer works, as the function name is now a new object.*
+*Note that redefining the function (in this case ``addSaveStamp``) will mean that this method, or the one before it, no longer works, as the function name is now a new object. Same problem if you re-run the script registering the callback several times: calling ``notepad.clearCallbacks(addSaveStamp)`` or ``notepad.clearCallbacks(addSaveStamp, [NOTIFICATION.FILESAVED])`` will only clear the most recently added callback. If these situations occur, you can use one of the other 2 forms of the ``clearCallbacks`` function *
-The Callback smallprint
+Synchronous and Asynchronous Callbacks
-----------------------
-Due to the nature of Scintilla events, they are by default processed internally slightly differently to Notepad++ events.
-Notepad++ events are always processed *synchronously*, i.e. your event handler finishes before Python Script lets
-Notepad++ continue. Scintilla events are placed in a queue, and your event handlers are called as the queue is *asynchronously* processed
-- i.e. the event completes before your event handler is complete (or potentially before your event handler is even called).
+By default, Notepad++ events and Scintilla events are, by default, processed internally slightly differently.
+Notepad++ events are always processed *synchronously* ("in sync", in step) relative to Notepad++ : your event handler finishes before Python Script lets Notepad++ continue with creating and processing other events. Thus, Notepad++ will appear unresponsive to a new user action for the (usually very short) period until the handler has finished processing current event.
+The following script demostrates this::
-The only visible difference is that if you have a lot of callbacks registered, or your callbacks perform a lot of work, you might receive
-the event some time after it has actually occurred. In normal circumstances the time delay is so small it doesn't matter, but you may
+ console.clear()
+ import time
+
+ starttime=time.time()
+
+ def on_buffer_activated(args):
+ print("on_buffer_activated")
+ print((time.time()-starttime)//1) ,
+ print(" ") ,
+ time.sleep(4)
+ print((time.time()-starttime)//1)
+
+ notepad.callback(on_buffer_activated, [NOTIFICATION.BUFFERACTIVATED])
+
+ time.sleep(20)
+
+ notepad.clearCallbacks()
+
+ print("\nExperiment is over.")
+
+
+In case of Scintilla events, when you use ``editor.callback(..)`` to register callbacks for them, their notifications are placed in a queue that is processed *asynchronously* relative to Notepad++ app. This means that while your event handler on one particular notification in the queue, Notepad++ does not wait for the handler to finish before accepting and responding to other user events. As a result, a particular event may happen a long time before your event handler finishes processing that event (notification) (or potentially before your event handler is even called).
+
+In normal circumstances the time delay is so small it doesn't matter, but you may
need to be aware of it if you're doing something time-sensitive.
+The script below demonstrates asynchronous processing where the delay is deliberately exaggerated::
+
+ console.clear()
+ import time
+
+ starttime=time.time()
+
+ def on_update_ui(args):
+ print("on_update_ui")
+ print((time.time()-starttime)//1) ,
+ print(" ") ,
+ time.sleep(4)
+ print((time.time()-starttime)//1)
+
+ editor.callback(on_update_ui, [SCINTILLANOTIFICATION.UPDATEUI])
+
+ time.sleep(20)
+
+ editor.clearCallbacks()
+
+ print("\nExperiment is over.")
+
+If you tried sufficiently many actions during its run (clicks in text or menu, selections etc), then you would notice that after the script finished, thus the callback unregistered, the console is still outputing print-out messages from the handler. That is because the event handler was STILL processing some past events left on the queue. The ``clearCallbacks(...)`` functions only disable the handler for NEW events (not yet on the queue).
+
+One other reason to be aware of the asynchronous nature of default Scintilla callbacks (besides potential lag in time relative to actual events) is that both your event handler in PythonScript and Notepad++ can access the same variable/state (from different threads), which could lead to unexpected behavior if you are not careful.
+
+However, as of version 1.0, you can use :meth:`Editor.callbackSync` to add a synchronous callback for Scintilla events. This allows you to perform time-sensitive operations in an event handler. In particular, it allows for calling :meth:`Editor.autoCCancel` in a ``SCINTILLANOTIFICATION.AUTOCSELECTION`` notification to cancel the auto-complete.
- As of version 1.0, you can use :meth:`Editor.callbackSync` to add a synchronous callback. This allows you to perform time-sensitive
- operations in an event handler. It also allows for calling :meth:`Editor.autoCCancel` in a ``SCINTILLANOTIFICATION.AUTOCSELECTION``
- notification to cancel the auto-complete. Note that there are certain calls which cannot be made in a synchronous callback -
- :meth:`Editor.findText`, :meth:`Editor.searchInTarget` and :meth:`Editor.setDocPointer` are notable examples. :meth:`Notepad.createScintilla`
- and :meth:`Notepad.destroyScintilla` are other examples in the ``Notepad`` object - note that this only applies to Scintilla (``Editor``) callbacks,
- ``Notepad`` callbacks can perform any operation.
+Note that there are certain calls which cannot be made in a *synchronous* Scintilla (``Editor``) callback - :meth:`Editor.findText`, :meth:`Editor.searchInTarget` and :meth:`Editor.setDocPointer` are notable examples.
+:meth:`Notepad.createScintilla` and :meth:`Notepad.destroyScintilla` are other examples in the ``Notepad`` object.
+``Notepad`` callbacks do not have such restrictions.
diff --git a/docs/source/notepad.rst b/docs/source/notepad.rst
index ba9a47cb..1b3aa0a8 100644
--- a/docs/source/notepad.rst
+++ b/docs/source/notepad.rst
@@ -78,13 +78,6 @@ Notepad++ Object
Unregisters all callbacks
-.. method:: notepad.clearCallbacks(function)
-
- Unregisters all callbacks for the given function. Note that this uses the actual function object, so if the function has
- been redefined since it was registered, this will fail. If this has happened, use one of the other ``clearCallbacks()``
- functions.
-
-
.. method:: notepad.clearCallbacks(eventsList)
@@ -94,9 +87,14 @@ Notepad++ Object
See :class:`NOTIFICATION`
+
+.. method:: notepad.clearCallbacks(function)
+
+ Unregisters all callbacks for the given function. Note that this uses the actual function object, so if the function has been redefined since it was registered, or if the script doing the registration of the callback has been re-run, then ``clearCallbacks(function)`` will fail. In such cases, use one of the other ``clearCallbacks`` functions.
+
.. method:: notepad.clearCallbacks(function, eventsList)
- Unregisters the callback for the given callback function for the list of events.
+ Unregisters all callbacks for the given callback function for the list of events. Same note as for the previous variant applies.
.. method:: notepad.close()
diff --git a/docs/source/pythonprimer.rst b/docs/source/pythonprimer.rst
index 0de2bf49..4de0244d 100644
--- a/docs/source/pythonprimer.rst
+++ b/docs/source/pythonprimer.rst
@@ -24,7 +24,8 @@ You can define a variable simply by using it.::
To call a function, just type the name, followed by brackets, with any arguments in brackets.::
x = 5
- console.write(x)
+ print(x)
+ console.write(str(x))
If Statements
@@ -34,35 +35,37 @@ An ``if`` statement doesn't need brackets around the test, just a colon (:) at t
The ``if`` block continues until the indentation reverts to the same indentation as the ``if`` line.::
-
- console.write("Let's go")
+ x=3
+ console.write("Let's go\n")
if x == 3:
- console.write("So x is 3 then")
- console.write("This line is also run if x is 3")
- console.write("this line is run always")
+ console.write("So x is 3 then\n")
+ console.write("This line is also run if x is 3\n")
+ console.write("this line is run always\n")
To use an else, place the else at the same level as the if, and append a colon::
+ x=4
if x == 3:
- console.write("So x is 3 then")
- console.write("This line is also run if x is 3")
+ console.write("So x is 3 then\n")
+ console.write("This line is also run if x is 3\n")
else:
- console.write("Guess x isn't 3 this time.")
- console.write("Better luck next time")
+ console.write("Guess x isn't 3 this time.\n")
+ console.write("Better luck next time\n")
- console.write("this line is run always")
+ console.write("this line is run always\n")
If you want an "else if", use ``elif``::
+ x=7
if x == 3:
- console.write("So x is 3 then")
- console.write("This line is also run if x is 3")
+ console.write("So x is 3 then\n")
+ console.write("This line is also run if x is 3\n")
elif x == 6:
- console.write("Hey it's your lucky day, x is 6")
+ console.write("Hey it's your lucky day, x is 6\n")
else:
- console.write("x is not 3 or 6 this time.")
- console.write("Better luck next time")
+ console.write("x is not 3 or 6 this time.\n")
+ console.write("Better luck next time\n")
Functions
@@ -72,7 +75,7 @@ To define a function, just use ``def``. Again, the indentation is important, th
def printNameAge(name, age):
console.write("Hello {0}, ".format(name))
- console.write("how was your {0} birthday?".format(age))
+ console.write("how was your {0}th birthday?\n".format(age))
printNameAge("Dave", 99)
@@ -87,11 +90,11 @@ To pass the function to another function (as in callbacks in Python Script), jus
def printNameAge(name, age):
console.write("Hello {0}, ".format(name))
- console.write("how was your {0} birthday?".format(age))
+ console.write("how was your {0}th birthday?\n".format(age))
- def callFunc(func)
- console.write("Calling function...\n")
+ def callFunc(func):
+ console.write("Calling a function...\n")
func("Dave", 99)
@@ -101,7 +104,37 @@ To pass the function to another function (as in callbacks in Python Script), jus
Line 11 calls the ``callFunc`` function, passing the printNameAge function to it. The ``callFunc`` function then calls printNameAge on line 8.
+Scope
+-----
+One other important benefit of functions is that they will create a *local scope*: the variables you define inside the function definition will not be available to code outside this region (while from inside the region, you can still access variables from outside).
+Variables, and functions, defined at top level of the script, outside functions definitions, are in what is called *global scope*: accessible from everywhere.
+You can see this by creating and running the following 3 scripts, in succession:
+
+Script1::
+
+ x=1
+ print(x)
+
+Script2::
+
+ print(x)
+ x=2
+
+Script3::
+
+ print(x)
+
+Most of the time, allowing scripts to create and access mutually accessible variable can lead to nasty bugs.
+One simple and effective way to avoid that is to use the following structure for EVERY script that you write, at least in your beginner's journey::
+
+ def main():
+ // the "meat" of your code
+
+ main()
+
+
+Not only it prevents bad script inter-action, but it will also allow you to use ``return`` (among other ways) to terminate your script early, if needed (see the Warning on the danger of ``exit()`` in Introduction section).
Strings
@@ -111,6 +144,8 @@ Strings use double or single quotes. There's no difference, but that helps if y
someString = "this is a string with a ' single quote inside"
someOther = 'this is a string with a " double quote inside'
+ print(someString)
+ print(someOther)
If you need both, just use ``\`` to escape them::
@@ -121,10 +156,13 @@ If you need to use ``\`` itself, just include two::
someString = "here's a demo of using a \\ backslash"
-You can also use ``raw`` strings. These don't need the ``\\`` to mean ``\``, which can make certain strings (particularly regular expressions) easier to understand. However, you also can't escape a quote. To make a raw string, just put an ``r`` before the string
+You can also use ``raw`` strings. These don't need the ``\\`` to mean ``\``, which can make certain strings (particularly regular expressions) easier to understand. However, you also can't escape a quote.
+To make a raw string, just put an ``r`` before the string::
someString = r"this is also a string using a \\ backslash"
+Exception: you cannot use a backslash right before the ending quote; it will escapes that quote, producing an error.
+
Further Information
-------------------
@@ -141,4 +179,4 @@ And all the information is available on https://www.python.org
.. _Python: https://www.python.org/
-.. _Scintilla: https://www.scintilla.org/
\ No newline at end of file
+.. _Scintilla: https://www.scintilla.org/
diff --git a/docs/source/scintilla.rst b/docs/source/scintilla.rst
index 0097a847..af071cdb 100644
--- a/docs/source/scintilla.rst
+++ b/docs/source/scintilla.rst
@@ -4978,19 +4978,20 @@ Helper Methods
Gets the start and end (zero indexed) byte numbers of the user selection, or the whole document if nothing is selected.
+
.. method:: editor.clearCallbacks()
Clears all callbacks
-.. method:: editor.clearCallbacks(function)
+.. method:: editor.clearCallbacks(eventsList)
- Clears all callbacks for a given function
+ Clears all callbacks for the given list of events
-.. method:: editor.clearCallbacks(eventsList)
+.. method:: editor.clearCallbacks(function)
- Clears all callbacks for the given list of events
+ Clears all callbacks for a given function
.. method:: editor.clearCallbacks(function, eventsList)
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 9422a65c..9fe314f7 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -63,8 +63,8 @@ script to the menu, then it will appear immediately, but you will not be able to
If you assign it to a toolbar icon, then it will only appear on the next start of Notepad++.
-Context-Sensitive help is available - if your cursor is on and notepad, editor or console function, the ``Context-Help`` menu
-will take you straight to the documentation for that function. If the CHM file is not in the relevant location, it will open the
+Context-Sensitive help is available - if your cursor is on a notepad, editor or console function, the ``Context-Help`` menu
+will take you straight to the documentation for that function. If the CHM (context help manual) file is not in the relevant location, it will open the
documentation from the web.
@@ -77,6 +77,6 @@ The script called startup.py (in either the "machine" directory or "user" direct
starts up. Normally, that is the first time a script is called. The default startup.py script does some small things like directing
the error output to the console, and importing some commonly used modules.
-If you want to register an callback (see :ref:`Notifications`) to run from when Notepad++ starts up, you need to change the startup type
+If you want to register a callback (see :ref:`Notifications`) to run from when Notepad++ starts up, you need to change the startup type
to ATSTARTUP, instead of LAZY. You can do this in the Configuration dialog.