Съдържание

# Библиотеката ScriptForge

За достъп до тази команда...

Отворете Инструменти - Макроси - LibreOffice Basic - Редактиране и изберете контейнера Макроси на приложението.

Библиотеките ScriptForge представляват разширяем набор от ресурси за скриптиране на макроси за LibreOffice, които могат да бъдат използвани от макроси на Basic или скриптове на Python.

• Макросите на Basic изискват зареждане на библиотеката ScriptForge чрез следния оператор:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Скриптовете на Python изискват импортиране от модула scriptforge:
from scriptforge import CreateScriptService

За да научите повече за създаването и изпълняването на скриптове на Python с библиотеката ScriptForge, прочетете страницата от помощта Създаване на скриптове на Python със ScriptForge.

## Обръщения към услуги на ScriptForge

Описаните модули и класове се извикват от потребителски скриптове като „Услуги“. За тази цел за всеки език е проектиран общ конструктор на тези услуги.

Методът Dispose е наличен във всички услуги и трябва да бъде извикван, за да се освободят ресурсите след употреба:

##### В Basic

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Set oSvc = CreateScriptService("servicename"[, arg0, arg1, ...])
        ' ...
        oSvc.Dispose()

##### В Python

        from scriptforge import CreateScriptService
        svc = CreateScriptService('servicename'[, arg0, arg1, ...])
        # ...
        svc.Dispose()

## Услуги, предоставяни от библиотеката ScriptForge

Категория | Услуги
--- | ---
LibreOffice Basic | Array Dictionary | Exception FileSystem | String TextStream
Съдържание на документа | Base Calc Chart | Database Dataset Datasheet | Document FormDocument Writer
Потребителски интерфейс | Dialog DialogControl Form | FormControl Menu PopupMenu | Toolbar ToolbarButton UI
Помощни средства | Basic L10N Platform | Region Services Session | Timer UnitTest

## Услуга ScriptForge.Array

Предоставя набор от методи за манипулиране и трансформиране на едномерни масиви (вектори) и двумерни масиви (матрици). Това включва операции с множества, сортиране, импортиране от и експортиране към текстови файлове.

Масиви с повече от две измерения не могат да се използват с методите в тази услуга, с изключение само на метода CountDims, който приема масиви с произволен брой измерения.

## Услуга SFDocuments.Base

Услугата Base предоставя методи и свойства за управление и работа с документи на LibreOffice Base.

Тази услуга е тясно свързана с услугата Document, която предоставя общи методи за работа с документи на LibreOffice, включително такива на Base. Следователно услугата Base разширява Document и предлага допълнителни методи, специфични за документите на Base, като позволява на потребителите:

- да получават достъп до базата от данни, която се съдържа в документ на Base;

- да отварят документи с формуляри, съхранявани в документ на Base;

- да проверяват дали в момента е зареден документ с формуляри от документ на Base.

## Услуга ScriptForge.Basic

Услугата ScriptForge предоставя съвкупност от методи на LibreOffice Basic за изпълнение в контекст на Python. Методите на услугата Basic възпроизвеждат точния синтаксис и поведение на вградените функции на Basic.

## Услуга SFDocuments.Calc

Споделената библиотека SFDocuments предлага набор от методи и свойства за улесняване управлението и боравенето с документи на LibreOffice.

Услугата SFDocuments.Calc е подклас на услугата SFDocuments.Document. Всички методи и свойства, дефинирани за услугата Document, са достъпни и през екземпляр на услугата Calc.

Услугата Calc е предназначена основно за:

- боравене с листове в документ на Calc (копиране, вмъкване, преместване и т.н.)

- обмен на данни между структури от данни на Basic и диапазони на Calc

- копиране и импортиране на големи количества данни.

## Услуга SFDocuments.Chart

Услугата Chart предоставя набор от свойства и методи за боравене с диаграми в документи на Calc. С тази услуга е възможно:

- да се осъществява достъп до обекти диаграми в документи на Calc и да се променят свойствата им;

- да се създават и вмъкват нови диаграми в документ на Calc;

- да се експортират диаграми като файлове с изображения.

## Услуга SFDatabases.Database

Услугата Database предоставя достъп до вградени или описани в документи на Base бази от данни. Тази услуга предлага методи за:

- получаване на достъп до таблици в база от данни

- стартиране на заявки SELECT и изчисляване на агрегатни функции

- изпълнение на оператори за действия на SQL като INSERT, UPDATE, DELETE и т.н.

## Услуга SFDatabases.Dataset

Услугата Dataset служи за представяне на таблични данни, предоставени от база от данни. Тази услуга позволява:

- навигация в набор от данни и достъп до данните в него;

- променяне, вмъкване и премахване на записи в набор от данни.

## Услуга SFDatabases.Datasheet

Услугата Datasheet позволява визуализиране съдържанието на таблици в база от данни, както и резултатите от заявки и оператори на SQL, посредством прозореца „Изглед с данни“ на Base. Освен това чрез нея е възможно:

- да се добавят потребителски менюта в изгледа с данни

- да се осъществява достъп до данните в конкретни позиции от изгледа с данни

- да се позиционира курсора в зададена клетка от изгледа с данни.

## Услуга SFDialogs.Dialog

Услугата Dialog подпомага управлението на диалози, изградени с редактора на диалози на Basic или създадени в движение. Всеки екземпляр на текущия клас представя един отделен диалогов прозорец, показан на потребителя.

## SFDialogs.DialogControl service

The DialogControl service manages the controls belonging to a dialog defined with the Basic Dialog Editor. Each instance of the current service represents a single control within a dialog box.

The focus is set on getting and setting the values displayed by the controls of the dialog box. Formatting is accessible via the XControlModel and XControlView properties.

Note that the unique DialogControl.Value property content varies according to the control type.

A special attention is given to controls of type tree control. It is easy to populate a tree, either branch by branch, or with a set of branches at once. Populating a tree control can be performed statically or dynamically.

## ScriptForge.Dictionary service

A dictionary is a collection of key-item pairs

- The key is a case-insensitive string

- Items may be of any type

## SFDocuments.Document service

The SFDocuments library provides methods and properties to facilitate the management and manipulation of LibreOffice documents.

Methods that are applicable for all types of documents (Text Documents, Sheets, Presentations, etc) are provided by the SFDocuments.Document service. Some examples are:

- Opening, closing and saving documents

- Accessing standard or custom properties of documents

## ScriptForge.Exception service

The Exception service is a collection of methods to assist in code debugging in Basic and Python scripts and in error handling in Basic scripts.

In Basic scripts, when a run-time error occurs, the methods and properties of the Exception service help identify the error context and allow to handle it.

## ScriptForge.FileSystem service

The FileSystem service includes routines to handle files and folders. Next are some examples of the features provided by this service:

- Verify whether a file or folder exists.

- Create and delete folders and files.

- Launch dialog boxes to open/save files.

- Access the list of files in a folder, etc.

## SFDocuments.Form service

The Form service provides methods and properties to manage forms in LibreOffice documents. This service supports forms in Base, Calc and Writer documents and allows to:

- Open and activate forms.

- Navigate through records shown by the form.

- Get access to the controls inside the form.

- Get access to subforms of a parent form.

## SFDocuments.FormControl service

The FormControl service provides access to the controls that belong to a form, a subform or a table control of a FormDocument. Each instance of the FormControl service refers to a single control in the form. This service allows users to:

- Get and set the properties of the control represented by the FormControl instance.

- Access the current value displayed by the control.

- Set the focus on the desired control.

## SFDocuments.FormDocument service

The FormDocument service allows to access form documents stored in LibreOffice Base documents.

In a Base document, existing form documents can be viewed by selecting View - Forms in the user interface. Each form document may be composed of one or more forms, including the main form and other sub-forms.

## ScriptForge.L10N service

This service provides a number of methods related to the translation of strings with minimal impact on the program's source code. The methods provided by the L10N service can be used mainly to:

- Create POT files that can be used as templates for translation of all strings in the program.

- Get translated strings at runtime for the language defined in the Locale property.

## SFWidgets.Menu service

The Menu service can be used to create and remove menus from the menubar of a LibreOffice document window. Each menu entry can be associated with a script or with a UNO command. This service provides the following capabilities:

- Creation of menus with custom entries, checkboxes, radio buttons and separators.

- Decoration of menu items with icons and tooltips.

## ScriptForge.Platform service

The Platform service provides a collection of properties about the current execution environment and context, such as:

- The hardware platform (architecture, CPU count, machine type, etc)

- Operating system information (OS type, release, version, etc)

- The LibreOffice version

- The current user name

## SFWidgets.PopupMenu service

The PopupMenu service can be used to create popup menus that can be associated with events or executed by scripts. This service provides the following capabilities:

- Creation of popup menus with custom entries, checkboxes and radio buttons.

- Decoration of menu items with icons and tooltips.

## ScriptForge.Region service

The Region service provides a collection of properties and methods to handle locale and region-related aspects of programming, such as:

- Accessing locale and region-dependent settings such as number formatting, currency and timezones.

- Converting timezones and calculate Daylight Saving Time (DST) offsets.

- Transforming numbers into text in any supported language.

## ScriptForge.Services service

The main purpose of the Services module is to provide access to the CreateScriptService method, which can be called in user scripts to instantiate services that are implemented using the ScriptForge framework.

## ScriptForge.Session service

The Session service gathers various general-purpose methods about:

- the installation or execution environment

- UNO introspection

- the invocation of external scripts or programs

## ScriptForge.String service

The String service provides a collection of methods for string processing. These methods can be used to:

- Validate the contents of strings

- Format strings by trimming, justifying or wrapping their contents

- Use regular expressions to search and replace substrings

- Apply hash algorithms on strings, etc.

## ScriptForge.TextStream service

The TextStream service is used to sequentially read from and write to files opened or created using the ScriptForge.FileSystem service.

The methods OpenTextFile and CreateTextFile from the FileSystem service return an instance of the TextStream service.

## ScriptForge.Timer service

The Timer service measures the amount of time it takes to run user scripts.

A Timer measures durations. It can be:

- Started, to indicate when to start measuring time.

- Suspended, to pause measuring running time.

- Resumed, to continue tracking running time after the Timer has been suspended.

- Restarted, which will cancel previous measurements and start the Timer at zero.

## SFWidgets.Toolbar service

The Toolbar service allows to retrieve information related to the toolbars available for a specific document window. With this service it is possible to:

- Toggle the visibility of specific toolbars.

- Access information about the buttons available in each toolbar.

## SFWidgets.ToolbarButton service

The ToolbarButton service allows to retrieve information related to the toolbar buttons available in a given toolbar. With this service it is possible to:

- Toggle the visibility of toolbar elements.

- Execute the command associated with a given toolbar button.

## ScriptForge.UI service

The UI (User Interface) service simplifies the identification and the manipulation of the different windows composing the whole LibreOffice application:

- Windows selection

- Windows moving and resizing

- Statusbar settings

- Display of a floating progress bar

- Creation of new windows

- Access to the underlying "documents"

## SFUnitTests.UnitTest service

The UnitTest service provides a framework for automating unit tests using the Basic language, including the ability to:

- Aggregate test cases into test suites and unit tests.

- Share setup and shutdown code among test cases.

- Report test results using the Console.

## SFDocuments.Writer service

Споделената библиотека SFDocuments предлага набор от методи и свойства за улесняване управлението и боравенето с документи на LibreOffice.

Some methods are generic for all types of documents and are inherited from the SF_Document module, whereas other methods that are specific for Writer documents are defined in the SF_Writer module.

Бележка: други, неописани модули на ScriptForge са запазени за вътрешна употреба. Съдържанието им подлежи на промяна без предизвестие.

В ScriptForge всички подпрограми или идентификатори на Basic с префикс „_“ са запазени за вътрешна употреба. Те не са предназначени за използване в макроси на Basic.