When you write a macro within libreOffice, you will quickly realise something. It’s not really convenient to execute macros through the Macro Manager. This is because you need to access that menu, and it takes a few clicks to do so. (Quickest way to access the APSO Macro manager being [Alt] + [Shift] + [F11]). Creating a button on your spreadsheet is easy. You can assign this button to your macro. When you click on the button, it will execute the macro.
So first we’ll Switch to Design Mode. This allows us to create a button on the spreadsheet. Then, we’ll assign the python macro to this button.

Switch to Design Mode: (Back to Top)

The first step is to set the document to ‘Design Mode’ . Select ‘Design Mode’ From ‘Menu Tools/Forms/Design Mode’.

Create a button: (Back to Top)
Then simply by clicking on Menu ‘Insert>Form Controls>Push Button’:

Once you have the little cross to insert the button, click for the button’s upper left corner. Then hold and release where you want the bottom right corner of the button.

Assign the python macro: (Back to Top)
Once you have the button displayed, right click on it and select ‘Control…’

Then in the window ‘Properties’ select the ‘Events’ tab, scroll down a bit to find in the list of events the one called ‘Mouse button pressed’. On the right of this ‘Mouse button pressed’ entry click on the button ‘[…]’.

A window named “Assign Action’ pops up, click on the button ‘[Macro]’ on the right hand side of this window.

You should then get the ‘Macro Selector’ with your Macro Libraries. Simply go to the library where your macro is saved and select the macro ‘HelloWorld’,then press ‘OK’.

Then ‘OK’ again in ‘Assign Macro’ window, than close the ‘Properties’ window.
The last thing to do is exit the ‘Design’ mode. This allows you to click on the button. Do that by going to ‘Tools>Forms>Design Mode’.

And now when you click on the button… tada…
If you get this ERROR!

The function HelloWorld requires all information from LibreOffice Context to work. This information is needed in the form of an argument. So we need to pass the argument ‘*args’ in your function called by the Push Button.
For example in the program HelloWorld done in a previous post, in your code instead of:
def HelloWorld():
You should have:
def HelloWorld(*args):
Save your program again and then when you press on the button the cell A1 will display ‘Hello World!’ !!!

So there is the final version of the macro:

# Created by Gweno 16/08/2019 for tutolibro.tech
# This program displays 'Hello World!" in cell A1 of the 
# current Calc document.

def HelloWorld(*args):
    """Write 'Hello World!' in Cell A1"""
    
# get the doc from the scripting context 
# which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
# access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

# write 'Hello World' in A1
    active_sheet.getCellRangeByName("A1").String = "Hello World!"

You can clone or download this code from gitHub here.

Good luck! and leave a comment if you are having problem to have this macro to work.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

In this Part 1 of LibreOffice Calc & Python programming tutorial we are looking at:

• some Software you need
• the APSO extension that’ll make things much easier
• an extra step for Linux users
• useful documentation
• further notes

Software

LibreOffice

You will of course need LibreOffice, you can download the latest version here.
LibreOffice is normally shipped with a PyUNO bridge. This allows it to bind its components with the Python language. It also makes it possible to program LibreOffice with Python. (see at end of this article if you’re using a Linux ).

Python 3

You also need the Python 3 programming language on your computer.
It may be installed already. For now I let you do it yourself, but I might write a quick help later. Just web search for ‘python 3’ for your Operating system.

IDE / Text Editor

You will also need a text editor or even better an IDE (Integrated Development Environment) to write your python program. The advantage of an IDE versus a simple text editor is that it offers tools to organise your codes, an IDE can also makes it easier to spot errors and offers all sort of features to speed up and ease coding like word auto-completion, search and replace.
If you are a programmer you may already have a preference for a simple editor or a clever one. I am using a free open-source IDE called geany, but other popular ones are Eclipse, code::block and the famous Microsoft Visual Studio. They all have their pros and cons, here is the Top 20 of the most popular ones. Geany is perfect for ‘small jobs’ like we are going to do, but again it’s also fine to use a text editor like notepad.

JRE install

If your computer does not have Java Runtime Environment already you will need to install it through the Oracle website. You can also follow instruction here. JRE is indeed required to be able to use macros within LibreOffice.

APSO extension

By default LibreOffice Python Macros are independent from any LibreOffice file. So to execute a python program within a LibreOffice Calc Spreadsheet for example you would need to go in Tools/Macro/Run Macro and select the python program from a list corresponding to a folder on your Hard drive. And this list, for example ‘MyMacro’, would be accessible for any LibreOffice file (Calc, Text, Base, etc…). This is great but not helpful when you want a particular python program to be used specifically for a particular file.
APSO is a LibreOffice extension that helps with organising Python Macros within your LibreOffice files. You just need to download the APSO extension here and then install the tool via Tools/Extensions Manager. One great advantage of APSO is its EditorKicker that you can set up to use your preferred text editor or IDE to edit your Python program.
One last note about using APSO, although the programs themselves are saved in the same folders than all other programs, the ones you choose to be embed in a particular file will be linked to that file, or rather for example LibreOffice calc file will have a link to the python program in its parameters and you will be able to see your program attached to LibreOffice documents currently opened.

Extra step for linux

I had to do one extra step when I was using LibreOffice 5 under Linux mint Operating System: adding some library. Without it it was not possible to do any Python macros within LibreOffice. This is an easy step, just open a terminal, type and execute:

sudo apt-get install libreoffice-script-provider-python

It will be the same for Ubuntu. For other linux distro you will need to check yourself but it’d be similar using the in-house package manager.

Documentation

It is not easy to find helpful documentation for programming Python Macros for LibreOffice. Firstly it’s hard to find a site or forum that have real documentation about using Python for LibreOffice, and secondly the tasks explained are usually too complicated for a beginner. However this is the best place I found so far with a list of links to Python program examples. You will not that most of the examples are using a Python library created by ‘Danny’.

Further notes

In my tutorial we will create everything from scratch and develop simple and useful functions.
I still haven’t decided what topic to cover to illustrate this tutorial. I am hesitating between continuing the time schedule, starting invoice manager or a garden planner.
If you have any preference please let me know in your comment.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

This article helps you decide whether to embed your python macro in the file. It also explores saving it in a macro repository.

With the APSO add-on (see previous article) you can embed your macro within the LibreOffice File. This can be useful for example when you want to send your LibreOffice file with the Python Macro. A downside is that the Python macro will not be accessible outside of the LibreOffice file you sent. So you will need to open the LibreOffice file. Then open the Python Macro organiser. This is necessary to edit the Python program.

There are alternatives to embedding the Python program. You can place it in an organized directory while still using APSO. This lets you re-use it for any other LibreOffice document. You can also edit the program without opening the LibreOffice document if you open it from the relevant folder. If you want to send your LibreOffice Document to someone, there is a trade-off. You will also need to send the Python macro.

I am in favor of keeping programs in a tidy manner. This approach allows me to re-use them across many different files. But the choice is entirely up to you. I hope

To illustrate these 2 cases, let’s have a look at an example:

