Spis treści

# Biblioteka ScriptForge

Aby wykonać tę operację...

Otwórz Narzędzia - Makra - LibreOffice Basic - Edycja i wybierz kontener Makra aplikacji.

Biblioteki ScriptForge tworzą rozszerzalną kolekcję zasobów skryptów makr dla LibreOffice, które mogą być wywoływane z podstawowych makr lub skryptów Pythona.

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

Aby dowiedzieć się więcej o tworzeniu i wykonywaniu skryptów w języku Python przy użyciu biblioteki ScriptForge, przeczytaj stronę pomocy Tworzenie skryptów w języku Python za pomocą ScriptForge.

## Wywoływanie usług ScriptForge

Opisane moduły i klasy są wywoływane ze skryptów użytkownika jako „Usługi”. W tym celu dla każdego języka został zaprojektowany ogólny konstruktor tych usług.

Metoda Dispose jest dostępna we wszystkich usługach i należy ją wywołać w celu zwolnienia zasobów po użyciu:

##### W języku Basic

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Set oSvc = CreateScriptService("servicename"[, arg0, arg1, ...])
        ' ...
        oSvc.Dispose()

##### W języku Python

        from scriptforge import CreateScriptService
        svc = CreateScriptService('servicename'[, arg0, arg1, ...])
        # ...
        svc.Dispose()

## Usługi świadczone przez bibliotekę ScriptForge

Kategoria | Usługi
--- | ---
LibreOffice Basic | Array Dictionary | Exception FileSystem | String TextStream
Treść dokumentu | Base Calc Chart | Database Dataset Datasheet | Document FormDocument Writer
Interfejs użytkownika | Dialog DialogControl Form | FormControl Menu PopupMenu | Toolbar ToolbarButton UI
Narzędzia | Basic L10N Platform | Region Services Session | Timer UnitTest

## Usługa ScriptForge.Array

Udostępnia zbiór metod służących do manipulowania i przekształcania tablic jednego wymiaru (wektorów) i tablic dwuwymiarowych (macierzy). Obejmuje to operacje na zestawach, sortowanie, importowanie i eksportowanie do plików tekstowych.

Tablice o więcej niż dwóch wymiarach nie mogą być używane z metodami w tej usłudze, jedynym wyjątkiem jest metoda CountDims, która akceptuje tablice o dowolnej liczbie wymiarów.

## Usługa SFDocuments.Base

Usługa Base zapewnia szereg metod i właściwości ułatwiających zarządzanie i obsługę dokumentów LibreOffice Base.

Ta usługa jest ściśle powiązana z usługą Document, która zapewnia ogólne metody obsługi dokumentów LibreOffice, w tym dokumentów Base. W związku z tym usługa Base rozszerza usługę Document i udostępnia dodatkowe metody, specyficzne dla dokumentów Base, umożliwiające użytkownikom:

- Uzyskiwanie dostępu do bazy danych zawartej w dokumencie Base.

- Otwieranie dokumentów formularzy przechowywanych w dokumencie Base.

- Sprawdzanie, czy dokument formularza z dokumentu Base jest aktualnie załadowany.

## Usługa ScriptForge.Basic

Usługa ScriptForge.Basic proponuje kolekcję podstawowych metod LibreOffice do wykonania w kontekście języka Python. Metody usługi Basic odtwarzają dokładną składnię i zachowanie wbudowanych funkcji języka Basic.

## Usługa SFDocuments.Calc

Biblioteka współdzielona SFDocuments udostępnia szereg metod i właściwości ułatwiających zarządzanie i obsługę dokumentów LibreOffice.

Usługa SFDocuments.Calc jest podklasą usługi SFDocuments.Document. Dostęp do wszystkich metod i właściwości zdefiniowanych dla usługi Document można również uzyskać za pomocą instancji usługi Calc.

Usługa Calc koncentruje się na:

- Obsłudze arkuszy w dokumencie programu Calc (kopiowanie, wstawianie, przenoszenie itp.)

- Wymianie danych pomiędzy podstawowymi strukturami danych a zakresami Calc

- Kopiowaniu i importowaniu ogromnych ilości danych

## Usługa SFDocuments.Chart

Usługa Chart udostępnia zestaw właściwości i metod obsługi wykresów w dokumentach programu Calc. Dzięki tej usłudze możliwe jest:

- Uzyskanie dostępu do obiektów wykresów w dokumentach programu Calc i manipulowanie ich właściwościami.

- Tworzenie i wstawianie nowych wykresów do dokumentu Calc.

- Eksportowanie wykresów jako pliki obrazów.

## Usługa SFDatabases.Database

Usługa Database zapewnia dostęp do baz danych osadzonych lub opisanych w dokumentach Base. Usługa ta zapewnia metody umożliwiające:

- Uzyskanie dostępu do danych w tabelach bazy danych.

- Uruchamianie kwerendy SELECT i wykonywanie funkcji agregujących.

- Uruchamianie instrukcji działania SQL, takich jak INSERT, UPDATE, DELETE itp.

## Usługa SFDatabases.Dataset

Usługa Dataset służy do reprezentowania danych tabelarycznych generowanych przez bazę danych. Dzięki tej usłudze możliwe jest:

- Nawigowanie i uzyskiwanie dostępu do danych w zestawie danych.

- Aktualizowanie, wstawianie i usuwanie rekordów w zestawie danych.

## Usługa SFDatabases.Datasheet

Usługa Datasheet pozwala na wizualizację zawartości tabel bazy danych oraz wyników kwerend i instrukcji SQL za pomocą widoku danych Base. Dodatkowo usługa ta umożliwia:

- Dodaj niestandardowe menu do widoku danych.

- Dostęp do wartości w określonych pozycjach widoku danych.

- Ustaw kursor w określonej komórce widoku danych.

## Usługa SFDialogs.Dialog

Usługa Dialog umożliwia zarządzanie oknami dialogowymi utworzonymi za pomocą Edytora okien dialogowych Basic lub oknami dialogowymi utworzonymi w locie. Każde wystąpienie bieżącej klasy reprezentuje pojedyncze okno dialogowe wyświetlane użytkownikowi.

## Usługa SFDialogs.DialogControl

Usługa DialogControl zarządza formantami należącymi do okna dialogowego zdefiniowanego za pomocą edytora okien dialogowych Basic. Każde wystąpienie bieżącej usługi reprezentuje pojedynczy formant w oknie dialogowym.

Usługa koncentruje się na pobieraniu i ustawianiu wartości wyświetlanych w formantach okna. Elementy można formatować za pomocą właściwości XControlModel i XControlView.

Należy pamiętać, że zawartość unikalnej właściwości DialogControl.Value różni się w zależności od typu formantu.

Szczególną uwagę zwrócono na formantu kontroli drzewa typów. Łatwo jest obsadzić drzewo, albo gałąź po gałęzi, albo zestawem gałęzi na raz. Wypełnianie formantu drzewa może odbywać się statycznie lub dynamicznie.

## Usługa ScriptForge.Dictionary

Słownik to zbiór par klucz-element

- Klucz jest ciągiem znaków, w którym nie jest rozróżniana wielkość liter

- Elementy mogą być dowolnego typu

## Usługa SFDocuments.Document

Biblioteka SFDocuments udostępnia metody i właściwości ułatwiające zarządzanie dokumentami LibreOffice i manipulowanie nimi.

Metody mające zastosowanie do wszystkich typów dokumentów (dokumenty tekstowe, arkusze, prezentacje itp.) udostępnia usługa SFDocuments.Document. Oto kilka przykładów:

- Otwieranie, zamykanie i zapisywanie dokumentów

- Dostęp do standardowych lub niestandardowych właściwości dokumentów

## Usługa ScriptForge.Exception

Usługa Exception to zbiór metod wspomagających debugowanie kodu w skryptach Basic i Python oraz obsługę błędów w skryptach Basic.

W skryptach Basic, gdy wystąpi błąd wykonania, metody i właściwości usługi Exception pomagają zidentyfikować kontekst błędu i pozwalają go obsłużyć.

## Usługa ScriptForge.FileSystem

