Jump to content

Macros/ScriptForge

From The Document Foundation Wiki


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:

  1. Propose the same comprehensive set of services to Basic and Python users (except where the language provides them natively).
  2. Unify the user interfaces for exceptions, user interactions, and debugging.
  3. Hides the complexity of UNO.
  4. Provide quick access to UNO.
  5. 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?».


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

  1. Is SF an object-oriented framework?
  2. How to load the ScriptForge library
  3. How to debug the code
  4. How to use the ScriptForge console
  5. Advanced Python setups (using pip vs. using the system Python)

Learn by project

  1. How to retrieve data from PDF forms into a Calc spreadsheet
  2. How to set up an automated workflow to retrieve data from CSV files and process it in Calc
  3. How to display a chart in a dialog
  4. (Advanced example) How to create a clone of BASIC macro organizer
  5. 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

Dialogs, Menus, and Forms

Complex Dialogs

Text

Calc, Charts, and Databases

Extensions

  • BASIC: arrays, strings, and dictionaries
  • Python: The Basic service

List of presentations about ScriptForge


List of references

  1. 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.
  2. https://extensions.libreoffice.org/en/extensions/show/apso-alternative-script-organizer-for-python
  3. https://gitlab.com/LibreOfficiant/ide_utils
  4. 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
  5. 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
  6. https://help.libreoffice.org/latest/en-US/text/sbasic/guide/basic_2_python.html?DbPAR=BASIC