I have a file called “HelloWorld.ods” and two Python files: the first one is called “HelloWorld.py” and the other file is called “Testing.py”. The first python file is embedded in the LibreOffice file, the second is in the shared Python Scripts directory.

In the first case scenario, after opening HelloWorld.ods, I can go to the Python Script Organizer, in Tools>Macro>Organize Python Scripts (shortcut Alt+Shift+F11) from the APSO extension. Alternatively I can use the LibreOffice Standard Macro Organiser in Tools>Macro>Organise Macros>Python….

In the Python Scripts Organiser you will see that your Python Macro is listed within the LibreOffice File’s name.

When you choose to edit the Python Macro, select ‘Menu>Edit’ from the ‘Python scripts’ window. The edited file’s path is temporary. It is only used for the time of editing this Python program.

So where is the Python Script saved on your hard drive?
As I wrote earlier, it’s embedded in the LibreOffice File. If you don’t believe me, here is a trick to find out:
If I rename my ‘HelloWorld.ods’ in ‘HelloWorld.zip’. I can then unzip it to see the archived compressed files and folders that constitute the LibreOffice file itself(with e.g. Archive Manager on Linux, winzip on Windows, or Archive Utility on Mac). In the list of folders, I spot a folder called ‘Scripts’. Then, I find a sub-folder called ‘python’. OH SURPRISE! The python script is there!

If you want to do that too, when you’re done don’t forget to rename the file back with its ‘.ods’ extension.

In the second case scenario,we are saving our Python script our Python script ‘Testing.py’ is not listed in the Macro manager within the LibreOffice File, but this time I created it as part of my Library ‘MyPythonLibrary’ within another Library called ‘Tutorial’.

And this time if I edit ‘Testing’, I can see the path is not a temporary one. I can access it even when LibreOffice is closed.

In fact your Python programs can be directly accessed on your computer at the following location:
For Linux:
/home/<user name>/.config/libreoffice/4/user/Scripts/python
(to see folder ‘.config’ you need to ‘Show hidden files’ , the shortcut CTRL+h).
For Windows:
C:\Users\<user_name>\AppData\Roaming\LibreOffice\4\Scripts\python
For Mac:
(I think it’s)/Users/<user name>/Library/Application Support/LibreOffice/4/user\Scripts\python
(Please let me know in a comment if you know for sure what the folder is for Mac OS).

Time for your First LibreOffice line of code!

I know you can’t wait anymore! So let’s create our first program in Python in a LibreOffice Calc Document in this next post.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

# Created by Gweno 16/08/2019 for tutolibro.org
# This program displays 'Hello World!" in cell A1 of the 
# current Calc document.

# get the doc from the scripting context 
# which is made available to all scripts
desktop = XSCRIPTCONTEXT.getDesktop()
model = desktop.getCurrentComponent()

def HelloWorld():
    """Write 'Hello World!' in Cell A1"""

    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

    # write 'Hello World' in A1
    active_sheet.getCellRangeByName("A1").String = "Hello World!"

You can either copy this block of code above or better type it yourself. Typing the code yourself will take longer but it’s the best way to remember a new language.

The first lines starting with ‘#’ are comments.
A comment in a program is a line that is not processed when the program is executed. It helps the person reading the program to understand what the code is doing. Most of the time, this person is yourself. Comments will help you remember what you were trying to achieve with this code.

The blank space at the start of indented lines should be made of 4 spaces:
    active_sheet = model.CurrentController.ActiveSheet

If you don’t do that it will create an error because the Python interpreter will not recognise the line as being part of the function define by:
def HelloWorld():

The instruction ‘def’ is to ‘define a function’. A function is a set of written instructions. It can be run on its own. It can also be ‘called’ by other functions to be executed.
Our function here is called ‘HelloWorld’. The part between parenthesis ‘()’ is where you write the arguments to be used by the function. In our case we are not ‘passing’ any argument to the function ‘HelloWorld’ for now. That’s why we have nothing within the parenthesis ‘()’.
If you want to assign this macro to a button, you need to pass a specific argument. This argument is necessary for the macro to work when pressing the button. (see this post explains how to assign a button to a python macro)

Explanations:
Lines 1,2,3,5,6: these lines start with a ‘#’ so they are comments.
Lines 4,9,18: these empty lines are only for making the program easier to read. They serve to separate the different sets of instructions within the program. The Python interpreter does not need them but these empty lines make the code more readable for us.

Line 7:
desktop = XSCRIPTCONTEXT.getDesktop()
This line is what allows us to use Python language to manipulate LibreOffice’s components. It is a bit complicated to explain exactly what this line does. In short, we define ‘desktop’ to hold the ‘XSCRIPTCONTEXT‘ interface provided by LibreOffice for our scripts (programs). The ‘getDesktop()’ function is used to obtain a reference for our scripts to operate on. (It is not a reference to a computer desktop!). (Click on the links above to read more in my ‘bitesize’ section).

Line 8:
model = desktop.getCurrentComponent()
Here, we define ‘model’ to be the current component of ‘desktop’. Thus, we are referencing the current document open. It should be a Calc document.

Line 10:
def HelloWorld():
Define a new function called ‘HelloWorld’ that has no arguments.
The ‘:’ at the end is essential, it’s to say that what is following is the actual code written for this function. And every line that follow this function’s 1st line should start with 4 spaces.
The function finishes when there is no lines after it. Or when the next non empty line is not a comment and starts with no space.
Line 11:
“””Write ‘Hello World!’ in Cell A1″””
This line is simply a description of the function. Also called a Docstring (DocStrings is short for Documentation Strings), it starts and ends with 3 quotation marks. It is not really useful for us right now. Still, it is good practice to have a short description for each of your functions. It’s different from a comment because this description can be displayed outside of the program as a ‘help’ note.
To display docstrings, you can use the built-in function ‘help’, like illustrated in the APSO console below:

Line 14:
    active_sheet = model.CurrentController.ActiveSheet
Here we are defining ‘active_sheet’ to be the current spreadsheet you are looking at.
Line 17:
    active_sheet.getCellRangeByName("A1").String = "Hello World!"
Finally! Now we have a reference to the current LibreOffice Context. We have the current LibreOffice Calc Document (component) and the current spreadsheet. Therefore, we can access the cell ‘A1’. We can then assign to its ‘String’ parameter the text “Hello World!

Exercise:
Add to function HelloWorld a line of code to display “Bye Bye World!” in cell ‘B2’. I am sure you can handle that!

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

Here is the plan for this part 2 of the tutorial:

• Get your workflow right: deciding between your macro embedded in the file or saved in a macro repository.
• First line of code and writing “Hello World!” in Cell A1.
• Assigning the macro to a LibreOffice Control Button.

Get your workflow right (Back to top)

With the APSO add-on (see previous article) you can embed your macro within the LibreOffice File. This can be useful when you want to send your file with the Python Macro. One downside if you do that is that the Python macro is not accessible outside of the LibreOffice file. So you’ll need to open the LibreOffice file and open the Python Macro organiser in order to edit the Python program. There are alternatives to embedding the Python program. You can place it in an organized directory while still using APSO. This allows you to re-use it for any other LibreOffice document. You can also edit the program without opening the LibreOffice document if you open it from the relevant folder. If you want to send your LibreOffice Document to someone, there is a trade-off. You will also need to send the Python macro.

I am in favor of keeping my programs in a tidy manner. This approach allows me to re-use them across many different files. However, the choice is entirely up to you.

To illustrate these 2 cases, let’s have a look at an example:

I have a file called “HelloWorld.ods” and two Python files: the first one is called “HelloWorld.py” and the other file is called “Testing.py”. The first python file is embedded in the LibreOffice file, the second is in the shared Python Scripts directory.

In the first case scenario, after opening HelloWorld.ods, I can go to the Python Script Organizer, in Tools>Macro>Organize Python Scripts (shortcut Alt+Shift+F11) from the APSO extension. Alternatively I can use the LibreOffice Standard Macro Organiser in Tools>Macro>Organise Macros>Python….

In the Python Scripts Organiser you will see that your Python Macro is listed within the LibreOffice File’s name.

When you choose to edit the Python Macro, select ‘Menu>Edit’ from the ‘Python scripts’ window. The edited file’s path is temporary. It is only used for the time of editing this Python program.

So where is the Python Script saved on your hard drive?
As I wrote earlier, it’s embedded in the LibreOffice File. If you don’t believe me, here is a trick to find out:
If I rename my ‘HelloWorld.ods’ in ‘HelloWorld.zip’ I can then unzip it to see the archived compressed files and folders that constitute the LibreOffice file itself (with e.g. Archive Manager on Linux, winzip on Windows, or Archive Utility on Mac). In the list of folders I can then spot a folder called ‘Scripts’, then a sub-folder called ‘python’, and OH SURPRISE! the python script is there!

If you want to do that too, when you’re done don’t forget to rename the file back with its ‘.ods’ extension.

In the second case scenario,we are saving our Python script our Python script ‘Testing.py’ is not listed in the Macro manager within the LibreOffice File, but this time I created it as part of my Library ‘MyPythonLibrary’ within another Library called ‘Tutorial’.

And this time if I edit ‘Testing’, I can see the path is not a temporary one and I can access it even when LibreOffice is closed.

In fact your Python programs can be directly accessed on your computer at the following location:
For Linux:
/home/<user name>/.config/libreoffice/4/user/Scripts/python
(to see folder ‘.config’ you need to ‘Show hidden files’ , the shortcut CTRL+h).
For Windows:
C:\Users\<user_name>\AppData\Roaming\LibreOffice\4\Scripts\python
For Mac:
(I think it’s)/Users/<user name>/Library/Application Support/LibreOffice/4/user\Scripts\python
(Please let me know in a comment if you know for sure what the folder is for Mac OS).

First line of code! (Back to top)

I know you can’t wait anymore! So let’s write our first line of code in Python, within a LibreOffice Calc Document.

So after creating a new Calc document, go in the Macro manager (if you have installed the APSO extension: ALT+Shift+F11), then as explained earlier in this lesson you can have your program either in calc document or in a library outside the document. To do so, choose between ‘My Macros’, ‘LibreOffice Macros’ or the name of the document itself.
I do prefer saving my python macros in the ‘My Macros’ Library.
You can also create sub-folders, called libraries, or directly create your program by choosing ‘Create Module’ in the ‘Menu’.

So go ahead and create a Module, name it “HelloWorld”, then once the module is listed and selected, click again on ‘Menu’ and choose ‘edit’.

And then you get either a default editor or the one you have linked with APSO to pop up with a new program that content nothing but a couple of lines like these:

The first line is a comment.
A comment in a program is a line that is not processed when the program is executed. So it’s not a line of code, it is usually to help the person who is going to read your program (most of the time, yourself) to understand what the following code is aiming to do.
So to write comments in your Python programs simply add a ‘#’ at the start of the line.
Don’t worry about the second line, in fact you can delete these two lines for now.
Instead you could like me write your name, the date and what the program is for:

# Created by Gweno 16/08/2019 for tutolibro.tech
# This program displays 'Hello World!" in cell A1 of the
# current Calc document.

Then Finally here is the code for writing “Hello World!” in cell A1:

# Created by Gweno 16/08/2019 for tutolibro.tech
# This program displays 'Hello World!" in cell A1 of the 
# current Calc document.

def HelloWorld():
    """Write 'Hello World!' in Cell A1"""

# get the doc from the scripting context
# which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()

# access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

# write 'Hello World' in A1
    active_sheet.getCellRangeByName("A1").String = "Hello World!"

You can either copy this block of code above or better type it manually yourself. Typing the code yourself will take longer but it’s the best way to remember a new language.
When you type it make sure that you leave 4 empty spaces to indent the lines that are not starting at the beginning of their lines, like:
desktop = XSCRIPTCONTEXT.getDesktop()
If you don’t do that it will create an error because the Python interpreter will not recognise the line as part of the function define by:
def HelloWorld():
So the instruction ‘def’ is to ‘define a function’. A function is a set of written instructions that can be run on its own or ‘called’ by other functions to be executed.
Our function here is called ‘HelloWorld’ and the part between parenthesis ‘()’ is where you write the arguments to be used by the function. In our case we are not ‘passing’ any argument to the function ‘HelloWorld’ for now, that is why we have nothing within the parenthesis ‘()’.
You need to know that when we will assign our macro to a button we will need to pass a specific argument for our macro to work when we press the button.

Explanations:
Lines 1,2,3,8,9,13,16: these lines start with a ‘#’ so they are comments.
Lines 4,7,12,15,18: these empty lines are only for making the program easier to read,by separating the different set of instructions within the program. The Python interpreter does not need them but these empty lines make the code more readable for us.
Line 5:
def HelloWorld():
Define a new function called ‘HelloWorld’ that has no arguments.
The ‘:’ at the end is essential, it’s to say that what is following is the actual code written for this function. And every line that follow this function’s 1st line should start with 4 spaces.
The function finishes when either there is nothing after, or when a new line starts from the beginning with no space to start with (excluding comment lines).
Line 6:
"""Write 'Hello World!' in Cell A1"""
This line is simply a description of the function, it starts and ends with 3 quotation marks. It is not really useful for us right now but it is a good practice to have a short description for each of your function. It’s different from a comment because this description can be displayed from outside of the program as a ‘help’ note.
Line 10:
desktop = XSCRIPTCONTEXT.getDesktop()
This line is what allows us to use Python language to manipulate LibreOffice’s components. It is a bit complicated to explained exactly what this line does but in short:
We define ‘desktop’ to hold the ‘XSCRIPTCONTEXT‘ interface provided by LibreOffice for our scripts (programs). The ‘getDesktop()’ function is used to obtain a reference for our scripts to operate on. (It is not a reference to a computer desktop!). (Click on the links above to read more in my ‘bitesize’ section)
Line 11:
model = desktop.getCurrentComponent()
In the same way we define here ‘model’ to be the current component of ‘desktop’, so effectively we are referencing to the current document open, which should be a Calc document.
Line 14:
active_sheet = model.CurrentController.ActiveSheet
Here we are defining ‘active_sheet’ to be the current spreadsheet you are looking at.
Line 17:
active_sheet.getCellRangeByName("A1").String = "Hello World!"
Finally! Now that we have a reference to the current LibreOffice Context, the current LibreOffice Calc Document (component) and the current spreadsheet, we can access the cell ‘A1’ from that current spreadsheet and assign to its ‘String’ parameter the text “Hello World!”.

Exercise:
Add to function HelloWorld a line of code to display “Bye Bye World!” in cell ‘B2’. I am sure you can handle that!

Assign the macro to a LibreOffice Control Button. (Back to top)

You will quickly realise when you write a macro within libreOffice that it’s not really convenient to execute them through the Macro Manager because you need to access that menu and it takes a few clicks to do so (Quickest way to access the APSO Macro manager being [Alt] + [Shift] + [F11]). It is easy to create a button on your spreadsheet and to assign it to your macro and then when you’ll click on that button it will execute the macro.
So first we’ll create a button on the spreadsheet then we’ll assign the python macro to this button.

Create a button:
Simply by clicking on Menu ‘Insert>Form Controls>Push Button’:

Then once you have the little cross to insert the button, just click for upper left corner of the button, then hold and release where you want the bottom right corner of the button.

Assign the python macro:
Once you have the button displayed, right click on it and select ‘Control…’

Then in the window ‘Properties’ select the ‘Events’ tab, scroll down a bit to find in the list of events the one called ‘Mouse button pressed’. On the right of this ‘Mouse button pressed’ entry click on the button ‘[…]’.

A window named “Assign Action’ pops up, click on the button ‘[Macro]’ on the right hand side of this window.

You should then get the ‘Macro Selector’ with your Macro Libraries. Simply go to the library where your macro is saved and select the macro ‘HelloWorld’,then press ‘OK’.

Then ‘OK’ again in ‘Assign Macro’ window, than close the ‘Properties’ window.
Last thing to do is to come out the ‘Design’ mode to be able to click on the button, do that by going to ‘Tools>Forms>Design Mode’.

And now when you click on the button… tada…
ERROR!

This is because to be able to work, the function HelloWorld need all information from LibreOffice Context in the form of an argument. So we need to pass the argument ‘*args’ in our function HelloWorld. So in your code in line 5 instead of:
def HelloWorld():
You should have:
def HelloWorld(*args):
Save your program again and then when you press on the button the cell A1 will display ‘Hello World!’ !!!

So there is the final version of the macro:

# Created by Gweno 16/08/2019 for tutolibro.tech
# This program displays 'Hello World!" in cell A1 of the 
# current Calc document.

def HelloWorld(*args):
    """Write 'Hello World!' in Cell A1"""
    
# get the doc from the scripting context 
# which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
# access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

# write 'Hello World' in A1
    active_sheet.getCellRangeByName("A1").String = "Hello World!"

You can clone or download this code from gitHub here.

Good luck! and leave a comment if you are having problem to have this macro to work.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

edit 30/09/2021: Thanks to karolus for pointing out a few mistakes and for suggesting improvements for this tutorial.

Here is the plan for this tutorial:

• Prepare your file
• Some useful functions
• How to increment a tuple
• Try in the console
• Increment tuple step by step
• Use built-in functions ‘tuple’ and ‘reversed’ together
• Full ReverseRange.py file
• Walk through the code
• Test the code

Prepare your file

We start with creating a new folder, I named mine ‘part 9’, in the python scripts folder for LibreOffice. Depending on your OS, it will be at a specific location in your user folder. Within that location you can organise your python scripts the way you want and each folder will be seen as a module within the LibreOffice Python Script manager.
This part 9 will re-use some of the code from part 8 (also available on my gitHub repository).

I named the file for this tutorial ‘ReverseRange.py’.

Check my tutorial hello world if you need help to get started with python scripts for LibreOffice.

I usually assign a button or a keyboard shortcut to the main() program of my new python file. This is explained in tutorial Annex 1.

If you are starting from part 8 code, I am not using a context() function anymore to define the global variable needed for pyUNO, but instead I declare them at the global scope straight away. This make things easier and avoid repeating calling context in every function that need the global variables.

So this code below:

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

Is replaced by:

# set global variables for context
    
# get the doc from the scripting context 
# which is made available to all scripts
desktop = XSCRIPTCONTEXT.getDesktop()
model = desktop.getCurrentComponent()

# access the active sheet
active_sheet = model.CurrentController.ActiveSheet

Some useful functions

I also replaced the section that is calculating Cell addresses from the current Range selection, by a simpler function returning a new range with horizontal and vertical offset as arguments. These two arguments having a default value of 0.

def getSelectionAddresses(horizontalOffset = 0 , verticalOffset = 0):
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()
    return oArea.StartColumn + horizontalOffset, oArea.StartRow + verticalOffset, oArea.EndColumn + horizontalOffset, oArea.EndRow + verticalOffset

This function returns a tuple(a list you cannot change, also called immutable, see further for more details) with 4 elements. You can indeed create a tuple without using parenthesis.
If you are not convinced, try this in a python console:

>>> fruits = "oranges","bananas","apples"
>>> fruits
('oranges', 'bananas', 'apples')
>>> type(fruits)
<class 'tuple'>

(Don’t type the ‘>>>’, it’s python key prompt!)

The python built-in method type() tells you that you have defined the object ‘fruits‘ as an instance of class ‘tuple‘.

How to increment a tuple

A tuple in python is a special type of array of data to store any type of data. Once a tuple has been created you cannot change its elements individually. A common solution to build a tuple is to use a ‘for loop‘ and to recreate the entire tuple with the same name at each loop iteration. It will look exactly like incrementing a variable, with each loop’s iteration looking like this:

myTuple = myTuple + (newElement,)

The comma at the end within the parenthesis is important, if you don’t have it, the (newElement) is not a tuple but just a single element of whatever the type of newElement is.

Try in the console

So let’s open an APSO console (see part 1 if you need help), or if any other python console like the Python Idle, or even your terminal after starting python3.

Then in the python console of your choice just create two new tuples like this:

source = (1,2,3)
target = ()

You can do a quick print of your two tuple if you want to make sure your 2 tuples are good:

>>> source
(1, 2, 3)
>>> target = ()
>>> ()
()
>>> type(target)
<class 'tuple'>

Note: as you can see you can create an empty tuple simply with empty parenthesis.

Increment tuple step by step

To have our ‘target‘ tuple elements in the exact reverse order than the elements from the ‘source‘ tuple we need to do the following steps:

1. define target tuple equal to target tuple (which is empty at this step) + last element of source tuple (3)
2. define target tuple equal to target tuple(as it is) + second last element of source tuple (2)
3. define target tuple equal to target tuple(as it is) + first element of source tuple (1)

In the console, it looks like this:

>>> target = target + (source[-1],)
>>> target
(3,)
>>> target = target + (source[-2],)
>>> target
(3, 2)
>>> target = target + (source[-3],)
>>> target
(3, 2, 1)

Use the reversed() function

Using a for loop and the reversed() function, we can now define a new function that takes a a tuple as argument and returns the reversed tuple, I called mine reverseTuple():

def reverseTuple(aTuple):
    oReversedSource = ()
    for t in reversed(aTuple): 
        oReversedSource = oReversedSource + (t,)
    return oReversedSource

Use built-in functions ‘tuple()’ and ‘reversed()’ together.

A nicer and more ‘pythonic’ way of doing it, is to use the function tuple() and building the elements using what is called ‘tuple comprehension’ with a loop on the reversed source tuple. This is done in one line only. So in the console it would look like this:

>>> source = (1,2,3)
>>> target = tuple(reversed(source))
>>> target
(3, 2, 1)
>>> 

So let’s create a reverse function. Now we have two functions doing the same job, just to show you that most of the time there are many ways to do the same thing in python and in programming in general. What counts is how readable the code is for you and other people that will read your code.

def reverse(aTuple):
    return tuple(reversed(aTuple))

Note that you could do without this function and use the tuple comprehension directly where you need to reverse your tuple.

For our final code we’ll keep the reverse function instead of the ReverseTuple, it’ll make people reading your code thinking, “That person knows python!”.

Now that we know how to reverse a tuple with python, we can apply it to a selected range of data within LibreOffice Calc.

Full ReverseRange.py file

# Created by Gwenole Capp 05/05/2021
# For tutolibro.tech
# Public Domain, feel free to copy, modify, use in your own scripts
# 
# email: gwenole.capp@gmail.com
   
# set global variables for context
    
# get the doc from the scripting context 
# which is made available to all scripts
desktop = XSCRIPTCONTEXT.getDesktop()
model = desktop.getCurrentComponent()

# access the active sheet
active_sheet = model.CurrentController.ActiveSheet

# define useful functions

def getSelectionAddresses(horizontalOffset = 0 , verticalOffset = 0):
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()
    return oArea.StartColumn + horizontalOffset, oArea.StartRow + verticalOffset, oArea.EndColumn + horizontalOffset, oArea.EndRow + verticalOffset
    
def reverse(aTuple):
    return tuple(reversed(aTuple))

# main function
def main():
       
    # get the Cell Range
    # use tuple unpacking of getSelectionAddresses returned tuple as parameter of getCellRangeByPosition
    oRangeSource = active_sheet.getCellRangeByPosition(*getSelectionAddresses())
    
    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()
    
    # print to console
    print(oDataSource)
    
    # create a new range of cells
    # from current selection using function getSelectionAddresses with offset
    # you can use the kwarg (keyword argument) horizontalOffset in parameter
    oRangeTarget = active_sheet.getCellRangeByPosition(*getSelectionAddresses(horizontalOffset = 3))
    
    # Reverse the data 
    oReversedSource = reverse(oDataSource)
    # Then set data for the target range using the 'reversed' data from the source range.
    oRangeTarget.setDataArray(oReversedSource)

Walk through the code

The global variables at the start are what allow us to manipulate LibreOffice Objects like the spreadsheet and its cells.
Then the function getSelectionAddresses(), as we have seen earlier is to get the addresses of the selected cells on LibreOffice.
The function reverse() is returning a reversed version of a tuple.

Let’s focus on the main() function.
In the main function, The function getCellRangeByPosition() to get the cells coordinates of the range of cells, takes 4 arguments, and not a tuple with 4 elements. But our function getSelectionAddresses() returns a tuple of 4 elements. So that is why the argument getSelectionAddresses() is preceded with a ‘*’ (asterisk). This mean that we are ‘unpacking‘ the tuple returned by the function getSelectionAddresses() into a sequence of for single elements.
When you create a tuple, you are ‘packing’ it with elements. You can ‘unpack’ it to access all its elements at once. And the asterisk can do it for you!

    # get the Cell Range
    # use tuple unpacking of getSelectionAddresses returned tuple as parameter of getCellRangeByPosition
    oRangeSource = active_sheet.getCellRangeByPosition(*getSelectionAddresses())

Then we are using getDataArray() to get the data within the selected range, we are printing the tuple to the console.

    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()
    
    # print to console
    print(oDataSource)

Next, we create a new range of cells, using again the ‘unpacked’ version of getSelectionAddresses() preceded with an asterix, but this time with the argument ‘horizontalOffset = 3‘, we don’t need to specify the verticalOffset if we want to use its default vaue set to 0 in the function definition. But we have to use the kwarg (the keyword argument) horizontalOffset to make sure we are passing the wanted value to the correct argument.
So in this case I have an offset of 3 cells horizontally, the reversed range of data will be displayed 3 cells on the right of the selected data.
If you wanted to reverse the range ‘in place’ and overwrite the source data, you just need to put no arguments in the code for function getSelectionAddresses().

    # create a new range of cells
    # from current selection using function getSelectionAddresses with offset
    # you can use the kwarg (keyword argument) horizontalOffset in parameter
    oRangeTarget = active_sheet.getCellRangeByPosition(*getSelectionAddresses(horizontalOffset = 3))

Note: there is no exception handling, no safeguard, to check if the offset your enter makes the range being 'out of range'. That could be a further improvement of this program. Another improvement could be to have the offset defined in a cell, or defined using a small control form with a text input.

Finally, we reverse the tuple of data and store it in our new range of Cell addresses in the LibreOffice Calc sheet.

    # Reverse the data 
    oReversedSource = reverse(oDataSource)
    # Then set data for the target range using the 'reversed' data from the source range.
    oRangeTarget.setDataArray(oReversedSource)

You can also find the file with the full code on this gitHub rep.

Test the code

Now it’s time to create a range of data, select that rage and run the python macro!

You can a look at tutorial Annex 1 to map a combination of key to this macro (I use CTRL + 0).
I hope this tutorial helped you understand a bit more about using python to control LibreOffice Calc. Please leave a comment to let me know!

Here is the plan for this tutorial:

• Start with code from the previous chapter
• Set the top-left and bottom-right Cells addresses
• Set the Target Range
• Create a new Array of data

Start with code from the previous chapter

Starting with the code from the previous episode of this series LibreOffice Calc & Python Programming from its corresponding gitHub rep, or a copy paste here:

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet
    
def main():
    
    # call function context()
    context()
    
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()

    # store the attribute of CellRangeAddress 
    nLeft = oArea.StartColumn
    nTop = oArea.StartRow
    nRight = oArea.EndColumn
    nBottom = oArea.EndRow
    #(note: could the attribute directly instead of using intermediary variable)
    
    # get the Cell Range 
    oRangeSource = active_sheet.getCellRangeByPosition(nLeft, nTop, nRight, nBottom)
    
    # example by name:
    # ~ oRangeSource = active_sheet.getCellRangeByName('A1:C10')
    
    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()
    
    # print to console
    print(oDataSource)

