LibreOffice Basic and the UNO API Explained

LibreOffice Basic is the default macro scripting language embedded within the LibreOffice productivity suite, designed to automate workflows and extend document functionality. To manipulate document elements like spreadsheets, text documents, and presentations, LibreOffice Basic relies on the Universal Network Objects (UNO) Application Programming Interface (API). This article explains the fundamentals of LibreOffice Basic, defines the UNO architecture, and demonstrates how Basic interfaces with UNO to control the LibreOffice environment.

What is LibreOffice Basic?

LibreOffice Basic is a lightweight, procedural programming language based on traditional BASIC syntax. It is built directly into LibreOffice and provides an integrated development environment (IDE) with debugging tools, syntax highlighting, and dialog builders. While it can execute standard programmatic tasks like loops, conditionals, and file operations independently, it cannot interact with documents without connecting to the underlying application structure.

What is the UNO API?

Universal Network Objects (UNO) is the core component model that powers LibreOffice. It is a language-independent, modular architecture that exposes the entire functionality of the office suite through a system of interfaces, services, and objects. Because UNO is language-agnostic, developers can interact with it using various programming languages, including Python, C++, Java, and LibreOffice Basic.

How LibreOffice Basic Interacts with UNO

LibreOffice Basic acts as a client that bridges your code to the UNO component model. Through built-in runtime functions and global variables, Basic can instantiate, inspect, and invoke UNO services.

1. Entry Points and Global Objects

LibreOffice Basic provides predefined global objects that serve as gateways to the UNO API: * ThisComponent: Represents the currently active document (such as a Calc spreadsheet or Writer document) as a UNO model object. * StarDesktop: Represents the top-level application framework, allowing scripts to open new files, iterate over open windows, and terminate the application.

2. Instantiating Services

To use UNO components not tied to an open document—such as file pickers, path configuration managers, or system services—Basic uses the built-in function CreateUnoService. This function requests a service by its standardized UNO interface name and returns an object reference that Basic can manipulate.

3. Services and Interfaces

UNO separates services (the components that perform tasks) from interfaces (the specific methods exposed by a service). In LibreOffice Basic, this distinction is largely abstracted away: when an object supports multiple UNO interfaces, Basic allows developers to call any method directly on the object variable without requiring explicit interface querying.

4. Structures and Constants

Many UNO API methods require structured data or specific enumeration values. LibreOffice Basic handles this through: * CreateUnoStruct: Creates an instance of a UNO structure (such as a cell property structure or color value). * Predefined Constants: Accesses global UNO constant groups to pass required parameters to API methods.

A Typical Interaction Flow

  1. Accessing the Target: The script references ThisComponent to get the root document object.
  2. Navigating the Object Hierarchy: The script traverses UNO interfaces—for example, moving from the document object to the Sheets collection, then to an individual Sheet, and finally to a specific Cell.
  3. Modifying Properties and Calling Methods: The script uses UNO methods on the cell object to set values, apply formatting, or execute calculations.
  4. Utilizing Auxiliary Services: If advanced actions are needed (like exporting to PDF or displaying a dialog box), the script invokes CreateUnoService to instantiate the required UNO component and passes the document object to it.

Through this relationship, LibreOffice Basic provides the syntax and control flow, while the UNO API provides the extensive object model required to manipulate every aspect of the office suite.