Съдържание

# Приставка за програмиране в LibreOffice Calc

Описаният по-долу начин за разширяване на Calc чрез приставки е остарял. Интерфейсите са все още валидни и се поддържат, за да се осигури съвместимост със съществуващите приставки, но за програмиране на нови приставки трябва да използвате новите функции на програмния интерфейс.

LibreOffice Calc може да бъде разширявана чрез приставки – външни програмни модули, предоставящи допълнителни функции за работа с електронни таблици. Те са изброени в помощника за функции в категорията Приставки. Ако желаете да програмирате приставка, тук можете да научите кои функции трябва да бъдат експортирани чрез споделена библиотека външна библиотека от тип DLL, за да бъде приставката успешно прикрепена.

LibreOffice претърсва зададената в конфигурацията папка с приставки за подходяща споделена библиотека DLL библиотека. За да бъде разпозната от LibreOffice, споделената библиотека динамично зарежданата библиотека трябва да изпълнява определени условия, както е обяснено по-долу. Тази информация ви позволява да програмирате свои собствени приставки за помощника за функции на LibreOffice Calc.

## Понятие за приставки

Всяка библиотека с приставка предоставя няколко функции. Някои от тях са за административни цели. Можете да използвате за функциите си почти произволни имена. Трябва обаче да спазвате определени правила, свързани с предаването на параметри. Точните конвенции за извикване и наименуване се различават според платформата.

### Функции на споделената библиотека динамично зарежданата библиотека

Като минимум трябва да съществуват административните функции GetFunctionCount и GetFunctionData. Чрез тях може да се получи информация за функциите и за типовете на техните параметри и резултати. Връщаните стойности могат да бъдат числа с двойна точност или низове. За параметрите се поддържат и области от клетки: масив от числа с двойна точност, масив от низове или масив от клетки.

Параметрите се подават по адрес, така че е възможно променяне на стойностите. Това обаче не се поддържа в LibreOffice Calc, тъй като няма смисъл в контекста на електронна таблица.

Библиотеките могат да се презареждат по време на изпълнение и тяхното съдържание да се анализира чрез административните функции. За всяка функция е налице информация за броя и вида на параметрите, външното и вътрешното име на функция и административния номер.

Функциите се изпълняват синхронно и връщат резултатите си незабавно. Възможни са и функции в реално време (асинхронни). Те не са описани подробно поради сложността си.

## Общи сведения за интерфейса

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

Типовете данни са дефинирани както следва:

Типове данни | Дефиниция
--- | ---
CALLTYPE | В Windows: FAR PASCAL (_far _pascal) Други: default (подразбираният вариант за операционната система)
USHORT | Цяло число без знак, 2 байта
DOUBLE | 8-байтов формат, зависи от платформата
Paramtype | Зависи от платформата, например int PTR_DOUBLE =0 указател към число с двойна точност PTR_STRING =1 указател към низ, завършващ с нула PTR_DOUBLE_ARR =2 указател към масив от числа с двойна точност PTR_STRING_ARR =3 указател към масив от низове PTR_CELL_ARR =4 указател към масив от клетки NONE =5

## Функции в споделената библиотека динамично зарежданата библиотека

