Надстройка для программирования в LibreOffice Calc
Способы расширения функциональных возможностей Calc с помощью надстроек, описанных ниже, устарели. Интерфейсы по-прежнему используются и поддерживаются в целях совместимости с существующими надстройками, но для программирования новых надстроек необходимо применять новые функции API.
Расширение LibreOffice Calc может осуществляться с помощью надстроек, которые являются внешними программными модулями, предоставляющими дополнительные функции для работы с электронными таблицами. Они перечислены в Мастере функций в категории Надстройка. При необходимости самостоятельного создания надстройки данный раздел поможет разобраться с тем, какие функции необходимо экспортировать в общую библиотекувнешний DLL для удачного присоединения надстройки.
LibreOffice выполняет поиск в папке надстройки, которая задана в конфигурации соответствующей общей библиотекиDLL. Чтобы LibreOffice мог распознать её, общая библиотекаDLL должна обладать определёнными свойствами, поясняемыми ниже. Эта информация позволит создавать свои собственные надстройки для Мастера функций в LibreOffice Calc.
Понятие надстройки
Каждая библиотека надстроек позволяет использовать несколько функций. Некоторые из них предназначены для целей администрирования. Для пользовательских функций можно указывать любые имена. Однако параметры функций должны соответствовать определённым требованиям. Соглашения об именовании и вызове зависят от платформы.
Функции Общей библиотекиDLL надстройки
Как минимум должны существовать функции администрирования 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 |
Функции Общей библиотекиDLL
Ниже следует описание тех функций, которые называются Общей библиотекойвнешних DLL.
Для всех функций Общей библиотекиDLL, применимы следующие аргументы:
void CALLTYPE fn(out, in1, in2, ...)
Вывод: Итоговое значение
Ввод: Любое число типов (double&, char*, double*, char**, Диапазон ячеек), где Диапазон ячеек представляет собой массив чисел с плавающей точкой двойной точности, массив строк или массив ячеек.
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:
Вывод: Имя функции с точки зрения программиста, согласно имени, заданному в Общей библиотекеDLL. Данное имя не определяет имя, использующееся в Мастере функций.
USHORT& nParamCount:
Вывод: Число параметров в функции надстроек. Этот номер должен быть больше нуля, поскольку всегда существует возвращаемое значение; максимальное число — 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 распознаёт три типа массивов в зависимости от типа данных.
Массив чисел с плавающей точкой двойной точности
В качестве параметра можно передать диапазон ячеек со значениями типа 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 |
... |
Следующий элемент |
Массив строк
Диапазон ячеек, который содержит значения с типом данных Text и передаётся как массив строк. Массив строк в 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+Len |
... |
Следующий элемент |
Массив ячеек
Массивы ячеек используются для вызова диапазонов ячеек, которые содержат текст и числа. Массив ячеек в 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 == Double, 1 == String |
|
24 |
Значение или длина |
Если тип == 0, переменная IEEE из 8 байтов с типом Double или Float Если тип == 1, длина последующей строки, включая конечный нулевой байт. Если длина с учётом последнего нулевого байта имеет нечётное значение, к строке добавляется второй ноль для получения чётного числа. Поэтому для расчёта длины используется формула ((StrLen+2)&~1). |
|
26, если тип==1 |
Строка |
Если тип == 1, строка с последним нулевым байтом |
|
32 или 26+длина |
… |
Следующий элемент |