2020-08-30

48: Create User/Application-Owned Python Macro for LibreOffice

<The previous article in this series | The table of contents of this series | The next article in this series>
Python will be far better than Basic, for many. Creating Python macros is not difficult, suspicious, or nerdish. Also for OpenOffice.

Topics


About: UNO (Universal Network Objects)
About: LibreOffice
About: Apache OpenOffice
About: The Python programming language

The table of contents of this article

Starting Context


  • The reader has a basic knowledge on LibreOffice or Apache OpenOffice.
  • The reader has a basic knowledge on the Python programming language.

Target Context


  • The reader will know how to create his or her user-owned or application-owned Python macro for LibreOffice or Apache OpenOffice.

Orientation


Also in-document Python macros can be created, which will be addressed in the next article.

Executing any macro (user-owned, application-owned, or in-document) function from your UNO program will be addressed in a future article.

The details of Python macro programming will be dug into in some future articles.

Using an external full Python has been addressed in a previous article.

Stage Direction
Here are Hypothesizer 7, Objector 48A, and Objector 48B in front of a computer.

Main Body

1: You Do Not Need to Use Basic for Creating Your Macro


Hypothesizer 7
 You do not need to use Basic for creating your macro.

Objector 48A
 Huh? Why shouldn't I use Basic?

Hypothesizer 7
 Sir, I did not say "shouldn't", but I guessed that you would not want to, if you knew a far better option.

Objector 48A
 Which is . . .

Hypothesizer 7
 Python.

Objector 48A
 Well, I thought I was supposed to use Basic.

Hypothesizer 7
 Sir, you do not need to do as you are supposed to do by whomever; you can do what you yourself choose to do.

Objector 48A
 But the GUI 'Edit Macros' menu item just shows the Basic IDE, as though I have to use it!

Hypothesizer 7
 You can edit your Python macro just outside the GUI.

Objector 48A
 "outside the GUI"? That is difficult, right?

Hypothesizer 7
 Not at all. Probably, you will be far happier without that not-so-unclumsy Basic IDE.

Objector 48A
 But that is a hack, right? It's suspicious! It's nerdish!

Hypothesizer 7
 Not particularly.

Objector 48A
 Basic is the standard, right?

Hypothesizer 7
 Standard or not, you are not obliged to be stuck with the very not-so-well-designed programming language.

Objector 48A
 "very not-so-well-designed" . . .

Hypothesizer 7
 To say nothing of its lack of some due functionality (like creating classes and using multiple threads), the foundations of it as a programming language do not seem to have been designed seriously.

Objector 48A
 Well, you seem to have a grudge against it.

Hypothesizer 7
 "grudge"? . . . Well, "grudge" seems to mean resentment because of a past experience, while I am sure that I am offended by Basic not because of a past experience, but because of how it is at present, if I am really offended, I mean.

2: How to Create Your User-Owned Python Macro


Hypothesizer 7
 In order to create your Python macro, you can forget the LibreOffice or Apache OpenOffice GUI.

Instead, you can create your Python macro with your favorite text editor or your favorite Python IDE.

Objector 48B
 Is that it?

Hypothesizer 7
 Madam, you just have to know the directory under which your Python macro should be located.

Objector 48B
 Where is it?

Hypothesizer 7
 The location is '~/.config/libreoffice/4/user/Scripts/python' for Linux or 'C:\Users\%user name%\AppData\Roaming\LibreOffice\4\user\Scripts\python' for Windows, or a like (there would be some differences between products and versions).

If you want to put your module in a package, you can just create the package directory under the base directory.

Objector 48B
 Well, can the macro be any Python module? I mean, doesn't it have to conform to some requirements like the class's extending a specific class?

Hypothesizer 7
 In fact, your macro function is just an ordinary Python function.

Objector 48B
 But what can I write inside the function?

Hypothesizer 7
 Anything (at least, almost), but if the function wants to handle UNO documents, of course, it has to do so in a certain way.

Objector 48B
 How, exactly?

Hypothesizer 7
 Such details will be addressed in some some future articles.

3: How to Create Your Application-Owned Python Macro


Hypothesizer 7
 In order to create your application-owned Python macro, what is different from creating your user-owned Python macro is only the directory under which your Python module should be located.

Namely, it is 'share/Scripts/python' in the LibreOffice or Apache OpenOffice product directory.

4: A Test


Hypothesizer 7
 As a test of user-owned Python macro, let us create a Python module under the base directory with these contents.

'theBiasPlanet/pythonEnvironmentChecker/macros/PythonEnvironmentChecker.py'

@Python Source Code 

import sys
from com.sun.star.frame import XDesktop2
from com.sun.star.lang import XComponent
from com.sun.star.script.provider import XScriptContext
from com.sun.star.text import XText

XSCRIPTCONTEXT: XScriptContext

def checkPythonEnvironment () -> None:
	l_unoDesktop: XDesktop2 = XSCRIPTCONTEXT.getDesktop ()
	l_currentUnoDocument: XComponent = l_unoDesktop.getCurrentComponent ()
	if hasattr (l_currentUnoDocument, "Text"):
		l_unoText: XText = l_currentUnoDocument.getText ()
		l_unoText = l_unoText.getEnd ()
		l_unoText.setString ("The Python environment: version -> {0:s}, paths -> {1:s}\n".format (sys.version, str (sys.path)))
		return None

Then, the 'theBiasPlanet.pythonEnvironmentChecker.macros.PythonEnvironmentChecker.checkPythonEnvironment ()' method is recognized as the 'theBiasPlanet.pythonEnvironmentChecker.macros.PythonEnvironmentChecker.checkPythonEnvironment ()' macro function.

Stage Direction
Hypothesizer 7 operates a LibreOffice instance, in which a Writer document is current, selecting 'Tools' -> 'Macros' -> 'Run Macro...' -> 'My Macros' -> 'theBiasPlanet' -> 'pythonEnvironmentChecker' -> 'macros' -> 'PythonEnvironmentChecker' -> 'checkPythonEnvironment' -> 'Run'; this is written to the document.

@Output 
The Python environment: version -> 3.8.2 (default, Jul 16 2020, 14:00:26) 
[GCC 9.3.0], paths -> ['/home/tanichida/myApplications/libraries/python/ZSI-2.0-py2.7.egg', '/usr/lib/libreoffice/program', '/home/tanichida/myApplications/libraries/python', '/usr/lib/python38.zip', '/usr/lib/python3.8', '/usr/lib/python3.8/lib-dynload', '/home/tanichida/.local/lib/python3.8/site-packages', '/usr/local/lib/python3.8/dist-packages', '/usr/lib/python3/dist-packages', '/usr/lib/libreoffice/program']

Hypothesizer 7
 We will not particularly need to create any application-owned Python macro for a test here, because there are some built-in samples, like the 'HelloWorld.py'.

References
<The previous article in this series | The table of contents of this series | The next article in this series>
Posted by at
Labels: