Macros/ScriptForge
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
ScriptForge (SF) is a library to help you write macros easily. Extensive documentation is available on the online ScriptForge Help pages.
The ScriptForge library is an intermediary framework that achieves several goals:
- Propose the same comprehensive set of services to Basic and Python users (except where the language provides them natively).
- Unify the user interfaces for exceptions, user interactions, and debugging.
- Hides the complexity of UNO.
- Provide quick access to UNO.
- Apply best practices from similar APIs.
Introduction
Does ScriptForge prevent anyone from coding in Python? On the contrary! It is there to prevent users from reinventing the wheel every time.
ScriptForge is an object-oriented API —a collection of routines that are repeatedly used and needed in common office automation applications. CODE ONCE, RUN EVERYWHERE.
- The ScriptForge API is common to Basic and Python.
- It complements UNO and coexists smoothly with it.
- It aims to extend the audience for self-made scripts from IT professionals (with a thorough knowledge of UNO) to end users.
Instead of dealing with the LibreOffice API reference UNO[1] of over 20,000 entries —a complex object model with much abstraction— you can avoid many of these complexities by using ScriptForge.
A service is a term from Java that generally refers to a collection of procedures and functions related to a broader task. ScriptForge implements services to provide easy access to LibreOffice functionalities. Obviously, not all LibreOffice functionalities are covered. For example, if a range in Calc only needs a black frame around the header row of a table, ScriptForge is your friend — one line of code is enough. But if you need a colored dotted line of non-standard width, then you'll have to dig into UNO.
It's important to note that CreateUnoService()
can coexist smoothly in the same script or macro with CreateScriptService()
.
For users who want to go deeper, ScriptForge also provides several shortcuts to simplify working with UNO objects. For example, the SF calc.XCellRange(range)
method returns a com.sun.star.Table.XCellRange
UNO object. You can read more in the presentation titled «Is ScriptForge Really A Scam?».
-
Services and their relationships, according to ScriptForge release for LibreOffice 25.2
ScriptForge provides functionalities for both BASIC and Python. In both languages, each interface has the same syntax and behavior. In addition, Python macros can invoke built-in Basic functions — a particularly useful feature in the LibreOffice context.
ScriptForge supplies the execution context for pPatform, FileSystem, and Region (i.e. locale) functionalities. [MORE EXPLANATION]
ScriptForge supports complex debugging contexts in both BASIC and Python. [MORE EXPLANATIONS]
One of the best niceties of ScriptForge is the simplification for handling Calc ranges. Since many methods and functions in SF use a string to indicate a range as input parameter —or return a range as a string— the framework makes it easier to manage ranges of unknown, variable, or unpredictable sizes. More can be found in the presentation titled «Is ScriptForge Really A Scam?» Presentation.
Configure your external editor
It is easy to edit and debug BASIC macros in LibreOffice. The built-in IDE is not the world champion, but it is fair enough.
Direct editing and testing of Python macros inside LibreOffice (using the Python executable that comes with LibreOffice) requires solely the APSO[2] extension, in which case a Python IDE is not needed.
However, it is a pain to edit and debug Python scripts for medium size projects in LibreOffice. For Python cracks, better IDEs (like PyCharm, and VSCode) are available, but are difficult to configure.[3]
- The APSO "terminal" or "shell" is intended only for Python, and is an alternative entry point to edit a script and run it line by line. - MRI extension and XRay extension (2 flavors doing the same thing) are useful for both languages to examine UNO objects.
External editors are most useful when your scripts do not use the same Python executable as LibreOffice[4].
Now, the script can be written/run using the APSO extension (via APSO menu or via APSO terminal or console[5]), or an external editor can be used.
In the latter case, scripts must be stored in a directory that LibreOffice can access. See Python Scripts Organization and Location for more information.
Learning ScriptForge
Useful questions
- Is SF an object-oriented framework?
- How to load the ScriptForge library
- How to debug the code
- How to use the ScriptForge console
- Advanced Python setups (using pip vs. using the system Python)
Learn by project
- How to retrieve data from PDF forms into a Calc spreadsheet
- How to set up an automated workflow to retrieve data from CSV files and process it in Calc
- How to display a chart in a dialog
- (Advanced example) How to create a clone of BASIC macro organizer
- How to create a custom Calc function: It is easy in BASIC; and a bit more tricky in Python because you must write a Basic wrapper that calls the Python routine[6] and gets the resulting value. In addition, ScriptForge is seldom useful in this context, except to call the Python routine.
Full examples and small snippets (quick wins)
Through a series of well-written, non-trivial examples, we aim to inspire you to develop better applications using LibreOffice technology.
We’ve also collected many short snippets, or quick wins, for easy insertion of powerful functions into user code.
Debugging, Verifying the system
- How to handle errors occurring in events
- How to verify if XRay extension is already installed (or any other extension)
- How to use the console (terminal)
- How to verify where is LibO folder installed
- How to verify what locale is the user using
- How to verify what is the current list of days, in letters for the current locale
- How to verify what is the current list of printers
- How to journalize updates inside a document (retrieve the updates log)
- How to unit testing a BASIC development
- Document properties as dictionary
- Custom properties as dictionary
Dialogs, Menus, and Forms
- How to display data in a Tree control (the easy way)
- How to display data in a tree control (the less easy way)
- How to make a list extractor
- How to use a tabbed interface in a dialog
- How to manage a multi-pages dialog
- How to wait for user input in a spreadsheet cell
- How to validate the user's input
- How to run an input box (Python-only)
- How to (re)define PDF export options
- How to apply a (menu) command to a document
Complex Dialogs
- Building compound tabbed dialogs - Basic Macro Organizer example clone
Text
Calc, Charts, and Databases
- How to simulate a Calc context menu with a popup menu
- How to make a custom context menu in a Calc sheet
- How to make a universal clock
- How to format selective portions of a Calc range
- How to identify the selected cell in a database query
- How to sort an array
- How to display a chart in a dialog
- How to derive new cell ranges from a Calc range
- How to pilot a snake in a spreadsheet
Extensions
- BASIC: arrays, strings, and dictionaries
- Python: The Basic service
List of presentations about ScriptForge
List of references
- ↑ Here are some books you can read in order to understand the complexities of API UNO:
- (Pitonyak) Macros explained, 672 p.
- (Marcelly/Godard) Macros OOoBASIC et API [French], 926 p.
- (Bain) OpenOffice.org Spreadsheet Macros Programming, 216 p.
- (Baeza) Aprendiendo OOo BASIC [Spanish], 584 p.
- ↑ https://extensions.libreoffice.org/en/extensions/show/apso-alternative-script-organizer-for-python
- ↑ https://gitlab.com/LibreOfficiant/ide_utils
- ↑ https://www.libreoffice.org/assets/libocon2020/Slides/oSLO-2020.IDE-utils.pdf | «Python Scripts made simple w/ IDE_utils»: Presentation given by Alain Romedenne during the Oslo 2020 LibreOffice Conference
- ↑ The system terminal can be used, of course. But for LibreOffice and the script to run in the same process, the Python console must be run from the same directory where the LibreOffice executable was installed. See Creating Python Scripts with ScriptForge
- ↑ https://help.libreoffice.org/latest/en-US/text/sbasic/guide/basic_2_python.html?DbPAR=BASIC