Set the top-left and bottom-right Cells addresses

This step is to calculate the addresses for our target range of cells, by defining the columns and rows for the top-left and bottom-right cells or our target range, the range where we are going to transfer the data from the selected area.
To avoid having python to throw an error, we need to make sure that our target area is exactly the same size than our source area.
We also don’t want to overlap our source area with our target area.
In this example, let’s define an area starting two columns to the right of our selected area. So the addresses of the cells in the new range will depend on the addresses of cells within the source range.
We can set an offset value that will define how many columns to the right of our selected range will our target range will be.

For example:
offset = 2

Then we set the leftmost column of our new range to be like this:
tLeft = nRight + offset
With nRight being the right column of our range of selected cells.
So here we are simply adding the offset (=2) to the end column of the source range.

Then we need to know the number of columns in the source area:
nbCol = nRight – nLeft + 1
This is the difference between the address of the right column of the source area and the address of the left column area, to which we add 1.
Check the illustration below to understand:

To remember that logic I always use a metaphor about number of holidays: if I start my holidays the 2nd of the month and my last day of holidays is the 4th of the month, I know I had 3 days of holidays, the 2nd, the 3rd and the 4th. And first day subtracted to last day makes 4 -2 = 2 , and I need to add 1 day to have the right count: 3 days from the 2nd to the 4th.
In the illustration above, the column 2 is the day 2 of the month, the column 4, the day 4…

To set the address of the last column of our target range we do the following:
tRight = nRight + nbCol – 1 + offset
Starting from the last column of the source area, you add the number of columns in that source area, subtract 1, and then add the same offset that you used for the starting column of this new range.
To use the same number of holidays example, to know what are the starting date and ending date of my holidays knowing that I have 3 days off next week, I need to add the number of days off to the starting date and take away 1: 2+3=5, 5-1 = 4 -> the 4th.

We can keep the same rows than the source area for the target area:
tTop = nTop
tBottom = nBottom

Altogether the snippet for setting the columns and rows of our new range is:

    # set the target columns and rows
    # relative to the selected area
    offset = 2
    tLeft = nRight + offset
    nbCol = nRight - nLeft + 1
    tRight = nRight + nbCol - 1 + offset
    tTop = nTop
    tBottom = nBottom

    print(tLeft,tTop,tRight,tBottom)

A simplified version, of tRight, if you replace nbCol by its value, would be:
tRight = 2*nRight – nLeft + offset
In which case you don’t need the nbCol variable anymore, but to make the explanation easier I am keeping it.

As usual, to help with testing, I added a print statement. It will print the value you calculated in the console. You can read my tutorial about the APSO console if you haven’t yet. Also to make testing easier, I usually assign the program to a combination of key, like CTRL + 0. Check my post that explains how to do that easily.

Set the Target range

We are going to use getCellRangeByPosition again to create a range of cells, but this time we are not going to use the addresses of the area defined by the mouse selection. We are now going to use the variables that we created in the previous step tLeft, tTop, tRight, tBottom.

    # create target Range
    oRangeTarget = active_sheet.getCellRangeByPosition(tLeft, tTop, tRight, tBottom)

Now that we have define a cell range, we can assign data to it.

Create a new Array of data

In the last tutorial we used the function getDataArray() to create a python tuple that we named oDataSource from the data stored in the source range of cells. This time we are going to use the function setDataArray() with the existing tuple of data oDataSource as parameter.

This will store the data from the tuple oDataSource to the target Range of Cells that we defined earlier, and hopefully display the data in the cells on the LibreOffice current spreadsheet.

    # set data for the target range using datafrom the source range.
    oRangeTarget.setDataArray(oDataSource)

Here is what I get with a bit of data, including the APSO console:

This is the full code:

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet
    
def main():
    
    # call function context()
    context()
    
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()

    # store the attribute of CellRangeAddress 
    nLeft = oArea.StartColumn
    nTop = oArea.StartRow
    nRight = oArea.EndColumn
    nBottom = oArea.EndRow
    #(note: could the attribute directly instead of using intermediary variable)
    
    # get the Cell Range 
    oRangeSource = active_sheet.getCellRangeByPosition(nLeft, nTop, nRight, nBottom)
    
    # example by name:
    # ~ oRangeSource = active_sheet.getCellRangeByName('A1:C10')
    
    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()
    
    # print to console
    print(oDataSource)
    
    # set the target columns and rows
    # relative to the selected area
    offset = 2
    tLeft = nRight + offset
    nbCol = nRight - nLeft + 1
    tRight = nRight + nbCol - 1 + offset
    tTop = nTop
    tBottom = nBottom
    
    print(tLeft,tTop,tRight,tBottom)
    
    # create target Range
    oRangeTarget = active_sheet.getCellRangeByPosition(tLeft, tTop, tRight, tBottom)
    
    # set data for the target range using data from the source range.
    oRangeTarget.setDataArray(oDataSource)

You can also find this code on this gitHub rep.

The getDataArray() function creates a tuple of tuples. Tuples are immutable objects, so you cannot change them once you have created them.
So if you want to change the data that you stored from a range of cells, you will need to create a new tuple, while looping on the source tuple element by element.
In the next episode of this series of Tutorials about LibreOffice Calc and Python Programming, I will show you some examples on how to work with these tuples of tuples to work on the data.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

How are we going to do it?

We are going to get the coordinates of a range of selected cells in an open Calc document and store all the data that the range of cells contains into an Tuple.

But first, what is an Tuple?

A Tuple in Python is like an Array of data but that can store data with different types.
But what is an Array?
An array in computer programming is a container that stores data in consecutive memory addresses. It is widely used in many programming languages.
In Python an Array is used to store many variables with the same type of data (string, integer, float, etc…) which is not convenient for storing data coming from a Spreadsheet’s cells.
That is where the Tuple is convenient as it can store data of different types (see the 4 possible types in my previous episode of this series).
Note that a Tuple in Python is ‘immutable’, it means that we cannot change its content once it has been defined. It is important to know and I’ll show you how to work with tuples easily.
So let’s get Started.

Here is the plan for this tutorial:

• Set the context for global variables
• Get the Range of Addresses
• Get the data from a range of Cells by Position
• Get the data from a range of Cells by Name
• Store Cells content in an Tuple of Data

Set the context for global variables

Note: you can start from the same script as the previous tutorial (part 6 - Cells Types ).

Starting with our usual context() function that stores desktop , model and active_sheet at a global scope:

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

Get the Range of Addresses

In our main function we start by calling context(), then we need to get the Addresses of the cells .

def main():
    
    # call function context()
    context()
    
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()

The method getRangeAddress() returns a CellRangeAddress.
A CellRangeAddress is a Struct (short for Structure). It has the following Attributes:

Sheet, StartColumn, StartRow, EndRow, EndColumn.

We don’t really need the Sheet index yet as we are only working on the current sheet. But we need the 4 other attributes. They correspond to the top-left and bottom-right cells of what we have selected with the mouse.