Usługa FileSystem zawiera procedury do obsługi plików i folderów. Poniżej znajduje się kilka przykładów funkcji udostępnianych przez tę usługę:

- Sprawdź, czy plik lub folder istnieje.

- Twórz i usuwaj foldery oraz pliki.

- Uruchom okna dialogowe, aby otworzyć/zapisać pliki.

- Uzyskaj dostęp do listy plików w folderze itp.

## Usługa SFDocuments.Form

Usługa Form udostępnia metody i właściwości umożliwiające zarządzanie formularzami w dokumentach LibreOffice. Usługa obsługuje formularze w dokumentach Base, Calc i Writer oraz pozwala na:

- Otwieranie i aktywowanie formularzy.

- Nawigowanie pomiędzy rekordami wyświetlanymi w formularzu.

- Uzyskiwanie dostępu do formantów znajdujących się w formularzu.

- Uzyskiwanie dostępu do podformularzy formularza nadrzędnego.

## Usługa SFDocuments.FormControl

Usługa FormControl zapewnia dostęp do formantów należących do formularza, podformularza lub formantów tabeli FormDocument. Każda instancja usługi FormControl odnosi się do pojedynczego formantu w formularzu. Usługa ta umożliwia użytkownikom:

- Pobieranie i ustawianie właściwości formantu reprezentowanego przez instancję FormControl.

- Uzyskanie dostępu do bieżącej wartości wyświetlanej przez formant.

- Ustawienie fokusu na żądanym formancie.

## Usługa SFDocument.FormDocument

Usługa FormDocument umożliwia dostęp do dokumentów formularzy przechowywanych w dokumentach LibreOffice Base.

W dokumencie Base istniejące dokumenty formularzy można przeglądać, wybierając Widok - Formularze w interfejsie użytkownika. Każdy dokument formularza może składać się z jednego lub większej liczby formularzy, w tym formularza głównego i innych formularzy podrzędnych.

## Usługa ScriptForge.L10N

Usługa ta udostępnia szereg metod związanych z tłumaczeniem ciągów znaków przy minimalnym wpływie na kod źródłowy programu. Metody udostępniane przez usługę L10N można wykorzystać głównie do:

- Tworzenia plików POT, które można wykorzystać jako szablony do tłumaczenia wszystkich ciągów znaków w programie.

- Uzyskania przetłumaczonych ciągów znaków w czasie wykonywania dla języka zdefiniowanego we właściwości Locale.

## Usługa SFWidgets.Menu

Usługa Menu może być używana do tworzenia i usuwania menu z paska menu okna dokumentu LibreOffice. Każda pozycja menu może być powiązana ze skryptem lub poleceniem UNO. Ta usługa zapewnia następujące możliwości:

- Tworzenie menu z niestandardowymi wpisami, polami wyboru, przyciskami opcji i separatorami.

- Dodanie ikon i podpowiedzi do pozycji menu.

## Usługa ScriptForge.Platform

Usługa Platform zawiera zbiór właściwości na temat bieżącego środowiska i kontekstu wykonania, takich jak:

- Platforma sprzętowa (architektura, liczba procesorów, typ maszyny itp.)

- Informacje o systemie operacyjnym (typ systemu operacyjnego, wydanie, wersja itp.)

- Wersja LibreOffice

- Nazwa bieżącego użytkownika

## Usługa SFWidgets.PopupMenu

Usługa PopupMenu może zostać wykorzystana do tworzenia wyskakujących menu, które można powiązać ze zdarzeniami lub wykonać za pomocą skryptów. Ta usługa zapewnia następujące możliwości:

- Tworzenie wyskakujących menu z niestandardowymi wpisami, polami wyboru i przyciskami radiowymi.

- Dodanie ikon i podpowiedzi do pozycji menu.

## Usługa ScriptForge.Region

Usługa Region udostępnia zbiór właściwości i metod do obsługi lokalnych i regionalnych aspektów programowania, takich jak:

- Dostęp do ustawień regionalnych i zależnych od regionu, takich jak formatowanie liczb, waluta i strefy czasowe.

- Konwersja stref czasowych i obliczanie przesunięcia czasu letniego (DST).

- Przekształcanie liczb w tekst w dowolnym obsługiwanym języku.