По-долу ще намерите описание на извикваните функции от споделената библиотека външната динамично зареждана библиотека (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:

Изход: брой на параметрите на функцията. Трябва да е по-голям от 0, тъй като винаги има резултатна стойност. Максимумът е 16.

Paramtype* peType:

Изход: указател към масив от точно 16 променливи от типа Paramtype. Първите nParamCount записа са попълнени със съответните типове на параметрите.

char* pInternalName:

Изход: името на функция, както се вижда от потребителя и се изписва в помощника за функции. Може да съдържа букви с умлаут.

Параметрите pFuncName и pInternalName са масиви от типа char, които в LibreOffice Calc имат размер 256.

### 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 са масиви от типа char, реализирани в LibreOffice Calc с размер 256. Забележете, че пространството в помощника за функции е ограничено и не могат да се използват всичките 256 знака.

## Области от клетки

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

### Масив от числа с двойна точност

Параметърът може да представлява масив със стойности от типа Number/Double. Масив от типа double се дефинира в LibreOffice Calc както следва:

Отместване | Име | Описание
--- | --- | ---
0 | Col1 | Номер на колона за горния ляв ъгъл на областта от клетки. Номерацията започва от 0.
2 | Row1 | Номер на ред за горния ляв ъгъл на областта от клетки. Номерацията започва от 0.
4 | Tab1 | Номер на таблица за горния ляв ъгъл на областта от клетки. Номерацията започва от 0.
6 | Col2 | Номер на колона в долния десен ъгъл на областта от клетки. Номерацията започва от 0.
8 | Row2 | Номер на ред за долния десен ъгъл на областта от клетки. Номерацията започва от 0.
10 | Tab2 | Номер на таблица за долния десен ъгъл на областта от клетки. Номерацията започва от 0.
12 | Брой | Брой на следващите елементи. Празните клетки не се броят и не се предават.
14 | Col | Номер на колона за елемента. Номерацията започва от 0.
16 | Ред | Номер на ред за елемента. Номерацията започва от 0.
18 | Tab | Номер на таблица за елемента. Номерацията започва от 0.
20 | Error | Номер на грешка, като 0 означава „няма грешка“. Ако елементът идва от клетка с формула, стойността за грешка се определя от формулата.
22 | Стойност | 8-байтова променлива по стандарта на IEEE от типа double/floating point
30 | ... | Следващ елемент

### Масив от низове

Област от клетки с текстови стойности, предавана като масив от низове. Масивите от низове в LibreOffice Calc са дефинирани както следва:

Отместване | Име | Описание
--- | --- | ---
0 | Col1 | Номер на колона за горния ляв ъгъл на областта от клетки. Номерацията започва от 0.
2 | Row1 | Номер на ред за горния ляв ъгъл на областта от клетки. Номерацията започва от 0.
4 | Tab1 | Номер на таблица за горния ляв ъгъл на областта от клетки. Номерацията започва от 0.
6 | Col2 | Номер на колона в долния десен ъгъл на областта от клетки. Номерацията започва от 0.
8 | Row2 | Номер на ред за долния десен ъгъл на областта от клетки. Номерацията започва от 0.
10 | Tab2 | Номер на таблица за долния десен ъгъл на областта от клетки. Номерацията започва от 0.
12 | Брой | Брой на следващите елементи. Празните клетки не се броят и не се предават.
14 | Col | Номер на колона за елемента. Номерацията започва от 0.
16 | Ред | Номер на ред за елемента. Номерацията започва от 0.
18 | Tab | Номер на таблица за елемента. Номерацията започва от 0.
20 | Error | Номер на грешка, като 0 означава „няма грешка“. Ако елементът идва от клетка с формула, стойността за грешка се определя от формулата.
22 | Len | Дължина на следващия низ, включително завършващия нулев байт. Ако дължината заедно с нулевия байт е нечетна, се добавя втори нулев байт, за да се достигне четна дължина. Така Len се изчислява като ((StrLen+2)&~1).
24 | String | Низ, завършващ с нулев байт
24+Len | ... | Следващ елемент

### Масив от клетки

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

Отместване | Име | Описание
--- | --- | ---
0 | Col1 | Номер на колона за горния ляв ъгъл на областта от клетки. Номерацията започва от 0.
2 | Row1 | Номер на ред за горния ляв ъгъл на областта от клетки. Номерацията започва от 0.
4 | Tab1 | Номер на таблица за горния ляв ъгъл на областта от клетки. Номерацията започва от 0.
6 | Col2 | Номер на колона в долния десен ъгъл на областта от клетки. Номерацията започва от 0.
8 | Row2 | Номер на ред за долния десен ъгъл на областта от клетки. Номерацията започва от 0.
10 | Tab2 | Номер на таблица за долния десен ъгъл на областта от клетки. Номерацията започва от 0.
12 | Брой | Брой на следващите елементи. Празните клетки не се броят и не се предават.
14 | Col | Номер на колона за елемента. Номерацията започва от 0.
16 | Ред | Номер на ред за елемента. Номерацията започва от 0.
18 | Tab | Номер на таблица за елемента. Номерацията започва от 0.
20 | Error | Номер на грешка, като 0 означава „няма грешка“. Ако елементът идва от клетка с формула, стойността за грешка се определя от формулата.
22 | Тип | Тип на съдържанието на клетката, 0 == Double, 1 == String
24 | Value или Len | Ако Type == 0: 8-байтова променлива по стандарта на IEEE от типа double/floating point Ако Type == 1: дължина на следващия низ, включително завършващия нулев байт. Ако дължината заедно с нулевия байт е нечетна, се добавя втори нулев байт, за да се достигне четна дължина. Така Len се изчислява като ((StrLen+2)&~1).
26 ако Type==1 | String | Ако Type == 1: низ, завършващ с нулев байт
32 или 26+Len | ... | Следващ елемент