I strongly advise you to check XCellRangeAddress and explore the LibreOffice API. It is actually a really good way to discover the different methods and attributes that you can use.

The next step is to get all necessary cell references to retrieve data from a Range of Cells. We can do that now that we have our oArea object variable.

    # store the attribute of CellRandeAddress 
    nLeft = oArea.StartColumn
    nTop = oArea.StartRow
    nRight = oArea.EndColumn
    nBottom = oArea.EndRow
    #(note: could the attribute directly instead of using intermediary variable)

Note that although we could use the oArea attributes, storing them in variables with relevant names makes the program/script more readable.

Get the data from a range of Cells by Position

Now we can call function getCellRangeByPosition to returns a ‘sub-range’ of the active sheet. Understand that the active sheet itself is a range of cells that is much bigger.
That ‘sub-range’ is the range of Selected Cells from where we are going to extract data. I am calling that range oRangeSource.

    # get data from the source
    oRangeSource = active_sheet.getCellRangeByPosition(nLeft, nTop, nRight, nBottom)

Here is an example of a selected range of cells in LibreOffice:

Get the data from a range of Cells by Name

In this tutorial we are using variables to get the Range of Cells. We could also use arbitrary values corresponding to the Top-left and Bottom-Right cells of the range like:

oRangeSource = active_sheet.getCellRangeByPosition(0, 0, 2, 9)

That set of parameters (0, 0, 2, 9) means that we are getting the range from cell(0,0) to cell(2,9).
In some cases it is easier to refer the cells by name. With names instead of positions the range (0,0,2,9) would be from cell “A1” to cell “C10”.

If you work with a range of cells by name it is then much easier to use the dedicated function getCellRangeByName:

    # example by name:
    oRangeSource = active_sheet.getCellRangeByName('A1:C10')

You would define the range of cells the same way you do it in formulas: ‘A1:C10‘.

Using range by position is much easier in programs where the ranges are not always the same and can be dynamically changed. It makes it much more flexible to work with, especially if you need to run loops on the cells.

Store Cells content in an Tuple of Data

This is a key operation.
The function getDataArray extracts the content of the cells within a range and stores that content in a tuple. And from there we will be able to use that content easily with Python. Here is the simple line of code needed to do that:

    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()

Note: A print statement here would be helpful to check how the tuple of data looks like. To get the APSO console check part 4  of this series of tutorials).

    # print to console
    print(oRangeSource)

Here is an example of what you would get:

The Tuple produced is actually a tuple of tuples:

((1.0, ‘C’), (2.0, ‘D’), (‘A’, 3.0), (‘B’, 4.0))

As you can see each tuple inside the big tuple stores a row of data.
If you look closer, for example if you look at the tuple for the first row:

(1.0,’C’)

You will see that the 1.0 has no quote where the ‘C’ has quotes. This means that the types of the data within the cells have been preserved.
A number in LibreOffice remains a number in Python, and string remains a string. In fact the function getDataArray() returns a tuple of tuples with data of a type Double or String. Double is a type for any decimal numbers.

Now here is the full code for this tutorial:

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet
    
def main():
    
    # call function context()
    context()
    
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()

    # store the attribute of CellRangeAddress 
    nLeft = oArea.StartColumn
    nTop = oArea.StartRow
    nRight = oArea.EndColumn
    nBottom = oArea.EndRow
    #(note: could the attribute directly instead of using intermediary variable)
    
    # get the Cell Range 
    oRangeSource = active_sheet.getCellRangeByPosition(nLeft, nTop, nRight, nBottom)
    
    # example by name:
    # ~ oRangeSource = active_sheet.getCellRangeByName('A1:C10')
    
    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()
    
    # print to console
    print(oDataSource)

On gitHub: https://github.com/Gweno/tutolibro.tech/tree/master/lopy/part7

To make it easier to test my scripts I usually assign them to a combination of keys like CTRL + 0. Learn how to do it on this post.

In the next tutorials we will actually do something with the tuple created here and then play a little bit the data inside.

Please leave a comment to let me know what you think about this tutorial 
or if you had any issues going through it. Getting your comments helps 
me a lot to make the next tutorials better! Thank you!

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

A cell within a LibreOffice Table has no predefined type. Its type comes from its content and can only be one of the 4 following types:

• empty
• value
• string
• formula

These types names are quite self-explanatory:

• empty is simply the type of an empty LibreOffice Calc cell.
• value is the type of any numerical content of a LibreOffice Calc cell.
• string is the type of any text content of a LibreOffice Calc cell.
• formula is the type of any LibreOffice Calc cell that contain a formula.

Note:
Dates, currencies, decimals, booleans within LibreOffice are not types but different formats of numbers. We’ll see how to manage them in a later post.

A good way to illustrate the 4 different cell types is to play with them with a simple python code that will display in the console the type of cell selected in LibreOffice Calc.
Please refer to my previous tutorials for creating a program and using the APSO console.

First you need to define the variables provided by XSCRIPTCONTEXT. This XSCRIPTCONTEXT is a UNO object that gather all you need to manipulate LibreOffice Documents with Python scripts.

You can either define these variables at the global level of your program or like I like to do, in a separate function that I call context() to make it more customizable in later programs.

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

In this ‘context()’ method, we first declare the 3 useful variables that will hold our objects as Global Variables. This will allow us to access these objects from other functions, like out main() function. These objects were briefly explained in part 2 of these series of tutorials.

Next we can create our main function:

• call (execute) function context
• get the selected range
• get coordinates of the selected cell
• get the Type of the selected cell
• print in the console and in a cell (optional)

But first, to make testing easier I advise to bind our main() function to a combination of keys on your keyboard. Check out my Annex1 to learn how to do it quickly.

Call context

This is the easiest part, simply:

    # call function context()
    context()

Get the selected range

To do that we use the method getCurrentSelection() of the object ‘model’ that we defined in the context() method further up.
That object ‘model’ is an interface for the ‘Desktop’ environment that we defined in context().
For now we should focus on the end point, the cells themselves. I will write a tutorial to explain how about the Desktop, Interface, Frames and other types of components imported from the UNO library that pyUno is based on.
Once we have an object that contains the selection, we can use the method getRangeAddress() to get useful attribues of this object that we will need to access the value of the cell we want and then the type of that value:

    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()

Get the coordinates of the selected cell

The object ‘oArea’ is a range of Cell Addresses and has 5 attributes:

• Sheet: the sheet number in the collection of sheets in the Calc document, starting at 0 for the first sheet.
• StartColumn: the index of the first column of the range of cells, starting at 0.
• StartRow: the index of the first Row of the range of cells, starting at 0.
• EndColumn: the index of the last column of the range of cells.
• EndRow: the index of the last row of the range of cells.

In our case we are only interested in the first cell of the selection. Whether we have selected one cell or more we are only going to use the attributes StartColumn and StartRow. Using these 2 values will then let us access the cell using the getCellByPosition() method:

    # get the first cell
    firstRow = oArea.StartRow
    firstCol = oArea.StartColumn
    selectedCell = active_sheet.getCellByPosition(firstCol,firstRow)

