Надстройка для программирования в LibreOffice Calc
Способы расширения функциональных возможностей Calc с помощью надстроек, описанные ниже, не применяются. Интерфейсы по-прежнему используются и поддерживаются в целях совместимости с существующими надстройками, но для программирования новых надстроек необходимо применять новые функции интерфейса программирования.
LibreOffice Calc can be expanded by Add-Ins, which are external programming modules providing additional functions for working with spreadsheets. These are listed in the Function Wizard in the Add-In category. If you would like to program an Add-In yourself, you can learn here which functions must be exported by the shared libraryexternal DLL so that the Add-In can be successfully attached.
LibreOffice searches the Add-in folder defined in the configuration for a suitable shared libraryDLL. To be recognized by LibreOffice, the shared libraryDLL must have certain properties, as explained in the following. This information allows you to program your own Add-In for Function Wizard of LibreOffice Calc.
Понятие надстройки
Каждая библиотека надстроек позволяет использовать несколько функций. Некоторые из них предназначены для целей администрирования. Для пользовательских функций можно указывать любые имена. Однако параметры функций должны соответствовать определённым требованиям. Соглашения об именовании и вызове зависят от платформы.
Functions of Shared LibraryAddIn 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 |
Shared LibraryDLL functions
Following you will find a description of those functions, which are called at the Shared Libraryexternal DLL.
For all Shared LibraryDLL functions, the following applies:
void CALLTYPE fn(out, in1, in2, ...)
Output: Resulting value
Input: Any number of types (double&, char*, double*, char**, Cell area), where the Cell area is an array of types double array, string array, or cell array.
GetFunctionCount()
Возвращает количество функций без учёта функций управления для параметра ссылки. Каждая функция имеет уникальный номер от 0 до nCount-1. Этот номер требуется для функций GetFunctionData и GetParameterDescription.
Синтаксис
void CALLTYPE GetFunctionCount(USHORT& nCount)
Параметр
USHORT &nCount:
Output: Reference to a variable, which is supposed to contain the number of Add-In functions. For example: If the Add-In provides 5 functions for LibreOffice Calc, then nCount=5.
GetFunctionData()
Возвращает важные сведения о функции надстройки.
Синтаксис
void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)
Параметр
USHORT& nNo:
Input: Function number between 0 and nCount-1, inclusively.
char* pFuncName:
Output: Function name as seen by the programmer, as it is named in the Shared LibraryDLL. This name does not determine the name used in the Function Wizard.
USHORT& nParamCount:
Output: Number of parameters in AddIn function. This number must be greater than 0, because there is always a result value; the maximum value is 16.
Paramtype* peType:
Output: Pointer to an array of exactly 16 variables of type Paramtype. The first nParamCount entries are filled with the suitable type of parameter.
char* pInternalName:
Output: Function name as seen by the user, as it appears in the Function Wizard. May contain umlauts.
Параметры pFuncName и pInternalName являются массивами символов с размером 256 в LibreOffice Calc.
GetParameterDescription()
Возвращает краткое описание функции надстройки и её параметров. При необходимости эту функцию можно использовать для отображения описания функции и параметров в мастере функций.
Синтаксис
void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)
Параметр
USHORT& nNo:
Input: Number of the function in the library; between 0 and nCount-1.
USHORT& nParam:
Input: Indicates, for which parameter the description is provided; parameters start at 1. If nParam is 0, the description itself is supposed to be provided in pDesc; in this case, pName does not have any meaning.
char* pName:
Output: Takes up the parameter name or type, for example, the word "Number" or "String" or "Date", and so on. Implemented in LibreOffice Calc as char[256].
char* pDesc:
Output: Takes up the description of the parameter, for example, "Value, at which the universe is to be calculated." Implemented in LibreOffice Calc as 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+Len |
... |
Следующий элемент |
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+длина |
... |
Следующий элемент |