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

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

LibreOffice претърсва зададената в конфигурацията папка с приставки за подходяща . За да бъде разпозната от 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

Функции в

По-долу ще намерите описание на извикваните функции от .

За всички функции от важи следното:

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:

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

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	Count	Брой на следващите елементи. Празните клетки не се броят и не се предават.
14	Col	Номер на колона за елемента. Номерацията започва от 0.
16	Ред	Номер на ред за елемента. Номерацията започва от 0.
18	Tab	Номер на таблица за елемента. Номерацията започва от 0.
20	Error	Номер на грешка, като 0 означава „няма грешка“. Ако елементът идва от клетка с формула, стойността за грешка се определя от формулата.
22	Value	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	Count	Брой на следващите елементи. Празните клетки не се броят и не се предават.
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	Count	Брой на следващите елементи. Празните клетки не се броят и не се предават.
14	Col	Номер на колона за елемента. Номерацията започва от 0.
16	Ред	Номер на ред за елемента. Номерацията започва от 0.
18	Tab	Номер на таблица за елемента. Номерацията започва от 0.
20	Error	Номер на грешка, като 0 означава „няма грешка“. Ако елементът идва от клетка с формула, стойността за грешка се определя от формулата.
22	Type	Тип на съдържанието на клетката, 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	...	Следващ елемент