Надстройка для программирования в LibreOffice Calc

Значок предупреждения

Способы расширения функциональных возможностей Calc с помощью надстроек, описанные ниже, не применяются. Интерфейсы по-прежнему используются и поддерживаются в целях совместимости с существующими надстройками, но для программирования новых надстроек необходимо применять новые функции интерфейса программирования.


Возможности программы LibreOffice Calc можно расширить за счёт надстроек, которые представляют собой внешние модули программирования с дополнительными функциями работы с электронными таблицами. Эти функции перечислены в мастере функций в категории Надстройка. Если программирование надстройки выполняется пользователем, он может ознакомиться с функциями, которые требуется экспортировать в для успешного добавления надстроек.

LibreOffice сканирует каталог надстроек, указанный в настройках, в поиске подходящей . Для того, чтобы LibreOfficeсмог распознать , этот файл должен содержать некоторые свойства, описанные ниже. Эта информация позволяет данной надстройке иметь свой Мастер функций в LibreOffice Calc.

Понятие надстройки

Каждая библиотека надстроек позволяет использовать несколько функций. Некоторые из них предназначены для целей администрирования. Для пользовательских функций можно указывать любые имена. Однако параметры функций должны соответствовать определенным требованиям. Соглашения об именовании и вызове зависят от платформы.

Функции

Как минимум должны быть созданы функции администрирования GetFunctionCount и GetFunctionData. С помощью этих функций можно определять как функции, так и типы параметров и возвращаемые значения. Для возвращаемых значений поддерживаются двойные и строковые массивы. В качестве параметров поддерживаются диапазоны ячеек Двойной массив, Строковый массив и Массив ячеек.

Параметры передаются с использованием ссылок. Поэтому изменение значений возможно. Но в LibreOffice Calc эта возможность не поддерживается, т. к. её применение в электронных таблицах нецелесообразно.

Во время выполнения можно перезагружать библиотеки и анализировать их содержимое с помощью функций администрирования. Для каждой функции существуют данные о количестве и типе параметров, именах и номерах внешних функций.

Функции вызываются синхронно, а результат возвращается немедленно. Можно также использовать функции реального времени (асинхронные). Но подробное описание этих функций не приводится из-за их сложности.

Общие сведения об интерфейсе

Максимальное количество параметров для надстройки, добавленной к LibreOffice Calc, равно 16: одно возвращаемое значение и максимум 15 входных параметров функции.

Типы данных определяются следующим образом:

Типы данных

Определение

CALLTYPE

Под Windows: FAR PASCAL (_far _pascal)

Другой: по умолчанию (по умолчанию для операционной системы)

USHORT

Целое число из 2 байтов без знака

DOUBLE

Зависящий от платформы 8-байтовый формат

Paramtype

В зависимости от платформы, например, целое число

Указатель PTR_DOUBLE =0 на двойной массив

Указатель PTR_STRING =1 на строку, которая оканчивается на ноль

Указатель PTR_DOUBLE_ARR =2 на двойной массив

Указатель PTR_STRING_ARR =3 на строковый массив

Указатель PTR_CELL_ARR =4 на массив ячеек

НЕТ =5


Ниже приводится описание функций, вызываемых из .

Для всех функций справедливо следующее:

void CALLTYPE fn(out, in1, in2, ...)

Вывод. Полученное значение

Ввод. Любое количество типов (двойной&, символ*, двойной*, символ**, диапазон ячеек), где диапазон ячеек представляет собой двойной массив, строковый массив или массив ячеек.

GetFunctionCount()

Возвращает количество функций без учёта функций управления для параметра ссылки. Каждая функция имеет уникальный номер от 0 до nCount-1. Этот номер требуется для функций GetFunctionData и GetParameterDescription.

Синтаксис

void CALLTYPE GetFunctionCount(USHORT& nCount)

Параметр

USHORT &nCount:

Вывод. Ссылка на переменную, которая должна содержать количество функций надстроек. Например, если надстройка включает 5 функций для LibreOffice Calc, nCount=5.

GetFunctionData()

Возвращает важные сведения о функции надстройки.

Синтаксис

void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)

Параметр

USHORT& nNo:

Ввод. Номер функции от 0 до nCount-1 включительно.

char* pFuncName:

Вывод. Имя функции, отображаемое для программиста и включённое в . Это имя не определяет имя функции в мастере функций.

USHORT& nParamCount:

Вывод. Количество параметров в функции надстройки. Это число должно быть больше 0, т. к. всегда существует возвращаемое значение. Максимальное количество - 16.

Paramtype* peType:

Вывод. Указатель на массив из 16 переменных с типом "Paramtype". Первые записи "nParamCount" заполняются нужным типом параметра.

char* pInternalName:

Вывод. Имя функции отображается для пользователя так же, как и в мастере функций. Имя может содержать умляуты.

Параметры pFuncName и pInternalName являются массивами символов с размером 256 в LibreOffice Calc.

GetParameterDescription()

Возвращает краткое описание функции надстройки и её параметров. При необходимости эту функцию можно использовать для отображения описания функции и параметров в мастере функций.

Синтаксис

void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)

Параметр

USHORT& nNo:

Ввод. Номер функции в библиотеке (от 0 до nCount-1).

USHORT& nParam:

Ввод. Параметр, для которого требуется получить описание. Параметры начинаются с 1. Если nParam имеет значение 0, описание предоставляется в pDesc. В этом случае pName не имеет значения.

char* pName:

Вывод. Имя или тип параметра, например, слово "Число", "Строка", "Дата" и т. д. Реализовано в LibreOffice Calc в качестве char[256].

char* pDesc:

Вывод. Описание параметра, например, "Значение, при котором рассчитывается универсальное множество". Реализовано в LibreOffice Calc в качестве char[256].

pName и pDesc являются массивами символов; эти функции реализованы в LibreOffice Calc с размером 256. Обратите внимание, что доступное место в мастере функций ограничено, поэтому размер в 256 символов невозможно использовать полностью.

Диапазоны ячеек

Приведенные ниже таблицы содержат сведения о том, какие структуры данных необходимы внешнему программному модулю для передачи диапазонов ячеек. LibreOffice Calc распознает три типа массивов в зависимости от типа данных.

Double Array

В качестве параметра можно передать диапазон ячеек со значениями типа Number или Double. Массив значений типа Double в LibreOffice Calc определяется следующим образом:

Смещение

Название

Описание

0

Стлб1

Номер столбца в верхнем левом углу диапазона ячеек. Нумерация начинается с 0.

2

Стр1

Номер строки в верхнем левом углу диапазона ячеек. Нумерация начинается с 0.

4

Таб1

Номер таблицы в верхнем левом углу диапазона ячеек. Нумерация начинается с 0.

6

Стлб2

Номер столбца в нижнем правом углу диапазона ячеек. Нумерация начинается с 0.

8

Стр2

Номер строки в нижнем правом углу диапазона ячеек. Нумерация начинается с 0.

10

Таб2

Номер таблицы в нижнем правом углу диапазона ячеек. Нумерация начинается с 0.

12

Количество

Количество элементов. Пустые ячейки не подсчитываются и не передаются.

14

Столбец

Номер столбца для элемента. Нумерация начинается с 0.

16

Строка

Номер строки для элемента. Нумерация начинается с 0.

18

Таб

Номер таблицы для элемента. Нумерация начинается с 0.

20

Ошибка

Номер ошибки. Значение 0 указывает на отсутствие ошибки. Если элемент содержится в ячейке с формулой, номер ошибки определяется этой формулой.

22

Значение

Переменная IEEE из 8 байтов с типом Double или Float

30

...

Следующий элемент


String Array

Диапазон ячеек, который содержит значения с типом данных Text и передаётся как массив значений типа String. Массив типа String в LibreOffice Calc определяется следующим образом:

Смещение

Название

Описание

0

Стлб1

Номер столбца в верхнем левом углу диапазона ячеек. Нумерация начинается с 0.

2

Стр1

Номер строки в верхнем левом углу диапазона ячеек. Нумерация начинается с 0.

4

Таб1

Номер таблицы в верхнем левом углу диапазона ячеек. Нумерация начинается с 0.

6

Стлб2

Номер столбца в нижнем правом углу диапазона ячеек. Нумерация начинается с 0.

8

Стр2

Номер строки в нижнем правом углу диапазона ячеек. Нумерация начинается с 0.

10

Таб2

Номер таблицы в нижнем правом углу диапазона ячеек. Нумерация начинается с 0.

12

Количество

Количество элементов. Пустые ячейки не подсчитываются и не передаются.

14

Столбец

Номер столбца для элемента. Нумерация начинается с 0.

16

Строка

Номер строки для элемента. Нумерация начинается с 0.

18

Таб

Номер таблицы для элемента. Нумерация начинается с 0.

20

Ошибка

Номер ошибки. Значение 0 указывает на отсутствие ошибки. Если элемент содержится в ячейке с формулой, номер ошибки определяется этой формулой.

22

Длина

Длина следующей строки, включая последний нулевой байт. Если длина с учетом последнего нулевого байта имеет нечётное значение, к строке добавляется второй ноль для получения чётного числа. Поэтому для расчета длины используется формула ((StrLen+2)&~1).

24

Строка

Строка с последним нулевым байтом

24+Длина

...

Следующий элемент


Cell Array

Массивы ячеек используются для вызова диапазонов ячеек, которые содержат текст и числа. Массив ячеек в LibreOffice Calc определяется следующим образом:

Смещение

Название

Описание

0

Стлб1

Номер столбца в верхнем левом углу диапазона ячеек. Нумерация начинается с 0.

2

Стр1

Номер строки в верхнем левом углу диапазона ячеек. Нумерация начинается с 0.

4

Таб1

Номер таблицы в верхнем левом углу диапазона ячеек. Нумерация начинается с 0.

6

Стлб2

Номер столбца в нижнем правом углу диапазона ячеек. Нумерация начинается с 0.

8

Стр2

Номер строки в нижнем правом углу диапазона ячеек. Нумерация начинается с 0.

10

Таб2

Номер таблицы в нижнем правом углу диапазона ячеек. Нумерация начинается с 0.

12

Количество

Количество элементов. Пустые ячейки не подсчитываются и не передаются.

14

Столбец

Номер столбца для элемента. Нумерация начинается с 0.

16

Строка

Номер строки для элемента. Нумерация начинается с 0.

18

Таб

Номер таблицы для элемента. Нумерация начинается с 0.

20

Ошибка

Номер ошибки. Значение 0 указывает на отсутствие ошибки. Если элемент содержится в ячейке с формулой, номер ошибки определяется этой формулой.

22

Тип

Тип содержимого ячейки: 0 == двойной, 1 == строковый

24

Значение или длина

Если тип == 0, переменная IEEE из 8 байтов с типом Double или Float

Если тип == ~1, длина следующей строки, включая последний нулевой байт. Если длина с учетом последнего нулевого байта имеет нечётное значение, к строке добавляется второй ноль для получения чётного числа. Поэтому для расчета длины используется формула ((StrLen+2)&1).

26, если тип==1

Строка

Если тип == 1, строка с последним нулевым байтом

32 или 26+длина

...

Следующий элемент