Get the Type of the selected cell

Now we have in hand the cell we want, we can check its attribute Type directly with selectedCell.Type.
However this would give us a detailed description of that attribute, a bit too detailed like that:
<Enum instance com.sun.star.table.CellContentType(‘TEXT’)>
This tells us that the attribute Type is in fact a python object of type Enum.
And to get the value of an object of type Enum we simply need to add .value like this:
selectedCell.Type.value
So our code for this part is:

    # get the type of the cell
    cellType = selectedCell.Type.value

Print in the console and in a cell (optional)

To get the console I strongly advice to use the APSO add-on which is so good, so free and just essential to make your life easier wen using Python scripts with LibreOffice, check part 4 of these LibreOffice/Python tutorials to get APSO and to install it. Then you can use the Python print() function to display the type of our cell in the Console.
When working on a Python scrip sometime it’s easier to display directly in a cell, just use the the method getCellByPosition() to set the value of a wanted cell, for example the next cell on the same row as our selected cell.
Note that we don’t need to convert cellType to a string because the value of the Enum Type is a string.

    # print in console
    print("Cell (",firstCol,",",firstRow,") Type:", cellType)
    
    # display in next cell
    active_sheet.getCellByPosition(firstCol+1,firstRow).String = "Cell Type:" + cellType

Full script for main()

def main():
    
    # call function context()
    context()
    
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()
        
    # get the first cell
    firstRow = oArea.StartRow
    firstCol = oArea.StartColumn
    selectedCell = active_sheet.getCellByPosition(firstCol,firstRow)
    
    # get the type of the cell
    cellType = selectedCell.Type.value
    
    # print in console
    print("Cell (",firstCol,",",firstRow,") Type:", cellType)
    
    # display in next cell
    active_sheet.getCellByPosition(firstCol+1,firstRow).String = "Cell Type:" + cellType

Full script with both functions:

# Created by Gwenole Capp 18/06/2020
# For tutolibro.tech
# Public Domain, feel free to copy, modify, use in your own scripts
# 
# email: gwenole.capp@gmail.com

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet
    
def main():
    
    # call function context()
    context()
    
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()
        
    # get the first cell
    firstRow = oArea.StartRow
    firstCol = oArea.StartColumn
    selectedCell = active_sheet.getCellByPosition(firstCol,firstRow)
    
    # get the type of the cell
    cellType = selectedCell.Type.value
    
    # print in console
    print("Cell (",firstCol,",",firstRow,") Type:", cellType)
    
    # display in next cell
    active_sheet.getCellByPosition(firstCol+1,firstRow).String = "Cell Type:" + cellType

On gitHub:

Download or clone from this folder on my gitHub repository.

If you are not familiar with git and gitHub you check this post I wrote as Annex to these series of tutorials.

Leave a comment

Please leave a comment to tell me what you think of this tutorial or if you have any question.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

Here is the plan for this Annex 0 of the tutorial:

• Write a simple python program.
• Save the script at the right place.
• Assign your scrip to [CTRL]+0.

Write a simple python program.

Let’s make a quick python program that writes numbers from 1 to 10 in 10 consecutive cells in column B of any LibreOffice Calc Spreadsheet (yes a lot like in this tutorial!).

# get the doc from the scripting context 
# which is made available to all scripts
desktop = XSCRIPTCONTEXT.getDesktop()
model = desktop.getCurrentComponent()

# access the active sheet
active_sheet = model.CurrentController.ActiveSheet

def write_1_to_10(*args):
    """Write 1,2...10 in Column B"""
    for each_number in range(10):
        active_sheet.getCellByPosition(1,each_number).Value = each_number + 1

In this simple example we don’t use a main() program to call our function ‘write_1_to_10, so the function needs to have the *args (pointer to arguments) for passing information from the LibreOffice environment to Python.

Save the script at the right place.

I have named my file Annex1.py to make it easier for you to match it with this lesson on my gitHub repository dedicated to LibreOffice Tutorials.

Now that you have written your program, to have it available in LibreOffice you have to save it in the correct folder.
For Linux:
/home/<user name>/.config/libreoffice/4/user/Scripts/python
(to see folder ‘.config’ you need to ‘Show hidden files’ , the shortcut CTRL+h).
For Windows:
C:\Users\<user_name>\AppData\Roaming\LibreOffice\4\Scripts\python
For Mac:
(I think it’s)/Users/<user name>/Library/Application Support/LibreOffice/4/user\Scripts\python
(Please let me know in a comment if you know for sure what the folder is for Mac OS).

Open a new LibreOffice Calc document if you haven’t doe it yet, to check that you can run your script. And also to debug it if needed…
The best is to use the APSO Add-on (how to install it here).
So if everything is ok you should find your script listed by looking in either:
Tool/Macros/Organize Macros/Python
or
Tool/Macros/Organize Python Scripts

Showing here the APSO organizer (the built-in LibreOffice one is self explanatory as well…):

(Check-out my helloworld tutorial if you need more details on how and where to save your python script)

Try to execute your program by selecting it from the APSO organizer and click on the execute button, or from the LibreOffice organizer on the ‘Run’ Button.
If everything goes write the program should write numbers 1 to 10 in column B. If not you have to debug it… or leave me a comment if you have any problem.

Assign your scrip to [CTRL]+0.

If like me you feel that executing a python script within LibreOffice as showing previously requires too many mouse clicks you will appreciate a much quicker way to run your pythonic creations.
And to debug more easily your programs on the go, it is much easier also.

To assign a key or a combination of keys to a python script (or to a LibreOffice Basic Macro as well) go directly in the menu Tools/Customize’

or right click anywhere on the toolbar (not the top menu bar) and nearly at the bottom of the contextual menu select ‘Customize Toolbar’:

The next steps are:

1. Select the tab ‘Keyboard’ .
2. In the ‘Category’ section, find and select your python module and file (in the example MyPythonLibrary/Annex1).
3. In the ‘Function’ section select the function within the file (in the example there is only one file: write_1_to_10).
4. In the ‘Shortcut Keys’ section select the key or combination of keys from the list, better choose one that has nothing assigned to it already (in the example Ctrl+0 : so the combination of keys ‘Ctrl’ + ‘0’).
5. Click on the ‘Modify’ button.
6. You should see the chosen keys now in the ‘Keys’ section.
7. You should see the function’s name assigned to the Keys combination entry in the ‘Shortcut Keys’ section.
8. Click ‘OK’.

And after emptying the cells in column B, just give a try of Ctrl+0, it should filled them again!

When I am testing python code, I sometimes keep that Ctrl+0 combination assigned to a function ‘test(*args)’, when I am happy with the function I copy/rename it to a better named one, then use the test function to code something else. You can also assign useful functions that you have built and that you use often for example to format cells in a particular way.

I hope you find this useful, please leave any comments to help me making this tutorial better.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!