IBM Lotus Symphony
|
![]() |
Opisana w tym dokumencie metoda rozszerzania funkcjonalności komponentu Lotus® Symphony™ Spreadsheets za pomocą programów dodatkowych jest przestarzała. Interfejsy są wciąż poprawne i obsługiwane, co zapewnia kompatybilność z istniejącymi programami dodatkowymi, ale do tworzenia nowych programów dodatkowych należy używać nowych funkcji API. |
Komponent Lotus Symphony Spreadsheets można rozszerzać przy użyciu programów dodatkowych, które są zewnętrznymi modułami programistycznymi udostępniającymi dodatkowe funkcje na potrzeby pracy z arkuszami kalkulacyjnymi. Są one wyświetlane w kreatorze funkcji w kategorii Program dodatkowy. Jeśli chcesz samodzielnie napisać program dodatkowy, warto przeczytać zawarte w tym dokumencie informacje o tym, które funkcje muszą zostać wyeksportowane przez zewnętrzną bibliotekę DLL w celu umożliwienia pomyślnego przyłączenia programu dodatkowego.
Produkt Lotus Symphony wyszukuje odpowiednie biblioteki DLL w folderze programów dodatkowych zdefiniowanym w konfiguracji. Rozpoznanie biblioteki DLL przez produkt Lotus Symphony umożliwiają określone właściwości opisane w dalszej części tego dokumentu. Podane informacje pozwalają na tworzenie własnych programów dodatkowych dla kreatora funkcji komponentu Lotus Symphony Spreadsheets.
Każda biblioteka programu dodatkowego udostępnia kilka funkcji. Niektóre z nich służą do celów administracyjnych. Dla własnych funkcji można wybrać prawie dowolną nazwę. Jednak muszą być one zgodne z pewnymi regułami dotyczącymi przekazywania parametrów. Konwencje nazewnictwa i wywoływania są różne dla poszczególnych platform.
Minimalny wymagany zestaw funkcji to funkcje administracyjne GetFunctionCount i GetFunctionData. Umożliwiają one określenie typów funkcji i parametrów oraz wartości zwracanych. Dla wartości zwracanych obsługiwane są typy Double i String. Dla parametrów obsługiwane są także obszary komórek typu Double Array, String Array i Cell Array.
Parametry są przekazywane przez referencje. Oznacza to, że ogólnie zmiana ich wartości jest możliwa. Komponent Lotus Symphony Spreadsheets nie obsługuje jednak takiej operacji, ponieważ nie ma ona sensu w odniesieniu do arkuszy kalkulacyjnych.
Biblioteki można przeładować w czasie wykonywania, a ich zawartość można analizować przy użyciu funkcji administracyjnych. Dla każdej funkcji jest dostępna informacja o liczbie i typach parametrów, zewnętrzna i wewnętrzna nazwa funkcji oraz liczba administracyjna.
Funkcje są wywoływane synchronicznie i natychmiast zwracają wyniki. Stosowanie funkcji czasu rzeczywistego (funkcji asynchronicznych) jest także możliwe, jednak nie są one opisane szczegółowo ze względu na ich złożoność.
Maksymalna liczba parametrów funkcji programu dodatkowego przyłączonego do komponentu Lotus Symphony Spreadsheets to 16, w tym jedna wartość zwracana i maksymalnie 15 parametrów wejściowych funkcji.
Typy danych są zdefiniowane w następujący sposób:
Typ danych | Definicja |
---|---|
CALLTYPE | W systemie Windows: FAR PASCAL (_far _pascal) Inne: domyślnie (wartość domyślna specyficzna dla systemu operacyjnego) |
USHORT | 2-bajtowa liczba całkowita bez znaku typu Byte |
DOUBLE | 8-bajtowy format zależny od platformy |
Paramtype | Format zależny od platformy, taki jak int PTR_DOUBLE =0 wskaźnik do typu double PTR_STRING =1 wskaźnik do łańcucha zakończonego wartością zerową PTR_DOUBLE_ARR =2 wskaźnik do typu double array PTR_STRING_ARR =3 wskaźnik do typu string array PTR_CELL_ARR =4 wskaźnik do typu cell array NONE =5 |
Poniżej znajdują się opisy funkcji wywoływanych w zewnętrznej bibliotece DLL.
Dla wszystkich funkcji biblioteki DLL stosuje się następujący opis:
void CALLTYPE fn(wy, we1, we2, ...)
Dane wyjściowe: Wartość wynikowa
Dane wejściowe: Dowolna liczba wartości typów (double&, char*, double*, char**, Obszar komórek), gdzie Obszar komórek to tablica typu double array, string array lub cell array.
Powoduje zwrócenie liczby funkcji bez uwzględniania funkcji zarządzających parametru referencji. Każda funkcja ma unikalny numer z zakresu od 0 do nLicznik-1. Ten numer jest później wymagany przez funkcje GetFunctionData oraz GetParameterDescription.
Składnia
void CALLTYPE GetFunctionCount(USHORT& nLicznik)
Parametr
USHORT &nLicznik:
Dane wyjściowe: Referencja do zmiennej, która zawiera informację o liczbie funkcji programu dodatkowego. Jeśli na przykład program dodatkowy udostępnia 5 funkcji komponentowi Lotus Symphony Spreadsheets, zwracana jest wartość nLicznik=5.
Określa wszystkie ważne informacje dotyczące funkcji programu dodatkowego.
Składnia
void CALLTYPE GetFunctionData(USHORT& nNr, char* pNazwaFunkcji, USHORT& nLicznikParametrow, Paramtype* peTyp, char* pNazwaWewnetrzna)
Parametr
USHORT& nNr:
Dane wejściowe: Numer funkcji z domkniętego przedziału od 0 do nLicznik -1.
char* pNazwaFunkcji:
Dane wyjściowe: Nazwa funkcji widziana przez programistę, określona w bibliotece DLL. Ta nazwa nie określa nazwy używanej w kreatorze funkcji.
USHORT& nLicznikParametrow:
Wyjście: Liczba parametrów funkcji programu dodatkowego. Ta liczba musi być większa od 0, ponieważ wartość wynikowa występuje zawsze. Wartość maksymalna to 16.
Paramtype* peTyp:
Wyjście: Wskaźnik do tablicy dokładnie 16 zmiennych typu Paramtype. Na pierwszych nLicznikParametrow pozycjach znajdują się odpowiednie typy parametrów.
char* pNazwaWewnetrzna:
Wyjście: Nazwa funkcji widziana przez użytkownika, widoczna w kreatorze funkcji. Może zawierać znaki umlaut.
Parametry pNazwaFunkcji i pNazwaWewnetrzna są tablicami znaków. Wielkość ich implementacji w komponencie Lotus Symphony Spreadsheets wynosi 256.
Udostępnia krótki opis funkcji programu dodatkowego i jej parametrów. Opcjonalnie można tej funkcji użyć do wyświetlenia opisu funkcji i parametrów w kreatorze funkcji.
Składnia
void CALLTYPE GetParameterDescription(USHORT& nNr, USHORT& nParametr, char* pNazwa, char* pOpis)
Parametr
USHORT& nNr:
Dane wejściowe: Liczba funkcji w bibliotece z zakresu od 0 do nLicznik-1.
USHORT& nParametr:
Dane wejściowe: Określa parametr, którego opis jest udostępniany. Parametry numerowane są od 1. Jeśli wartość nParametr jest równa 0, sam opis jest podawany w parametrze pOpis. W takim przypadku parametr pNazwa nie ma znaczenia.
char* pNazwa:
Dane wyjściowe: Przyjmuje nazwę lub typ parametru, na przykład słowo "Number", "String" lub "Date" itd. Typ tego parametru zaimplementowanego w komponencie Lotus Symphony Spreadsheets to char[256].
char* pOpis:
Dane wyjściowe: Przyjmuje wartość opisu parametru, na przykład „Wartość, dla której zostanie obliczony wszechświat”. Typ tego parametru zaimplementowanego w komponencie Lotus Symphony Spreadsheets to char[256].
Parametry pNazwa i pOpis są tablicami znaków. Ich implementacja w komponencie Lotus Symphony Spreadsheets ma wielkość 256. Należy zwrócić uwagę na ograniczoną dostępność miejsca w kreatorze funkcji, która uniemożliwia pełne wykorzystanie 256 znaków.
Następująca tabela zawiera informacje o strukturach danych, które musi udostępnić zewnętrzny moduł programu w celu przekazania obszarów komórek. Komponent Lotus Symphony Spreadsheets rozróżnia trzy typy tablic w zależności od typu danych.
Jako parametr można przekazać obszar komórek zawierający wartości typu Number/Double. Tablica wartości podwójnej precyzji jest zdefiniowana w komponencie Lotus Symphony Spreadsheets następująco:
Przesunięcie | Nazwa | Opis |
---|---|---|
0 | Col1 | Numer kolumny w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
2 | Row1 | Numer wiersza w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
4 | Tab1 | Numer tabeli w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
6 | Col2 | Numer kolumny w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
8 | Row2 | Numer wiersza w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
10 | Tab2 | Numer tabeli w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
12 | Count | Liczba następujących elementów. Puste komórki nie są zliczane ani przekazywane. |
14 | Col | Numer kolumny elementu. Numeracja rozpoczyna się od 0. |
16 | Row | Numer wiersza elementu. Numeracja rozpoczyna się od 0. |
18 | Tab | Numer tabeli elementu. Numeracja rozpoczyna się od 0. |
20 | Error | Numer błędu, przy czym wartość 0 oznacza brak błędu. Jeśli element pochodzi z komórki formuły, wartość błędu jest określona przez formułę. |
22 | Value | Zmienna 8-bajtowa zgodna ze standardem IEEE, podwójnej precyzji/zmiennopozycyjna. |
30 | ... | Następny element |
Obszar komórek zawierający wartości typu Text, przekazywany jako tablica łańcuchów. Tablica łańcuchów jest zdefiniowana w komponencie Lotus Symphony Spreadsheets produktu Lotus Symphony następująco:
Przesunięcie | Nazwa | Opis |
---|---|---|
0 | Col1 | Numer kolumny w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
2 | Row1 | Numer wiersza w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
4 | Tab1 | Numer tabeli w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
6 | Col2 | Numer kolumny w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
8 | Row2 | Numer wiersza w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
10 | Tab2 | Numer tabeli w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
12 | Count | Liczba następujących elementów. Puste komórki nie są zliczane ani przekazywane. |
14 | Col | Numer kolumny elementu. Numeracja rozpoczyna się od 0. |
16 | Row | Numer wiersza elementu. Numeracja rozpoczyna się od 0. |
18 | Tab | Numer tabeli elementu. Numeracja rozpoczyna się od 0. |
20 | Error | Numer błędu, przy czym wartość 0 oznacza brak błędu. Jeśli element pochodzi z komórki formuły, wartość błędu jest określona przez formułę. |
22 | Len | Długość następującego łańcucha, włącznie z kończącym bajtem o wartości zero. Jeśli długość uwzględniająca kończący bajt o wartości zero jest nieparzysta, do łańcucha jest dodawany kolejny bajt o wartości zero, aby otrzymać długość parzystą. Z tego powodu wartość Len jest obliczana jako ((StrLen+2)&~1). |
24 | String | Łańcuch z kończącym bajtem zerowym |
24+Len | ... | Następny element |
Tablice komórek umożliwiają wywoływanie obszarów komórek zawierających tekst oraz liczby. Tablica komórek jest zdefiniowana w komponencie Lotus Symphony Spreadsheets następująco:
Przesunięcie | Nazwa | Opis |
---|---|---|
0 | Col1 | Numer kolumny w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
2 | Row1 | Numer wiersza w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
4 | Tab1 | Numer tabeli w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
6 | Col2 | Numer kolumny w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
8 | Row2 | Numer wiersza w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
10 | Tab2 | Numer tabeli w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0. |
12 | Count | Liczba następujących elementów. Puste komórki nie są zliczane ani przekazywane. |
14 | Col | Numer kolumny elementu. Numerowanie rozpoczyna się od 0. |
16 | Row | Numer wiersza elementu. Numeracja rozpoczyna się od 0. |
18 | Tab | Numer tabeli elementu. Numeracja rozpoczyna się od 0. |
20 | Error | Numer błędu, przy czym wartość 0 oznacza brak błędu. Jeśli element pochodzi z komórki formuły, wartość błędu jest określona przez formułę. |
22 | Type | Typ zawartości komórki, 0 == Double, 1 == String. |
24 | Value lub Len | Jeśli Type == 0: Zmienna 8-bajtowa zgodna ze standardem IEEE, podwójnej precyzji/zmiennopozycyjna. Jeśli Type == 1: Długość następującego łańcucha, włącznie z kończącym bajtem o wartości zero. Jeśli długość uwzględniająca kończący bajt o wartości zero jest nieparzysta, do łańcucha jest dodawany kolejny bajt o wartości zero, aby otrzymać długość parzystą. Z tego powodu wartość Len jest obliczana jako ((StrLen+2)&~1). |
26 jeśli Typ==1 | String | Jeśli Type == 1: Łańcuch z kończącym bajtem zerowym |
32 lub 26+Len | ... | Następny element |