## Usługa ScriptForge.Services

Głównym celem modułu Services jest zapewnienie dostępu do metody CreateScriptService, którą można wywołać w skryptach użytkownika w celu utworzenia instancji usług zaimplementowanych przy użyciu frameworka ScriptForge.

## Usługa ScriptForge.Session

Usługa Session gromadzi różne metody ogólnego przeznaczenia dotyczące:

- środowiska instalacji lub wykonania

- eksploracji obiektów UNO

- wywoływania zewnętrznych skryptów lub programów

## Usługa ScriptForge.String

Usługa String udostępnia zbiór metod przetwarzania ciągów. Metody te można wykorzystać do:

- Sprawdzania zawartości ciągów

- Formatowania ciągów znaków, przycinając, justując lub zawijając ich zawartość

- Używania wyrażeń regularnych, aby wyszukiwać i zamieniać podciągi

- Stosowania algorytmu mieszającego na ciągach znaków itp.

## Usługa ScriptForge.TextStream

Usługa TextStream służy do sekwencyjnego odczytu i zapisu do plików otwartych lub utworzonych za pomocą usługi ScriptForge.FileSystem.

Metody OpenTextFile i CreateTextFile z usługi FileSystem zwracają instancję usługi TextStream.

## Usługa ScriptForge.Timer

Usługa Timer mierzy ilość czasu potrzebnego na uruchomienie skryptów użytkownika.

Timer mierzy czas trwania. To może być:

- Rozpoczęcie, aby wskazać, kiedy rozpocząć pomiar czasu.

- Wstrzymanie, aby wstrzymać odmierzanie czasu pracy.

- Wznowienie, aby kontynuować śledzenie czasu działania po zawieszeniu usługi Timer.

- Ponowne uruchomienie, co spowoduje anulowanie poprzednich pomiarów i rozpoczęcie odliczania usługi Timer od zera.

## Usługa SFWidgets.Toolbar

Usługa Toolbar pozwala na pobranie informacji związanych z paskami narzędzi dostępnymi dla konkretnego okna dokumentu. Dzięki tej usłudze możliwe jest:

- Przełączanie widoczności określonych pasków narzędzi.

- Uzyskiwanie dostępu do informacji o przyciskach dostępnych na każdym pasku narzędzi.

## Usługa SFWidgets.ToolbarButton

Usługa ToolbarButton pozwala na pobranie informacji związanych z przyciskami paska narzędzi dostępnymi na danym pasku narzędzi. Dzięki tej usłudze możliwe jest:

- Przełączanie widoczności elementów paska narzędzi.

- Wykonywanie polecenia powiązanego z danym przyciskiem paska narzędzi.

## Usługa ScriptForge.UI

Usługa UI (interfejs użytkownika) upraszcza identyfikację i manipulowanie różnymi oknami tworzącymi całą aplikację LibreOffice:

- Wybór okien

- Przenoszenie i zmiana rozmiaru okien

- Ustawienia paska stanu

- Wyświetlanie pływającego paska postępu

- Tworzenie nowych okien

- Dostęp do podstawowych „dokumentów”

## Usługa SFUnitTests.UnitTest

Usługa UnitTest zapewnia framework do automatyzacji testów jednostkowych z wykorzystaniem języka Basic, obejmujący możliwość:

- Agreguj przypadki testowe w zestawy testów i testy jednostkowe.

- Udostępniaj kod konfiguracji i zamykania pomiędzy przypadkami testowymi.

- Raportuj wyniki testów za pomocą Console.

## Usługa SFDocuments.Writer

Biblioteka współdzielona SFDocuments udostępnia szereg metod i właściwości ułatwiających zarządzanie i obsługę dokumentów LibreOffice.

Niektóre metody są ogólne dla wszystkich typów dokumentów i są dziedziczone z modułu SF_Document, natomiast inne metody, które są specyficzne dla dokumentów programu Writer, są zdefiniowane w module SF_Writer.

Uwaga: inne nieopisane moduły ScriptForge są zarezerwowane do użytku wewnętrznego. Ich treść może ulec zmianie bez powiadomienia.

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.