Spis treści
Indeks 🔎︎

# 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

Ta strona pomocy opisuje metody i właściwości, które mają zastosowanie tylko do dokumentów programu Calc.

## Wywoływanie usługi

Przed użyciem usługi Calc należy załadować lub zaimportować bibliotekę ScriptForge:

• 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

Usługa Calc jest ściśle powiązana z usługą UI biblioteki ScriptForge. Poniżej znajduje się kilka przykładów, jak można wywołać usługę Calc.

##### W języku Basic

Poniższy fragment kodu tworzy instancję usługi Calc odpowiadającą aktualnie aktywnemu dokumentowi Calc.

        Set oDoc = CreateScriptService("Calc")

Innym sposobem na utworzenie instancji usługi Calc jest użycie usługi UI. W poniższym przykładzie tworzony jest nowy dokument programu Calc, a oDoc jest instancją usługi Calc:

        Dim ui As Object, oDoc As Object
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.CreateDocument("Calc")

Lub używając metody OpenDocument z usługi UI:

        Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")

Możliwe jest również utworzenie instancji usługi Calc, określając nazwę okna dla metody CreateScriptService:

        Dim oDoc As Object
        Set oDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")

W powyższym przykładzie „MyFile.ods” to nazwa otwartego okna dokumentu. Jeśli ten argument nie zostanie podany, uwzględniane jest aktywne okno.

Możliwe jest również wywołanie usługi Calc za pomocą dokumentu, do którego odwołuje się ThisComponent. Jest to szczególnie przydatne podczas uruchamiania makr z IDE Basic.

        Dim oDoc As Object
        Set oDoc = CreateScriptService("Calc", ThisComponent)

Zaleca się zwolnienie zasobów po użyciu:

        Set oDoc = oDoc.Dispose()

Jeśli jednak dokument został zamknięty przy użyciu metody CloseDocument, zwalnianie zasobów za pomocą opisanej powyżej komendy staje się niepotrzebne.

##### W języku Python

        myDoc = CreateScriptService("Calc")

        ui = CreateScriptService("UI")
        myDoc = ui.CreateDocument("Calc")

        myDoc = ui.OpenDocument(r"C:\Documents\MyFile.ods")

        myDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")
        myDoc.Dispose()

        bas = CreateScriptService("Basic")
        myDoc = CreateScriptService("Calc", bas.ThisComponent)

Użycie prefiksu "SFDocuments." podczas wywoływania usługi jest opcjonalne.

## Definicje

Wiele metod wymaga argumentu "Sheet" lub "Range". Pojedyncze komórki są uważane za szczególny przypadek Range.

Obie mogą być wyrażone jako ciąg znaków lub jako odniesienie (= obiekt) w zależności od sytuacji:

- W konkretnej instancji usługi Calc arkusze i zakresy są określane jako ciągi znaków, na przykład "Sheet1" i "D2:F6".

- Dodatkowo właściwości .Sheet i .Range zwracają odniesienie, które można użyć jako argumentu metody wywołanej z innej instancji metody usługi Calc.

### Przykład:

Poniższy przykład kopiuje dane z dokumentu A (otwartego tylko do odczytu i ukrytego) do dokumentu B.

##### W języku Basic

        Dim oDocA As Object, oDocB As Object
        Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
        Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
        oDocB.CopyToRange(oDocA.Range("SheetX.D4:F8"), "D2:F6") 'CopyToRange(source, target)

##### W języku Python

        docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = ui.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopyToRange(docA.Range("SheetX.D4:F8"), "D2:F6")

### SheetName

Albo nazwa arkusza jako string, albo object utworzony przez właściwość .Sheet.

Skrót „~” (tylda) reprezentuje bieżący arkusz.

### RangeName

Ciąg określający zestaw ciągłych komórek znajdujących się w arkuszu bieżącej instancji lub object utworzony przez właściwość .Range.

Skrót „~” (tylda) reprezentuje bieżący wybór lub pierwszy wybrany zakres, jeśli wybrano wiele zakresów.

Skrót „*” reprezentuje wszystkie używane komórki.

Nazwa arkusza jest opcjonalna podczas definiowania zakresu. Jeśli nie podano nazwy arkusza, używany jest arkusz aktywny. Otaczające pojedyncze cudzysłowy i znaki $ są dozwolone, ale są ignorowane.

Podczas określania SheetName jako łańcucha, wymagane jest użycie pojedynczych cudzysłowów w celu umieszczenia nazwy arkusza, jeśli nazwa zawiera spacje " " lub kropki ".".

Poniższe przykłady ilustrują, w jakich przypadkach stosowanie pojedynczych cudzysłowów jest obowiązkowe:

          ' Użycie pojedynczych cudzysłowów jest opcjonalne
          oDoc.clearAll("SheetA.A1:B10")
          oDoc.clearAll("'SheetA'.A1:B10")
          ' Użycie pojedynczych cudzysłowów jest wymagane
          oDoc.clearAll("'Sheet.A'.A1:B10")

Z wyjątkiem właściwości CurrentSelection, usługa Calc uwzględnia tylko pojedyncze zakresy komórek.

Przykłady prawidłowych zakresów
1) $'SheetX'.D2 2) $D$2 | Pojedyncza komórka
1) $'SheetX'.D2:F6 2) D2:D10 | Pojedynczy zakres z wieloma komórkami
$'SheetX'.* | Wszystkie użyte komórki w danym arkuszu
1) $'SheetX'.A:A (kolumna A) 2) 3:5 (rzędy 3 do 5) | Wszystkie komórki w ciągłych kolumnach lub wierszach aż do ostatniej użytej komórki
myRange | Zakres o nazwie „myRange” na poziomie arkusza kalkulacyjnego
1) ~.someRange 2) SheetX.someRange | Nazwa zakresu na poziomie arkusza
myDoc.Range("SheetX.D2:F6") | Zakres w arkuszu SheetX w pliku powiązanym z instancją myDoc Calc
~.~ lub ~ | Bieżący wybór w aktywnym arkuszu

## Właściwości

Wszystkie właściwości ogólne dowolnego dokumentu mają niejawne zastosowanie również do dokumentów programu Calc. Aby uzyskać więcej informacji, przeczytaj stronę pomocy usługi Document.

Właściwości dostępne specjalnie dla dokumentów programu Calc to:

Nazwa | Tylko do odczytu | Argument | Typ zwracany | Opis
--- | --- | --- | --- | ---
CurrentSelection | Nie | Brak | Ciąg lub tablica ciągów | Pojedynczy wybrany zakres jako ciąg znaków lub lista wybranych zakresów jako tablica.
FirstCell | Tak | SheetName lub RangeName jako String | String | Zwraca pierwszą użytą komórkę w danym zakresie lub arkuszu.
FirstColumn | Tak | SheetName lub RangeName jako String | Long | Zwraca numer skrajnej lewej kolumny w danym zakresie lub arkuszu.
FirstRow | Tak | SheetName lub RangeName jako String | Long | Zwraca najwyższy numer wiersza w danym zakresie lub arkuszu.
Height | Tak | RangeName jako String | Long | Liczba wierszy (>= 1) w podanym zakresie.
LastCell | Tak | SheetName lub RangeName jako String | String | Zwraca ostatnio używaną komórkę w danym zakresie lub arkuszu.
LastColumn | Tak | SheetName lub RangeName jako String | Long | Ostatnia używana kolumna w danym zakresie lub arkuszu.
LastRow | Tak | SheetName lub RangeName jako String | Long | Ostatni używany wiersz w danym zakresie lub arkuszu.
Range | Tak | RangeName jako String | Object | Odwołanie do zakresu, którego można użyć jako argumentu metod takich jak CopyToRange.
Region | Tak | RangeName jako String | String | Zwraca adres najmniejszego obszaru zawierającego określony zakres, tak aby obszar ten był otoczony pustymi komórkami lub krawędziami arkusza. Jest to równoważne zastosowaniu skrótu Command + *Ctrl + * do podanego zakresu.
Sheet | Tak | SheetName jako String | Object | Odwołanie do zakresu, którego można użyć jako argumentu metod takich jak CopySheet.
SheetName | Tak | RangeName jako String | String | Zwraca nazwę arkusza o podanym adresie zakresu.
Sheets | Tak | Brak | Tablica ciągów | Lista z nazwami wszystkich istniejących arkuszy.
Width | Tak | RangeName jako String | Long | Liczba kolumn (>= 1) w podanym zakresie.
XCellRange | Tak | RangeName jako String | Object | Obiekt UNO com.sun.star.Table.XCellRange.
XSheetCellCursor | Tak | RangeName jako String | Object | Obiekt UNO com.sun.star.sheet.XSheetCellCursor. Po przesunięciu kursora uzyskany adres zakresu jest dostępny poprzez właściwość UNO AbsoluteName obiektu kursora, która zwraca wartość ciągu znaków, która może być użyta jako argument dla właściwości i metod usługi Calc.
XSpreadsheet | Tak | SheetName jako String | Object | Obiekt UNO com.sun.star.sheet.XSpreadsheet.

Odwiedź witrynę dokumentacji API LibreOffice, aby dowiedzieć się więcej o obiektach UNO XCellRange, XSheetCellCursor oraz XSpreadsheet.

## Metody

Lista metod w usłudze Calc
A1Style Activate Charts ClearAll ClearFormats ClearValues CompactLeft CompactUp CopySheet CopySheetFromFile CopyToCell CopyToRange CreateChart CreatePivotTable DAvg | DCount DMax DMin DSum ExportRangeToFile Forms GetColumnName GetFormula GetValue ImportFromCSVFile ImportFromDatabase InsertSheet MoveRange MoveSheet Offset | OpenRangeSelector PrintOut Printf RemoveDuplicates RemoveSheet RenameSheet SetArray SetCellStyle SetFormula SetValue ShiftDown ShiftLeft ShiftRight ShiftUp SortRange

## A1Style

Zwraca adres zakresu jako ciąg na podstawie współrzędnych arkusza, tj. numerów wierszy i kolumn.

Jeśli podano tylko parę współrzędnych, zwracany jest adres do pojedynczej komórki. Dodatkowe argumenty mogą określać prawą dolną komórkę zakresu prostokątnego.

### Składnia:

svc.A1Style(row1: int, column1: int, row2: int = 0; column2: int = 0; sheetname: str = "~"): str

### Parametry:

row1, column1: określ numery wierszy i kolumn w lewej górnej komórce zakresu, który ma być brany pod uwagę. Numery wierszy i kolumn zaczynają się od 1.

row2, column2: określ numery wierszy i kolumn komórki w prawym dolnym rogu zakresu, który ma być brany pod uwagę. Jeśli te argumenty nie zostaną podane lub podane zostaną wartości mniejsze niż row1 i column1, to adres zakresu pojedynczej komórki reprezentowany przez row1 i column1 jest zwracany.

sheetname: nazwa arkusza, który ma zostać dołączony do zwracanego adresu zakresu. Arkusz musi istnieć. Wartość domyślna to „~” odpowiadająca aktualnie aktywnemu arkuszowi.

### Przykład:

Poniższe przykłady w językach Basic i Python uwzględniają, że „Sheet1” jest obecnie aktywnym arkuszem.

##### W języku Basic

        Set oDoc = CreateScriptService("Calc")
        addr1 = oDoc.A1Style(1, 1) ' '$Sheet1'.$A$1
        addr2 = oDoc.A1Style(2, 2, 3, 6) ' '$Sheet1'.$B$2:$F$3
        addr3 = oDoc.A1Style(2, 2, 0, 6) ' '$Sheet1'.$B$2
        addr4 = oDoc.A1Style(3, 4, 3, 8, "Sheet2") ' '$Sheet2'.$D$3:$H$3
        addr5 = oDoc.A1Style(5, 1, SheetName := "Sheet3") ' '$Sheet3'.$A$5

##### W języku Python

        doc = CreateScriptService("Calc")
        addr1 = doc.A1Style(1, 1) # '$Sheet1'.$A$1
        addr2 = doc.A1Style(2, 2, 3, 6) # '$Sheet1'.$B$2:$F$3
        addr3 = doc.A1Style(2, 2, 0, 6) # '$Sheet1'.$B$2
        addr4 = doc.A1Style(3, 4, 3, 8, "Sheet2") # '$Sheet2'.$D$3:$H$3
        addr5 = doc.A1Style(5, 1, sheetname="Sheet3") # '$Sheet3'.$A$5

Metodę A1Style można łączyć z dowolnymi właściwościami i metodami usługi Calc, które wymagają podania zakresu jako argumentu, na przykład GetValue, GetFormula, ClearAll itd.

## Activate

Podanie argumentu sheetname powoduje aktywację danego arkusza i staje się aktualnie wybranym arkuszem. W przypadku braku argumentu okno dokumentu jest aktywowane.

### Składnia:

svc.Activate(sheetname: str = ""): bool

### Parametry:

sheetname: nazwa arkusza, który ma zostać aktywowany w dokumencie. Wartością domyślną jest ciąg pusty, co oznacza, że okno dokumentu zostanie uaktywnione bez zmiany aktywnego arkusza.

### Przykład:

Poniższy przykład aktywuje arkusz o nazwie „Sheet4” w aktualnie aktywnym dokumencie.

##### W języku Basic

        Dim ui as Variant, oDoc as Object
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.GetDocument(ui.ActiveWindow)
        oDoc.Activate("Sheet4")

##### W języku Python

        ui = CreateScriptService("UI")
        myDoc = ui.GetDocument(ui.ActiveWindow)
        myDoc.Activate("Sheet4")

Aktywacja arkusza ma znaczenie tylko w dokumentach programu Calc. Aby upewnić się, że pracujesz z dokumentem programu Calc, użyj właściwości isCalc obiektu dokumentu. Ta właściwość zwraca wartość True, jeśli jest to dokument Calcu, w przeciwnym razie zwraca wartość False.

## Charts

Zwraca listę z nazwami wszystkich obiektów wykresu w danym arkuszu lub pojedynczą instancję usługi Chart.

- Jeśli określono tylko sheetname, zwracana jest liczona od zera tablica łańcuchów zawierająca nazwy wszystkich wykresów.

- Jeśli podano chartname, zwracany jest pojedynczy obiekt odpowiadający żądanemu wykresowi. Określony wykres musi istnieć.

### Składnia:

svc.Charts(sheetname: str, chartname: str = ""): obj

### Parametry:

sheetname: nazwa arkusza, z którego ma zostać pobrana lista wykresów lub w którym znajduje się określony wykres.

chartname: zdefiniowana przez użytkownika nazwa zwracanego obiektu wykresu. Jeżeli wykres nie posiada nazwy zdefiniowanej przez użytkownika, możliwe jest użycie wewnętrznej nazwy obiektu. Jeśli brakuje tego argumentu, zwracana jest lista nazw wykresów na określonym arkuszu.

Użyj paska bocznego Navigator, aby sprawdzić nazwy przypisane do wykresów w kategorii Obiekty OLE.

### Przykład:

##### W języku Basic

Poniższy przykład pokazuje liczbę obiektów wykresu w „Sheet1”.

        Dim arrNames as Object
        arrNames = oDoc.Charts("Sheet1")
        MsgBox "There are " & UBound(arrNames) + 1 & " charts in Sheet1"

Poniższy przykład uzyskuje dostęp do wykresu o nazwie „MyChart” w „Sheet1” i drukuje jego typ.

        Dim oChart as Object
        oChart = oDoc.Charts("Sheet1", "MyChart")
        MsgBox oChart.ChartType

##### W języku Python

        bas = CreateScriptService("Basic")
        chart_names = doc.Charts("Sheet1")
        bas.MsgBox(f"There are {len(chart_names)} charts in Sheet1")

        chart = doc.Charts("Sheet1", "MyChart")
        bas.MsgBox(chart.ChartType)

## ClearAll

Czyści całą zawartość i formaty podanego zakresu.

Można określić formułę filtra, aby ustalić, które komórki mają zostać zmienione.

### Składnia:

svc.ClearAll(range: str, opt filterformula: str, opt filterscope: str)

### Parametry:

range: zakres do wyczyszczenia jako ciąg.

filterformula: formuła Calc, która zostanie zastosowana do podanego zakresu, aby określić, które komórki zostaną naruszone. Określona formuła musi zwracać wartość True lub False. Jeśli ten argument nie zostanie określony, wpłynie to na wszystkie komórki w zakresie.

filterscope: określa, w jaki sposób filterformula jest rozszerzana do podanego zakresu. Ten argument jest obowiązkowy, jeśli podano filterformula. Akceptowane są następujące wartości:

- "CELL": formuła określona w argumencie filterformula jest interpretowana raz dla każdej komórki w range.

- "ROW": formuła określona w argumencie filterformula jest interpretowana raz dla każdego wiersza w range.

- "COLUMN": formuła określona w argumencie filterformula jest interpretowana raz dla każdej kolumny w range.

### Przykład:

##### W języku Basic

        ' Czyści wszystkie komórki w zakresie ArkuszX.A1:J10
        oDoc.ClearAll("ArkuszX.A1:J10")
        ' Czyści wszystkie komórki w zakresie ArkuszX.A1:J10, które mają wartość większą niż 100
        oDoc.ClearAll("ArkuszX.A1:J10", "=ArkuszX.A1>100", "CELL")
        ' Czyści wszystkie wiersze w zakresie ArkuszX.A1:J10, których suma jest większa niż 500
        oDoc.ClearAll("ArkuszX.A1:J10", "=SUM(ArkuszX.A1:J1)>100", "ROW")
        ' Czyści wszystkie kolumny w zakresie ArkuszX.A1:J10, których suma jest większa niż 500
        oDoc.ClearAll("ArkuszX.A1:J10", "=SUM(ArkuszX.A1:A10)>100", "COLUMN")

##### W języku Python

        myDoc.ClearAll("ArkuszX.A1:F10")
        myDoc.ClearAll("ArkuszX.A1:J10", "=ArkuszX.A1>100", "CELL")
        myDoc.ClearAll("ArkuszX.A1:J10", "=SUM(ArkuszX.A1:J1)>100", "ROW")
        myDoc.ClearAll("ArkuszX.A1:J10", "=SUM(ArkuszX.A1:A10)>100", "COLUMN")

## ClearFormats

Czyści formaty i style w podanym zakresie.

Można określić formułę filtra, aby ustalić, które komórki mają zostać zmienione.

### Składnia:

svc.ClearFormats(range: str, opt filterformula: str, opt filterscope: str)

### Parametry:

range: zakres, którego formaty i style mają zostać wyczyszczone, jako ciąg.

filterformula: formuła Calc, która zostanie zastosowana do podanego zakresu, aby określić, które komórki zostaną naruszone. Określona formuła musi zwracać wartość True lub False. Jeśli ten argument nie zostanie określony, wpłynie to na wszystkie komórki w zakresie.

filterscope: określa, w jaki sposób filterformula jest rozszerzana do podanego zakresu. Ten argument jest obowiązkowy, jeśli podano filterformula. Akceptowane są następujące wartości:

- "CELL": formuła określona w argumencie filterformula jest interpretowana raz dla każdej komórki w range.

- "ROW": formuła określona w argumencie filterformula jest interpretowana raz dla każdego wiersza w range.

- "COLUMN": formuła określona w argumencie filterformula jest interpretowana raz dla każdej kolumny w range.

### Przykład:

##### W języku Basic

          oDoc.ClearFormats("SheetX.*")

##### W języku Python

        myDoc.ClearFormats("SheetX.*")

Zapoznaj się z dokumentacją metody ClearAll, aby zaznajomić się z przykładami użycia argumentów filterformula i filterscope.

## ClearValues

Czyści wartości i formuły w podanym zakresie.

Można określić formułę filtra, aby ustalić, które komórki mają zostać zmienione.

### Składnia:

svc.ClearValues(range: str, opt filterformula: str, opt filterscope: str)

### Parametry:

range: zakres, którego wartości i formuły mają zostać wyczyszczone, jako ciąg znaków.

filterformula: formuła Calc, która zostanie zastosowana do podanego zakresu, aby określić, które komórki zostaną naruszone. Określona formuła musi zwracać wartość True lub False. Jeśli ten argument nie zostanie określony, wpłynie to na wszystkie komórki w zakresie.

filterscope: określa, w jaki sposób filterformula jest rozszerzana do podanego zakresu. Ten argument jest obowiązkowy, jeśli podano filterformula. Akceptowane są następujące wartości:

- "CELL": formuła określona w argumencie filterformula jest interpretowana raz dla każdej komórki w range.

- "ROW": formuła określona w argumencie filterformula jest interpretowana raz dla każdego wiersza w range.

- "COLUMN": formuła określona w argumencie filterformula jest interpretowana raz dla każdej kolumny w range.

### Przykład:

##### W języku Basic

          oDoc.ClearValues("SheetX.A1:F10")

##### W języku Python

        myDoc.ClearValues("SheetX.A1:F10")

Zapoznaj się z dokumentacją metody ClearAll, aby zaznajomić się z przykładami użycia argumentów filterformula i filterscope.

## CompactLeft

Usuwa kolumny z określonego zakresu, które pasują do filtru wyrażonego jako formuła Calc. Filtr jest stosowany do każdej kolumny, aby zdecydować, czy zostanie ona usunięta, czy nie.

Usuniętą kolumnę można ograniczyć do wysokości podanego zakresu lub rozpiętości do wysokości całego arkusza, usuwając tym samym całe kolumny.

Ta metoda zwraca ciąg z adresem zakresu skompaktowanego zakresu. Jeśli wszystkie kolumny zostaną usunięte, zwracany jest pusty ciąg.

Jeśli zaznaczony jest zakres komórek, wywołanie tej metody nie wpłynie na zaznaczenie.

### Składnia:

svc.CompactLeft(range: str, wholecolumn: bool = False, opt filterformula: str): str

### Parametry:

range: zakres, z którego kolumny zostaną usunięte, jako ciąg.

wholecolumn: jeśli ta opcja jest ustawiona na True, cała kolumna zostanie usunięta z arkusza. Domyślną wartością jest False, co oznacza, że usunięta kolumna będzie ograniczona do wysokości podanego range.

filterformula: filtr, który ma zostać zastosowany do każdej kolumny, aby określić, czy zostanie ona usunięta. Filtr jest wyrażony jako formuła Calc, którą należy zastosować do pierwszej kolumny. Gdy formuła zwróci wartość True dla kolumny, ta kolumna zostanie usunięta. Domyślny filtr usuwa wszystkie puste kolumny.

Załóżmy na przykład, że wybrano zakres A1:J200 (wysokość = 200), więc domyślna formuła to =(LICZ.PUSTE(A1:A200)=200). Oznacza to, że jeśli wszystkie 200 komórek jest pustych w pierwszej kolumnie (Kolumna A), kolumna jest usuwana. Zauważ, że formuła jest wyrażona tylko w odniesieniu do pierwszej kolumny. Wewnętrznie metoda CompactLeft uogólni tę formułę dla wszystkich pozostałych kolumn.

Funkcje Calc użyte w argumencie filterformula muszą być wyrażone przy użyciu ich angielskich nazw. Odwiedź stronę wiki List of Calc Functions, aby uzyskać pełną listę funkcji Calc w języku angielskim.

### Przykład:

##### W języku Basic

        ' Usuń wszystkie puste kolumny w zakresie G1:L10 z Sheet1
        newrange = oDoc.CompactLeft("Sheet1.G1:L10")
        ' Poniższy przykład jest podobny, ale cała kolumna jest usuwana z arkusza
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", WholeColumn := True)
        ' Usuwa wszystkie kolumny, w których pierwszy wiersz jest oznaczony znakiem "X"
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Usuwa wszystkie kolumny, w których suma wartości w kolumnie jest nieparzysta
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")

##### W języku Python

        newrange = myDoc.CompactLeft("Sheet1.G1:L10")
        newrange = myDoc.CompactLeft("Sheet1.G1:L10", wholecolumn = True)
        newrange = myDoc.CompactLeft("Sheet1.G1:L10", filterformula = '=(G1="X")')
        newrange = myDoc.CompactLeft("Sheet1.G1:L10", filterformula = '=(MOD(SUM(G1:G10);2)=1)')

## CompactUp

Usuwa wiersze z określonego zakresu, które pasują do filtra wyrażonego jako formuła programu Calc. Filtr jest stosowany do każdego wiersza, aby zdecydować, czy zostanie on usunięty, czy nie.

Usunięte wiersze można ograniczyć do szerokości określonego zakresu lub rozpiętości do szerokości całego arkusza, usuwając tym samym całe wiersze.

Ta metoda zwraca ciąg z adresem zakresu skompaktowanego zakresu. Jeśli wszystkie wiersze zostaną usunięte, zwracany jest pusty ciąg.

Jeśli zaznaczony jest zakres komórek, wywołanie tej metody nie wpłynie na zaznaczenie.

### Składnia:

svc.CompactUp(range: str, wholerow: bool = False, opt filterformula: str): str

### Parametry:

range: zakres, z którego wiersze zostaną usunięte, jako ciąg.

wholerow: Jeśli ta opcja jest ustawiona na True, cały wiersz zostanie usunięty z arkusza. Domyślną wartością jest False, co oznacza, że usuwany wiersz będzie ograniczony do szerokości podanego range.

filterformula: filtr, który ma zostać zastosowany do każdego wiersza, aby określić, czy zostanie on usunięty. Filtr jest wyrażony jako formuła Calc, którą należy zastosować do pierwszego wiersza. Gdy formuła zwróci wartość True dla wiersza, ten wiersz zostanie usunięty. Domyślny filtr usuwa wszystkie puste wiersze.

Załóżmy na przykład, że wybrano zakres A1:J200 (szerokość = 10), więc domyślna formuła to =(LICZ.PUSTE(A1:J1)=10). Oznacza to, że jeśli wszystkie 10 komórek jest pustych w pierwszym wierszu (wiersz 1), wiersz zostanie usunięty. Zauważ, że wzór jest wyrażony tylko w odniesieniu do pierwszego wiersza. Wewnętrznie metoda CompactUp uogólni tę formułę dla wszystkich pozostałych wierszy.

Funkcje Calc użyte w formule podanej w argumencie filterformula muszą być wyrażone przy użyciu ich angielskich nazw. Odwiedź stronę wiki List of Calc Functions, aby uzyskać pełną listę funkcji Calc w języku angielskim.

### Przykład:

##### W języku Basic

        ' Usuń wszystkie puste wiersze w zakresie G1:L10 z Sheet1
        newrange = oDoc.CompactUp("Sheet1.G1:L10")
        ' Poniższy przykład jest podobny, ale cały wiersz jest usuwany z arkusza
        newrange = oDoc.CompactUp("Sheet1.G1:L10", WholeRow := True)
        ' Usuwa wszystkie wiersze, w których pierwsza kolumna jest oznaczona znakiem "X"
        newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Usuwa wszystkie wiersze, w których suma wartości w wierszu jest nieparzysta
        newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")

##### W języku Python

        newrange = myDoc.CompactUp("Sheet1.G1:L10")
        newrange = myDoc.CompactUp("Sheet1.G1:L10", wholerow = True)
        newrange = myDoc.CompactUp("Sheet1.G1:L10", filterformula = '=(G1="X")')
        newrange = myDoc.CompactUp("Sheet1.G1:L10", filterformula = '=(MOD(SUM(G1:L1);2)=1)')

## CopySheet

Kopiuje określony arkusz przed istniejącym arkuszem lub na końcu listy arkuszy. Arkusz do skopiowania może znajdować się w dowolnym otwartym dokumencie programu Calc. Zwraca True, jeśli się powiedzie.

### Składnia:

svc.CopySheet(sheetname: any, newname: str, [beforesheet: any]): bool

### Parametry:

sheetname: nazwa arkusza do skopiowania jako ciąg znaków lub jego odniesienie jako obiekt.

newname: nazwa arkusza do wstawienia. Nazwa nie może być używana w dokumencie.

beforesheet: nazwa (ciąg) lub indeks (liczbowy, począwszy od 1) arkusza, przed którym ma zostać wstawiony skopiowany arkusz. Ten argument jest opcjonalny, a domyślnym zachowaniem jest dodanie skopiowanego arkusza na ostatniej pozycji.

### Przykład:

##### W języku Basic

Poniższy przykład tworzy kopię arkusza „SheetX” i umieszcza go jako ostatni arkusz w bieżącym dokumencie. Nazwa skopiowanego arkusza to „SheetY”.

        Dim oDoc as Object
        'Pobiera obiekt Document aktywnego okna
        Set oDoc = CreateScriptService("Calc")
        oDoc.CopySheet("SheetX", "SheetY")

Poniższy przykład kopiuje „SheetX” z „FileA.ods” i wkleja go na ostatniej pozycji „FileB.ods” z nazwą „SheetY”:

          Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
          Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
          oDocB.CopySheet(oDocA.Sheet("SheetX"), "SheetY")

##### W języku Python

        myDoc.CopySheet("SheetX", "SheetY")

        docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = ui.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopySheet(docA.Sheet("SheetX"), "SheetY")

Aby kopiować arkusze pomiędzy otwartymi dokumentami, użyj CopySheet. Aby skopiować arkusze z dokumentów, które są zamknięte, użyj CopySheetFromFile.

## CopySheetFromFile

Kopiuje określony arkusz z zamkniętego dokumentu Calc i wkleja go przed istniejącym arkuszem lub na końcu listy arkuszy pliku, do którego odnosi się obiekt Document.

Jeśli plik nie istnieje, zgłaszany jest błąd. Jeśli plik nie jest prawidłowym plikiem Calc, wstawiany jest pusty arkusz. Jeśli arkusz źródłowy nie istnieje w pliku wejściowym, na górze nowo wklejonego arkusza zostanie wstawiony komunikat o błędzie.

### Składnia:

svc.CopySheetFromFile(filename: str, sheetname: str, newname: str, [beforesheet: any]): bool

### Parametry:

filename: identyfikuje plik do otwarcia. Musi być zgodny z notacją SF_FileSystem.FileNaming. Plik nie może być chroniony hasłem.

sheetname: nazwa arkusza, który ma zostać skopiowany jako ciąg znaków.

newname: nazwa kopiowanego arkusza, który ma zostać wstawiony do dokumentu. Nazwa nie może być używana w dokumencie.

beforesheet: nazwa (ciąg) lub indeks (liczbowy, począwszy od 1) arkusza, przed którym ma zostać wstawiony skopiowany arkusz. Ten argument jest opcjonalny, a domyślnym zachowaniem jest dodanie skopiowanego arkusza na ostatniej pozycji.

### Przykład:

Poniższy przykład kopiuje „SheetX” z „myFile.ods” i wkleja go do dokumentu określanego przez „oDoc” jako „SheetY” na pierwszej pozycji.

##### W języku Basic

        oDoc.CopySheetFromFile("C:\Documents\myFile.ods", "SheetX", "SheetY", 1)

##### W języku Python

        myDoc.CopySheetFromFile(r"C:\Documents\myFile.ods", "SheetX", "SheetY", 1)

## CopyToCell

Kopiuje określony zakres źródłowy (wartości, formuły i formaty) do docelowego zakresu lub komórki. Metoda odtwarza zachowanie operacji kopiowania/wklejania z zakresu do pojedynczej komórki.

Zwraca ciąg reprezentujący zmodyfikowany zakres komórek. Rozmiar modyfikowanego obszaru jest w pełni zdeterminowany rozmiarem obszaru źródłowego.

Zakres źródłowy może należeć do innego otwartego dokumentu.

### Składnia:

svc.CopyToCell(sourcerange: any, destinationcell: str): str

### Parametry:

sourcerange: zakres źródła jako ciąg znaków, jeśli należy do tego samego dokumentu, lub jako odniesienie, jeśli należy do innego otwartego dokumentu programu Calc.

destinationcell: komórka docelowa, do której zostanie wklejony skopiowany zakres komórek w postaci ciągu znaków. Jeśli podany jest zakres, pod uwagę brana jest tylko jego lewa górna komórka.

### Przykład:

##### W języku Basic

Poniżej znajduje się przykład, w którym źródło i miejsce docelowe znajdują się w tym samym pliku:

          oDoc.CopyToCell("SheetX.A1:F10", "SheetY.C5")

Poniższy przykład ilustruje, jak skopiować zakres z innego otwartego dokumentu Calc:

        Dim ui as Variant : ui = CreateScriptService("UI")
        Dim oDocSource As Object, oDocDestination As Object
        ' Otwórz dokument źródłowy w tle (ukryty)
        Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
        Set oDocDestination = CreateScriptService("Calc")
        oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
        ' Nie zapomnij zamknąć dokumentu źródłowego, ponieważ został otwarty jako ukryty
        oDocSource.CloseDocument()

##### W języku Python

        docSource = ui.OpenDocument(r"C:\Documents\SourceFile.ods", hidden = True, readonly = True)
        docDestination = CreateScriptService("Calc")
        docDestination.CopyToCell(docSource.Range("Sheet1.C2:C4"), "SheetT.A5")
        docSource.CloseDocument()

Aby zasymulować kopiowanie/wklejanie z zakresu do pojedynczej komórki, użyj CopyToCell. Aby zasymulować kopiowanie/wklejanie z zakresu do większego zakresu (przy kilkukrotnej replikacji tych samych komórek), użyj CopyToRange.

## CopyToRange

Kopiuje w dół i/lub w prawo określony zakres źródłowy (wartości, formuły i formaty) do zakresu docelowego. Metoda imituje zachowanie operacji kopiowania/wklejania z zakresu źródłowego do większego zakresu docelowego.

- Jeśli wysokość (lub szerokość) obszaru docelowego wynosi > 1 wiersz (lub kolumna), wówczas wysokość (lub szerokość) źródła musi być <= wysokości (lub szerokości) miejsca docelowego. W przeciwnym razie nic się nie stanie.

- Jeśli wysokość (lub szerokość) miejsca docelowego wynosi = 1, wówczas miejsce docelowe jest rozwijane w dół (lub w prawo) aż do wysokości (lub szerokości) zakresu źródłowego.

Metoda zwraca ciąg znaków reprezentujący zmodyfikowany zakres komórek.

Zakres źródłowy może należeć do innego otwartego dokumentu.

### Składnia:

svc.CopyToRange(sourcerange: any, destinationrange: str): str

### Parametry:

sourcerange: zakres źródła jako ciąg znaków, jeśli należy do tego samego dokumentu, lub jako odniesienie, jeśli należy do innego otwartego dokumentu programu Calc.

destinationrange: miejsce docelowe skopiowanego zakresu komórek jako ciąg.

### Przykład:

##### W języku Basic

Kopiowanie w ramach jednego dokumentu:

        oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
        ' Zwraca ciąg zakresu: "$SheetY.$C$5:$J$14"

Kopiowanie z jednego pliku do drugiego:

        Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
        Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
        oDocB.CopyToRange(oDocA.Range("SheetX.A1:F10"), "SheetY.C5:J5")

##### W języku Python

        doc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")

        docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = ui.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopyToRange(docA.Range("SheetX.A1:F10"), "SheetY.C5:J5")

## CreateChart

Tworzy nowy obiekt wykresu przedstawiający dane z określonego zakresu. Zwrócony obiekt wykresu można dalej manipulować za pomocą usługi Chart.

### Składnia:

svc.CreateChart(chartname: str, sheetname: str, range: str, columnheader: bool = False, rowheader: bool = False): obj

### Parametry:

chartname: zdefiniowana przez użytkownika nazwa wykresu, który ma zostać utworzony. Nazwa musi być unikalna w tym samym arkuszu.

sheetname: nazwa arkusza, w którym zostanie umieszczony wykres.

range: zakres, który ma być używany jako źródło danych dla wykresu. Zakres może odnosić się do dowolnego arkusza dokumentu Calc.

columnheader: gdy True, najwyższy wiersz zakresu jest używany jako etykiety osi kategorii lub legendy (domyślnie = False).

rowheader: gdy True, skrajna lewa kolumna zakresu jest używana jako etykiety osi kategorii lub legendy. (domyślnie = False).

### Przykład:

Poniższe przykłady w języku Basic i Python tworzą wykres przy użyciu danych zawartych w zakresie „A1:B5” w „Sheet1” i umieszczają wykres w „Sheet2”.

##### W języku Basic

        Set oChart = oDoc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", RowHeader := True)
        oChart.ChartType = "Donut"

##### W języku Python

        chart = doc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", rowheader=True)
        chart.ChartType = "Donut"

Odwiedź stronę pomocy dotyczącą usługi Chart ScriptForge, aby dowiedzieć się więcej o dalszym manipulowaniu obiektami wykresów. Możliwa jest zmiana właściwości takich jak typ wykresu, tytuł wykresu i osi oraz pozycja wykresu.

## CreatePivotTable

Tworzy nową tabelę przestawną z właściwościami zdefiniowanymi przez argumenty przekazane do metody.

Należy podać nazwę tabeli przestawnej. Jeśli w arkuszu docelowym istnieje już tabela przestawna o tej samej nazwie, zostanie ona zastąpiona bez ostrzeżenia.

Ta metoda zwraca ciąg znaków zawierający zakres, w którym została umieszczona nowa tabela przestawna.

### Składnia:

svc.CreatePivotTable(pivottablename: str, sourcerange: str, targetcell: str, datafields: str[0..*], rowfields: str[0..*], columnfields: str[0..*], filterbutton: bool = true, rowtotals: bool = true, columntotals: bool = true): str

### Parametry:

pivottablename: zdefiniowana przez użytkownika nazwa nowej tabeli przestawnej.

sourcerange: zakres zawierający surowe dane w postaci ciągu znaków. Pierwszy wiersz powinien zawierać nazwy pól, z których korzysta tabela przestawna.

targetcell: lewa górna komórka, w której zostanie umieszczona nowa tabela przestawna. Jeśli określono zakres, uwzględniana jest tylko jego lewa górna komórka.

datafields: może to być pojedynczy ciąg znaków lub tablica zawierająca ciągi znaków definiujące nazwy pól i funkcje, które mają zostać zastosowane. Gdy określono tablicę, musi ona być zgodna ze składnią Array("NazwaPola[;Funkcja]", ...).

Dozwolone funkcje to: Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP i Median. Nazwy funkcji muszą być podawane w języku angielskim. Gdy wszystkie wartości są numeryczne, funkcją domyślną jest Sum. W przeciwnym razie funkcją domyślną jest Count.

rowfields: pojedynczy ciąg znaków lub tablica z nazwami pól, które będą używane jako wiersze tabeli przestawnej.

columnfields: pojedynczy ciąg znaków lub tablica z nazwami pól, które będą używane jako kolumny tabeli przestawnej.

filterbutton: określa, czy przycisk filtru będzie wyświetlany nad tabelą przestawną (domyślnie = True).

rowtotals: określa, czy do tabeli przestawnej zostanie dodana osobna kolumna zawierająca sumy wierszy (domyślnie = True).

columntotals: określa, czy do tabeli przestawnej zostanie dodany oddzielny wiersz zawierający sumy kolumn (domyślnie = True)

### Przykład:

##### W języku Basic

        Dim vData As Variant, oDoc As Object, ui As Object, sTable As String, sPivot As String
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.CreateDocument("Calc")
        vData = Array(Array("Item", "State", "Team", "2002", "2003", "2004"), _
            Array("Books", "Michigan", "Jean", 14788, 30222, 23490), _
            Array("Candy", "Michigan", "Jean", 26388, 15641, 32849), _
            Array("Pens", "Michigan", "Jean", 16569, 32675, 25396), _
            Array("Books", "Michigan", "Volker", 21961, 21242, 29009), _
            Array("Candy", "Michigan", "Volker", 26142, 22407, 32841))
        sTable = oDoc.SetArray("A1", vData)
        sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _
            Array("2002", "2003;count", "2004;average"), _ ' Trzy pola danych
            "Item", _ ' Pole z jednym wierszem
            Array("State", "Team"), False) ' Dwa pola kolumnowe

##### W języku Python

        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Calc")
        vData = [["Item", "State", "Team", "2002", "2003", "2004"],
                 ["Books", "Michigan", "Jean", 14788, 30222, 23490],
                 ["Candy", "Michigan", "Jean", 26388, 15641, 32849],
                 ["Pens", "Michigan", "Jean", 16569, 32675, 25396)],
                 ["Books", "Michigan", "Volker", 21961, 21242, 29009],
                 ["Candy", "Michigan", "Volker", 26142, 22407, 32841]]
        sTable = doc.SetArray("A1", vData)
        sPivot = doc.CreatePivotTable("PT1", sTable, "H1",
                                      ["2002", "2003;count", "2004;average"],
                                      "Item",
                                      ["State", "Team"], False)

Aby dowiedzieć się więcej o tabelach przestawnych LibreOffice Calc, przeczytaj stronę pomocy Tabela przestawna.

## DAvg, DCount, DMax, DMin and DSum

Zastosuj odpowiednio funkcje Average, Count, Max, Min i Sum, do wszystkich komórek zawierających wartości liczbowe w danym zakresie, z wyłączeniem wartości z filtrowanych i ukrytych wierszy i ukrytych kolumn, tak samo jak w przypadku funkcji paska stanu.

### Składnia:

svc.DAvg(range: str): float

svc.DCount(range: str): float

svc.DMax(range: str): float

svc.DMin(range: str): float

svc.DSum(range: str): float

### Parametry:

range: zakres, do którego zostanie zastosowana funkcja, jako ciąg.

### Przykład:

Poniższy przykład stosuje funkcję Sum do zakresu "A1:A1000" aktualnie wybranego arkusza:

##### W języku Basic

          result = oDoc.DSum("~.A1:A1000")

##### W języku Python

        result = myDoc.DSum("~.A1:A1000")

Komórki w danym zakresie zawierającym tekst będą ignorowane przez wszystkie te funkcje. Na przykład metoda DCount nie policzy komórek z tekstem, tylko komórki numeryczne.

## ExportRangeToFile

Eksportuje określony zakres jako plik obrazu lub PDF.

Ta metoda zwraca True, jeśli plik docelowy został pomyślnie zapisany.

Ukryte wiersze lub kolumny w określonym zakresie nie są eksportowane do pliku docelowego.

### Składnia:

svc.ExportRangeToFile(range: str, filename: str, imagetype: str = "pdf", overwrite: bool = False): bool

### Parametry:

range: nazwa arkusza lub zakres komórek do wyeksportowania jako ciąg.

filename: nazwa pliku do zapisania. Musi podążać za notacją SF_FileSystem.FileNaming.

imagetype: identyfikuje typ pliku docelowego. Możliwe wartości to "jpeg", "pdf" (domyślnie) i "png".

overwrite: po ustawieniu na True plik docelowy może zostać zastąpiony (domyślnie = False).

### Przykład:

##### W języku Basic

        ' Eksportuje cały arkusz jako plik PDF
        oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
        ' Eksportuje zakres jako plik PNG i zastępuje plik docelowy, jeśli istnieje
        oDoc.ExportRangeToFile("SheetX.A1:D10", "C:\Temp\image.png", "png", Overwrite := True)

##### W języku Python

        doc.ExportRangeToFile("SheetX", r"C:\Temp\image.pdf")
        doc.ExportRangeToFile("SheetX.A1:D10", r"C:\Temp\image.png", "png", overwrite = True)

## Forms

W zależności od podanych parametrów ta metoda zwróci:

- Tablica liczona od zera (lub krotka w Pythonie) z nazwami wszystkich formularzy zawartych w danym arkuszu (jeśli nieobecny jest argument form)

- Instancja usługi sfDocuments.Form reprezentująca formularz wymieniony jako argument.

### Składnia:

svc.Forms(sheetname: str): str[0..*]

svc.Forms(sheetname: str, form: str = ''): svc

svc.Forms(sheetname: str, form: int): svc

### Parametry:

sheetname: nazwa arkusza, jako ciąg, z którego formularz zostanie pobrany.

form: nazwa lub indeks odpowiadający formularzowi przechowywanemu w określonym arkuszu. Jeśli ten argument jest nieobecny, metoda zwróci listę z nazwami wszystkich formularzy dostępnych w arkuszu.

### Przykład:

W poniższych przykładach pierwszy wiersz otrzymuje nazwy wszystkich formularzy przechowywanych w "Sheet1", a drugi wiersz pobiera obiekt Form formularza o nazwie "Form_A", który jest przechowywany w "Sheet1".

##### W języku Basic

        Set FormNames = oDoc.Forms("Sheet1")
        Set FormA = oDoc.Forms("Sheet1", "Form_A")

##### W języku Python

        form_names = doc.Forms("Sheet1")
        form_A = doc.Forms("Sheet1", "Form_A")

## GetColumnName

Przekształca numer kolumny od 1 do 1024 w odpowiednią literę (kolumna 'A', 'B', ..., 'AMJ'). Jeśli podany numer kolumny jest poza dozwolonym zakresem, zwracany jest ciąg zerowej długości.

### Składnia:

svc.GetColumnName(columnnumber: int): str

### Parametry:

columnnumber: numer kolumny jako wartość liczby całkowitej w przedziale 1 ... 1024.

### Przykład:

##### W języku Basic

Wyświetla pole wiadomości o nazwie trzeciej kolumny, która domyślnie to "C".

        MsgBox oDoc.GetColumnName(3)

##### W języku Python

        bas = CreateScriptService("Basic")
        bas.MsgBox(myDoc.GetColumnName(3))

Maksymalna liczba kolumn dozwolonych na arkuszu obliczeniowym wynosi 1024.

## GetFormula

Uzyskaj formułę lub formuły przechowywane w danym zakresie komórek jako pojedynczy ciąg, tablicę ciągów jedno- lub dwuwymiarową.

Nazwy funkcji Calc używanych w zwróconych formułach są wyrażone w języku angielskim. Odwiedź stronę wiki List of Calc Functions, aby uzyskać pełną listę funkcji Calc w języku angielskim.

### Składnia:

svc.GetFormula(range: str): any

### Parametry:

range: zakres, z którego można uzyskać formuły, jako ciąg.

### Przykład:

##### W języku Basic

Poniższy przykład zwraca tablicę 3 na 2 z formułami w zakresie "A1:B3" (3 wiersze na 2 kolumny):

        arrFormula = oDoc.GetFormula("~.A1:B3")

##### W języku Python

        arrFormula = myDoc.GetFormula("~.A1:B3")

## GetValue

Uzyskaj wartość lub wartości przechowywane w danym zakresie komórek jako pojedynczą wartość, tablicę jedno- lub dwuwymiarową. Wszystkie wartości są typu Double lub String.

### Składnia:

svc.GetValue(range: str): any

### Parametry:

range: zakres, z którego uzyskać wartości, jako ciąg.

### Przykład:

##### W języku Basic

          arrValues = oDoc.GetValue("~.B1:C100")

##### W języku Python

        arrValues = myDoc.GetValue("~.B1:C100")

Jeśli komórka zawiera datę, liczba odpowiadająca tej dacie zostanie zwrócona. Aby przekonwertować wartości liczbowe na daty w skryptach Basic, użyj wbudowanej funkcji Basic CDate. W skryptach Pythona użyj funkcji CDate z usługi Basic.

## ImportFromCSVFile

Importuje zawartość pliku tekstowego CSV i umieszcza ją w określonej komórce docelowej.

Obszar docelowy jest oczyszczony ze wszystkich zawartości i formatów przed umieszczeniem zawartości pliku CSV. Rozmiar zmodyfikowanego obszaru jest w pełni określony przez zawartość pliku wejściowego.

Metoda zwraca ciąg znaków reprezentujący zmodyfikowany zakres komórek.

### Składnia:

svc.ImportFromCSVFile(filename: str, destinationcell: str, [filteroptions: str]): str

### Parametry:

filename: identyfikuje plik do otwarcia. Musi podążać za notacją SF_FileSystem.FileNaming.

destinationcell: komórka docelowa do wstawienia importowanych danych jako ciąg. Jeśli zamiast tego podano obszar, stosuje się tylko lewą górną komórkę.

filteroptions: argumenty dotyczące filtra wejściowego CSV. Domyślny filtr dokonuje następujących założeń:

- Kodowanie plików wejściowych to UTF8.

- Separator pola to przecinek, średnik lub znak tabulatora.

- Separator ciągów jest znakiem cytatu (").

- Wszystkie linie są uwzględnione.

- Cytowane ciągi są sformatowane jako tekst.

- Wykryto liczby specjalne.

- Wszystkie kolumny są uważane za tekst, jeśli nie są uznawane za prawidłowe liczby.

- Językiem jest angielski (USA), co oznacza, że separator dziesiętny to ".", a separator tysięcy to ",".

### Przykład:

##### W języku Basic

        oDoc.ImportFromCSVFile("C:\Temp\myCSVFile.csv", "SheetY.C5")

##### W języku Python

        myDoc.ImportFromCSVFile(r"C:\Temp\myCSVFile.csv", "SheetY.C5")

Więcej informacji na temat opcji filtra CSV można znaleźć na stronie pomocy opcji filtra CSV.

## ImportFromDatabase

Importuje zawartość tabeli bazy danych, kwerendy lub zestawu wyników, czyli wynik polecenia SQL SELECT, wstawiając go do komórki docelowej.

Przed wstawieniem zaimportowanej zawartości obszar docelowy zostaje oczyszczony z całej zawartości i formatów. Rozmiar modyfikowanego obszaru jest w pełni zdeterminowany zawartością tabeli lub kwerendy.

Metoda zwraca wartość True, gdy import się powiódł.

### Składnia:

svc.ImportFromDatabase(filename: str = "", registrationname: str = "", destinationcell: str = "", sqlcommand: str = "", directsql: bool): bool

### Parametry:

filename: identyfikuje plik do otwarcia. Musi podążać za notacją SF_FileSystem.FileNaming.

registrationname: nazwa używana do wyszukiwania bazy danych w rejestrze baz danych. Argument ten jest ignorowany, jeśli podano filename.

destinationcell: miejsce docelowe zaimportowanych danych jako ciąg. Jeśli podany jest zakres, pod uwagę brana jest tylko jego lewa górna komórka.

sqlcommand: nazwa tabeli lub kwerendy (bez cudzysłowów i nawiasów kwadratowych) albo instrukcja SQL SELECT, w której nazwy tabel i pól mogą być ujęte w nawiasy kwadratowe lub cudzysłowy, aby poprawić ich czytelność.

directsql: jeśli True, polecenie SQL jest wysyłane do silnika bazy danych bez wstępnej analizy. Wartość domyślna to False. Argument jest ignorowany w przypadku tabel. W przypadku kwerend zastosowaną opcją jest ta ustawiona podczas definiowania kwerendy.

### Przykład:

##### W języku Basic

        oDoc.ImportFromDatabase("C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")

##### W języku Python

        myDoc.ImportFromDatabase(r"C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")

## InsertSheet

Wstawia nowy pusty arkusz przed istniejącym arkuszem lub na końcu listy arkuszy.

### Składnia:

svc.InsertSheet(sheetname: str, [beforesheet: any]): bool

### Parametry:

sheetname: nazwa nowego arkusza.

beforesheet: nazwa (ciąg) lub indeks (numeryczny, zaczynający się od 1) arkusza, przed którym ma zostać wstawiony nowy arkusz. Argument ten jest opcjonalny i domyślnym zachowaniem jest wstawienie arkusza na ostatniej pozycji.

### Przykład:

Poniższy przykład wstawia nowy pusty arkusz o nazwie "SheetX" i umieszcza go przed "SheetY":

##### W języku Basic

        oDoc.InsertSheet("SheetX", "SheetY")

##### W języku Python

        myDoc.InsertSheet("SheetX", "SheetY")

## MoveRange

Przenosi określony zakres źródłowy do docelowego zakresu komórek. Metoda zwraca ciąg znaków reprezentujący zmodyfikowany zakres komórek. Wymiar modyfikowanego obszaru jest w pełni zdeterminowany rozmiarem obszaru źródłowego.

### Składnia:

svc.MoveRange(source: str, destination: str): str

### Parametry:

source: zakres źródłowy komórek jako ciąg.

destination: komórka docelowa jako ciąg. Jeśli podany jest zakres, za miejsce docelowe uważa się jego lewą górną komórkę.

### Przykład:

##### W języku Basic

        oDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")

##### W języku Python

        myDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")

## MoveSheet

Przenosi istniejący arkusz i umieszcza go przed określonym arkuszem lub na końcu listy arkuszy.

### Składnia:

svc.MoveSheet(sheetname: str, [beforesheet: any]): bool

### Parametry:

sheetname: nazwa arkusza do przeniesienia. Arkusz musi istnieć. W przeciwnym razie zostanie zgłoszony wyjątek.

beforesheet: nazwa (ciąg) lub indeks (numeryczny, zaczynający się od 1) arkusza, przed którym zostanie umieszczony arkusz pierwotny. Argument ten jest opcjonalny i domyślnym zachowaniem jest przesunięcie arkusza na ostatnią pozycję.

### Przykład:

Poniższy przykład przenosi istniejący arkusz "SheetX" i umieszcza go przed "SheetY":

##### W języku Basic

        oDoc.MoveSheet("SheetX", "SheetY")

##### W języku Python

        myDoc.MoveSheet("SheetX", "SheetY")

## Offset

Zwraca nowy zakres (jako ciąg znaków) przesunięty o określoną liczbę wierszy i kolumn z danego zakresu.

Ta metoda zachowuje się tak samo jak funkcja Offset programu Calc.

### Składnia:

svc.Offset(reference: str, rows: int = 0, columns: int = 0, [height: int], [width: int]): str

### Parametry:

reference: zakres w postaci ciągu znaków, który będzie używany przez metodę jako odniesienie do wykonania operacji przesunięcia.

rows: liczba wierszy, o które zakres początkowy jest przesunięty w górę (wartość ujemna) lub w dół (wartość dodatnia). Użyj 0 (domyślnie), aby pozostać w tym samym wierszu.

columns: liczba kolumn, o które zakres początkowy jest przesunięty w lewo (wartość ujemna) lub w prawo (wartość dodatnia). Użyj 0 (domyślnie), aby pozostać w tej samej kolumnie.

height: wysokość pionowa obszaru rozpoczynającego się w nowej pozycji zakresu. Pomiń ten argument, jeśli nie jest wymagana zmiana rozmiaru w pionie.

width: szerokość pozioma obszaru rozpoczynającego się w nowej pozycji zakresu. Pomiń ten argument, jeśli nie jest wymagana zmiana rozmiaru w poziomie.

Argumenty rows i columns nie mogą prowadzić do zera lub ujemnego wiersza lub kolumny początkowej.

Argumenty height i width nie mogą prowadzić do zera lub ujemnej liczby wierszy lub kolumn.

### Przykład:

##### W języku Basic

        oDoc.Offset("A1", 2, 2)
        'SheetX.$C$3 (A1 przesunięta o dwa wiersze i dwie kolumny w dół)
        oDoc.Offset("A1", 2, 2, 5, 6)
        'SheetX.$C$3:$H$7 (A1 przesunięta o dwa wiersze i kolumny o szerokości 5 wierszy i 6 kolumn)

##### W języku Python

        myDoc.Offset("A1", 2, 2)
        myDoc.Offset("A1", 2, 2, 5, 6)

## OpenRangeSelector

Otwiera niemodalne okno dialogowe umożliwiające wybranie obszaru w dokumencie i zwraca ciąg znaków zawierający wybrany obszar.

Ta metoda otwiera to samo okno dialogowe, które jest używane przez LibreOffice po naciśnięciu przycisku Zmniejsz. Na przykład w oknie dialogowym Narzędzia - Szukaj wyniku znajduje się przycisk Zmniejsz po prawej stronie pola Komórka formuły.

Ta metoda nie zmienia bieżącego wyboru.

### Składnia:

svc.OpenRangeSelector(opt title: str, opt selection: str, singlecell: bool = False, closeafterselect: bool = True): str

### Parametry:

title: tytuł okna dialogowego jako ciąg znaków.

selection: opcjonalny zakres, który jest początkowo wybrany po wyświetleniu okna dialogowego.

singlecell: gdy True (domyślnie), dozwolony jest tylko wybór pojedynczych komórek. Gdy False, dozwolony jest wybór zakresu.

closeafterselect: gdy True (domyślnie), okno dialogowe zostanie zamknięte natychmiast po dokonaniu wyboru. Gdy False, użytkownik może zmienić wybór tyle razy, ile potrzeba, a następnie ręcznie zamknąć okno dialogowe.

### Przykład:

##### W języku Basic

        Dim sRange as String
        sRange = oDoc.OpenRangeSelector(Title := "Select a range")

##### W języku Python

        sRange = myDoc.OpenRangeSelector(title = "Select a range")

## Printf

Zwraca ciąg wejściowy po zastąpieniu jego znaków tokenu ich wartościami z danego zakresu.

Ta metoda nie zmienia bieżącego wyboru.

Tej metody można użyć do szybkiego wyodrębnienia określonych części nazwy zakresu, takich jak nazwa arkusza lub pierwsza kolumna i wiersz komórki, i wykorzystania ich do utworzenia nowego adresu zakresu.

### Składnia:

svc.Printf(inputstr: str, range: str, tokencharacter: str = "%"): str

### Parametry:

inputstr: ciąg zawierający tokeny, które zostaną zastąpione odpowiednimi wartościami z range.

range: właściwość RangeName, z której zostaną wyodrębnione wartości. Jeśli zawiera nazwę arkusza, arkusz musi istnieć.

tokencharacter: znak używany do identyfikacji tokenów. Domyślnie "%" jest znakiem tokenu. Akceptowane są następujące tokeny:

- %S – nazwa arkusza zawierająca zakres, w razie potrzeby łącznie z cudzysłowami.

- %R1 – numer wiersza lewej górnej komórki zakresu.

- %C1 – litera kolumny lewej górnej komórki zakresu.

- %R2 – numer wiersza w prawej dolnej komórce zakresu.

- %C2 – litera kolumny w prawej dolnej komórce zakresu.

### Przykład:

##### W języku Basic

Poniższy przykład wyodrębnia każdy element RangeName zdefiniowany w sRange i wykorzystuje je do tworzenia komunikatu.

        Dim sRange as String, sInputStr as String
        sRange = "Sheet1.A1:E10"
        sInputStr = "Sheet name: %S" & Chr(10) & _
                    "First row: %R1" & Chr(10) & _
                    "First column %C1" & Chr(10) & _
                    "Last row %R2" & Chr(10) & _
                    "Last column %C2"
        MsgBox oDoc.Printf(sInputStr, sRange)

Metodę Printf można połączyć z metodą SetFormula, aby utworzyć formuły obejmujące wiele komórek. Rozważmy na przykład tabelę z wartościami liczbowymi z zakresu "A1:E10", z której mają zostać utworzone formuły sumujące wartości w każdym wierszu i umieszczające wyniki w zakresie "F1:F10":

        Dim sFormula as String, sRange as String
        sRange = "A1:E10"
        ' Zwróć uwagę na użycie znaku "$".
        sFormula = "=SUM($%C1%R1:$%C2%R1)"
        oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))

##### W języku Python

        sRange = "Sheet1.A1:E10"
        sInputStr = "Sheet name: %S\n" \
                    "First row: %R1\n" \
                    "First column %C1\n" \
                    "Last row %R2\n" \
                    "Last column %C2"
        bas = CreateScriptService("Basic")
        bas.MsgBox(myDoc.Printf(sInputStr, sRange))

        sRange = "A1:E10
        sFormula = "=SUM($%C1%R1:$%C2%R1)"
        myDoc.SetFormula("F1:F10", myDoc.Printf(sFormula, sRange))

## PrintOut

Metoda ta wysyła zawartość danego arkusza do drukarki domyślnej lub do drukarki zdefiniowanej metodą SetPrinter usługi Document.

Zwraca wartość True, jeśli arkusz został pomyślnie wydrukowany.

### Składnia:

svc.PrintOut(opt sheetname: str, pages: str = "", copies: num = 1): bool

### Parametry:

sheetname: arkusz do wydrukowania, domyślnie jest to arkusz aktywny.

pages: strony do wydrukowania jako ciąg znaków, jak w interfejsie użytkownika. Przykład: "1-4;10;15-18". Wartość domyślna to wszystkie strony.

copies: liczba kopii. Wartość domyślna to 1.

### Przykład:

##### W języku Basic

        If oDoc.PrintOut("SheetX", "1-4;10;15-18", Copies := 2) Then
            ' ...
        End If

##### W języku Python

        if doc.PrintOut('SheetX', copies=3, pages='45-88'):
            # ...

## RemoveDuplicates

Usuwa zduplikowane wiersze z określonego zakresu. Porównanie w celu ustalenia, czy dany wiersz jest duplikatem, odbywa się na podstawie podzbioru kolumn w zakresie.

Ta metoda zwraca ciąg znaków zawierający wynikowy zakres.

Usuwanie zduplikowanych wierszy rozpoczyna się od pierwszego wiersza w zakresie, przesuwając się w dół, co oznacza, że jeśli dwa lub więcej wierszy jest duplikatami, zachowywany jest tylko pierwszy.

### Składnia:

svc.RemoveDuplicates(range: str, opt columns: int[0..*], header: bool = False, casesensitive: bool = False, mode: str = "COMPACT"): str

### Parametry:

range: zakres, z którego duplikaty zostaną usunięte, w postaci ciągu znaków.

columns: tablica zawierająca numery kolumn wskazujące, które kolumny zostaną uwzględnione przy ustalaniu, czy wiersz jest duplikatem, czy nie. Jeśli ten argument pozostanie pusty, używana będzie tylko pierwsza kolumna. Elementy tej tablicy muszą znajdować się w przedziale od 1 do szerokości zakresu.

header: określa, czy pierwszy wiersz jest wierszem główki (domyślnie = False).

casesensitive: określa, czy w porównaniach ciągów uwzględniana jest wielkość liter (domyślnie = False).

mode: określa, co zrobić ze zduplikowanymi wierszami. Jeśli mode = "CLEAR", wówczas duplikaty są po prostu usuwane z arkusza, pozostawiając komórki puste. Jeśli mode = "COMPACT", to duplikaty są usuwane, a puste wiersze są kompresowane (domyślnie = "COMPACT").

### Przykład:

##### W języku Basic

        ' Usuwa zduplikowane wiersze, w których wartości w kolumnie A są zduplikowane
        ' Należy pamiętać, że wszystkie argumenty opcjonalne używają wartości domyślnej
        oDoc.RemoveDuplicates("A1:B10")
        ' Usuwa zduplikowane wiersze, biorąc pod uwagę, że pierwszy wiersz zawiera główki
        ' Kolumny A i B służą do określenia, czy wiersz jest duplikatem
        ' Komórki zawierające zduplikowane wartości pozostają puste
        oDoc.RemoveDuplicates("A1:D10", columns := Array(1, 2), header := True, mode := "CLEAR")

##### W języku Python

        myDoc.RemoveDuplicates("A1:B10")
        myDoc.RemoveDuplicates("A1:D10", columns = (1, 2), header = True, mode = "CLEAR")

## RemoveSheet

Usuwa istniejący arkusz z dokumentu.

### Składnia:

svc.RemoveSheet(sheetname: str): bool

### Parametry:

sheetname: nazwa arkusza do usunięcia.

### Przykład:

##### W języku Basic

        oDoc.RemoveSheet("SheetY")

##### W języku Python

        myDoc.RemoveSheet("SheetY")

## RenameSheet

Zmienia nazwę podanego arkusza i zwraca True, jeśli się powiedzie.

### Składnia:

svc.RenameSheet(sheetname: str, newname: str): bool

### Parametry:

sheetname: nazwa arkusza, którego nazwę chcesz zmienić.

newname: nowa nazwa arkusza. Nie może jeszcze istnieć.

### Przykład:

W tym przykładzie nazwa aktywnego arkusza zostaje zmieniona na "SheetY":

##### W języku Basic

        oDoc.RenameSheet("~", "SheetY")

##### W języku Python

        mydoc.RenameSheet("~", "SheetY")

## SetArray

Przechowuje podaną wartość, zaczynając od określonej komórki docelowej. Zaktualizowany obszar rozciąga się od komórki docelowej lub od lewego górnego rogu danego zakresu, aby dostosować się do rozmiaru wejściowego argumentu value. Wektory są zawsze rozwijane w pionie.

Metoda zwraca ciąg znaków reprezentujący zmodyfikowany obszar jako zakres komórek.

### Składnia:

svc.SetArray(targetcell: str, value: any): str

### Parametry:

targetcell: komórka lub zakres w postaci ciągu znaków, od którego należy rozpocząć przechowywanie danej wartości.

value: skalar, wektor lub tablica (w Pythonie jedno- lub dwuwymiarowe listy i krotki) z nowymi wartościami, które mają być zapisane z komórki docelowej lub z lewego górnego rogu zakresu, jeśli targetcell jest zakresem. Nowe wartości muszą być ciągami znaków, wartościami numerycznymi lub datami. Inne typy spowodują opróżnienie odpowiednich komórek.

### Przykład:

##### W języku Basic

Poniższy przykład wykorzystuje wbudowaną funkcję DimArray do utworzenia tablicy, a następnie zapisania jej w komórce "A1":

        Dim arrData as Variant
        arrData = DimArray(2, 1)
        arrData(0, 0) = 1 : arrData(1, 0) = 2 : arrData(2, 0) = 3
        arrData(0, 1) = "One" : arrData(1, 1) = "Two" : arrData(2, 1) = "Three"
        oDoc.SetArray("Sheet1.A1", arrData)

W tym przykładzie użyto metody RangeInit usługi ScriptForge Array do utworzenia tablicy z wartościami, które są następnie zapisywane od komórki "A1" w dół.

        ' Wypełnij pierwszą kolumnę wartościami od 1 do 1000
        oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))

##### W języku Python

        arrData = ((1, "One"), (2, "Two"), (3, "Three"))
        myDoc.SetArray("Sheet1.A1", arrData)

        myDoc.SetArray("Sheet1.A1", tuple(i + 1 for i in range(1000)))

Aby zrzucić całą zawartość tablicy do arkusza, użyj SetArray. Aby zrzucić zawartość tablicy tylko w granicach docelowego zakresu komórek, użyj SetValue.

## SetCellStyle

Stosuje określony styl komórki do danego zakresu docelowego. Pełny asortyment jest aktualizowany, a pozostała część arkusza pozostaje nietknięta. Jeśli styl komórki nie istnieje, zgłaszany jest błąd.

Metoda zwraca ciąg znaków reprezentujący zmodyfikowany obszar jako zakres komórek.

### Składnia:

svc.SetCellStyle(targetrange: str, style: str, opt filterformula: str, opt filterscope: str): str

### Parametry:

targetrange: zakres, do którego styl zostanie zastosowany, jako ciąg.

style: nazwa stylu komórki do zastosowania.

filterformula: formuła Calc, która zostanie zastosowana do podanego zakresu, aby określić, które komórki zostaną naruszone. Określona formuła musi zwracać wartość True lub False. Jeśli ten argument nie zostanie określony, wpłynie to na wszystkie komórki w zakresie.

filterscope: określa, w jaki sposób filterformula jest rozszerzana do podanego zakresu. Ten argument jest obowiązkowy, jeśli podano filterformula. Akceptowane są następujące wartości:

- "CELL": formuła określona w argumencie filterformula jest interpretowana raz dla każdej komórki w range.

- "ROW": formuła określona w argumencie filterformula jest interpretowana raz dla każdego wiersza w range.

- "COLUMN": formuła określona w argumencie filterformula jest interpretowana raz dla każdej kolumny w range.

### Przykład:

##### W języku Basic

        oDoc.SetCellStyle("A1:J1", "Heading 1")
        oDoc.SetCellStyle("A2:J100", "Neutral")

##### W języku Python

        myDoc.SetCellStyle("A1:J1", "Heading 1")
        myDoc.SetCellStyle("A2:J100", "Neutral")

Zapoznaj się z dokumentacją metody ClearAll, aby zaznajomić się z przykładami użycia argumentów filterformula i filterscope.

## SetFormula

Wstawia określoną formułę (lub tablicę formuł) do określonego obszaru docelowego. Rozmiar edytowanego obszaru jest równy rozmiarowi obszaru docelowego.

Metoda zwraca ciąg znaków reprezentujący zmodyfikowany obszar jako zakres komórek.

### Składnia:

svc.SetFormula(targetrange: str, formula: any): str

### Parametry:

targetrange: zakres, w którym należy wstawić formuły, jako ciąg.

formula: ciąg, wektor lub tablica ciągów z nowymi formułami dla każdej komórki w zakresie docelowym.

Pełny asortyment zostaje zaktualizowany, a pozostała część arkusza pozostaje niezmieniona.

Jeżeli podana formuła jest ciągiem znaków, w całym zakresie wklejana jest unikalna formuła z dostosowaniem względnych odniesień.

Jeśli rozmiar formula jest mniejszy niż rozmiar targetrange, wówczas pozostałe komórki zostaną opróżnione.

Jeśli rozmiar formula jest większy niż rozmiar targetrange, wówczas formuły są kopiowane tylko częściowo, aż wypełnią rozmiar targetrange.

Wektory są zawsze rozwijane w pionie, chyba że targetrange ma wysokość dokładnie 1 wiersza.

Funkcje Calc użyte w argumencie formula muszą być wyrażone przy użyciu ich angielskich nazw. Odwiedź stronę wiki List of Calc Functions, aby uzyskać pełną listę funkcji Calc w języku angielskim.

### Przykład:

##### W języku Basic

        oDoc.SetFormula("A1", "=A2")
        ' Wektor poziomy, częściowo pusty
        oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
        ' D2 zawiera formułę "=H2"
        oDoc.SetFormula("A1:D2", "=E1")

##### W języku Python

        myDoc.SetFormula("A1", "=A2")
        myDoc.SetFormula("A1:F1", ("=A2", "=B2", "=C2+10"))
        myDoc.SetFormula("A1:D2", "=E1")

## SetValue

Przechowuje podaną wartość w określonym zakresie. Rozmiar modyfikowanego obszaru jest równy rozmiarowi zakresu docelowego.

Metoda zwraca ciąg znaków reprezentujący zmodyfikowany obszar jako zakres komórek.

### Składnia:

svc.SetValue(targetrange: str, value: any): str

### Parametry:

targetrange: zakres, w którym ma być przechowywana podana wartość w postaci ciągu.

value: skalar, wektor lub tablica z nowymi wartościami dla każdej komórki zakresu. Nowe wartości muszą być ciągami znaków, wartościami numerycznymi lub datami. Inne typy spowodują opróżnienie odpowiednich komórek.

Pełny asortyment zostaje zaktualizowany, a pozostała część arkusza pozostaje niezmieniona. Jeśli rozmiar value jest mniejszy niż rozmiar targetrange, wówczas pozostałe komórki zostaną opróżnione.

Jeśli rozmiar value jest większy niż rozmiar targetrange, wówczas value jest kopiowana tylko częściowo, aż wypełni rozmiar targetrange.

Wektory są rozwijane w pionie, chyba że targetrange ma wysokość dokładnie 1 wiersza.

### Przykład:

##### W języku Basic

        oDoc.SetValue("A1", 2)
        ' Pole Value jest mniejsze niż obszar TargetRange (pozostałe komórki są puste)
        oDoc.SetValue("A1:F1", Array(1, 2, 3))
        ' Value i TargetRange mają ten sam rozmiar
        oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))

Jeśli chcesz wypełnić pojedynczy wiersz wartościami, możesz użyć funkcji Offset. W poniższym przykładzie rozważmy, że arrData jest tablicą jednowymiarową:

        Dim firstCell As String : firstCell = "A1"
        Dim lenArray As Integer : lenArray = UBound(arrData) - LBound(arrData) + 1
        Dim newRange As String : newRange = oDoc.Offset(firstCell, width = lenArray)
        oDoc.SetValue(newRange, arrData)

##### W języku Python

        myDoc.SetValue("A1", 2)
        myDoc.SetValue("A1:F1", (1, 2, 3))
        myDoc.SetValue("A1:D2", ((1, 2, 3, 4), (5, 6, 7, 8)))

        firstCell = "A1"
        newRange = doc.Offset(firstCell, width = len(arrData))
        doc.SetValue(newRange, arrData)

## ShiftDown

Przesuwa zadany zakres komórek w dół poprzez wstawienie pustych wierszy. Nie ma to wpływu na bieżący wybór.

W zależności od wartości argumentu wholerow wstawione wiersze mogą obejmować szerokość określonego zakresu lub wszystkie kolumny w wierszu.

Ta metoda zwraca ciąg znaków reprezentujący nową lokalizację zakresu początkowego.

Jeżeli przesunięty zakres przekracza krawędzie arkusza, to nic się nie dzieje.

### Składnia:

svc.ShiftDown(range: str, wholerow: bool = False, opt rows: int): str

### Parametry:

range: zakres, powyżej którego zostaną wstawione wiersze, jako ciąg znaków.

wholerow: jeśli ustawiono wartość False (domyślnie), szerokość wstawianych wierszy będzie taka sama, jak szerokość określonego range. W przeciwnym razie wstawiony wiersz obejmie wszystkie kolumny arkusza.

rows: liczba wierszy do wstawienia. Wartość domyślna to wysokość oryginalnego range. Liczba wierszy musi być liczbą dodatnią.

### Przykład:

##### W języku Basic

        ' Przesuwa zakres "A3:D3" w dół o jeden wiersz; wpływa tylko na kolumny od A do D
        oDoc.ShiftDown("A3:D3")
        ' Wstawiony wiersz obejmuje wszystkie kolumny arkusza
        oDoc.ShiftDown("A3:D3", WholeRow := True)
        ' Przesuwa zakres "A3:D3" w dół o pięć wierszy
        oDoc.ShiftDown("A3:D3", Rows := 5)
        ' Przesuwa zakres "A3:D10" w dół o dwa wiersze i pokazuje nową lokalizację pierwotnego zakresu
        Dim sNewRange as String
        sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)
        MsgBox sNewRange   ' $Sheet1.$A$5:$D$12

##### W języku Python

        myDoc.ShiftDown("A3:D3")
        myDoc.ShiftDown("A3:D3", wholerow = True)
        myDoc.ShiftDown("A3:D3", rows = 5)
        sNewRange = myDoc.ShiftDown("A3:D10", rows = 2)
        bas = CreateScriptService("Basic")
        bas.MsgBox(sNewRange)

## ShiftLeft

Usuwa skrajne lewe kolumny danego zakresu i przesuwa w lewo wszystkie komórki na prawo od danego zakresu. Nie ma to wpływu na bieżący wybór.

W zależności od wartości argumentu wholecolumn usunięte kolumny mogą obejmować wysokość określonego zakresu lub wszystkie wiersze w kolumnie.

Ta metoda zwraca ciąg znaków reprezentujący lokalizację pozostałej części zakresu początkowego. Jeśli wszystkie komórki z pierwotnego zakresu zostały usunięte, zwracany jest pusty ciąg.

### Składnia:

svc.ShiftLeft(range: str, wholecolumn: bool = False, opt columns: int): str

### Parametry:

range: zakres, z którego komórki zostaną usunięte, jako ciąg.

wholecolumn: jeśli ustawiono wartość False (domyślnie), wówczas wysokość usuniętych kolumn będzie taka sama, jak wysokość określonego range. W przeciwnym razie usunięte kolumny obejmą wszystkie wiersze arkusza.

columns: liczba kolumn do usunięcia z określonego range. Wartość domyślna to szerokość oryginalnego range, który jest jednocześnie maksymalną wartością tego argumentu.

### Przykład:

##### W języku Basic

        ' Usuwa zakres "B3:B6"; przesuwa w lewo wszystkie komórki w prawo
        oDoc.ShiftLeft("B3:B6")
        ' Usuwa pierwszą kolumnę w zakresie "A3:D6"
        oDoc.ShiftLeft("A3:D6", Columns := 1)
        ' Usunięte kolumny (od A do D) obejmują wszystkie wiersze arkusza
        oDoc.ShiftLeft("A3:D6", WholeColumn := True)

##### W języku Python

        myDoc.ShiftLeft("B3:B6")
        myDoc.ShiftLeft("A3:D6", Columns = 1)
        myDoc.ShiftLeft("A3:D6", WholeColumn = True)

## ShiftUp

Usuwa najwyższe wiersze danego zakresu i przesuwa w górę wszystkie komórki poniżej dotkniętego zakresu. Nie ma to wpływu na bieżący wybór.

W zależności od wartości argumentu wholerow usunięte wiersze mogą obejmować szerokość określonego zakresu lub wszystkie kolumny w wierszu.

Ta metoda zwraca ciąg znaków reprezentujący lokalizację pozostałej części zakresu początkowego. Jeśli wszystkie komórki z pierwotnego zakresu zostały usunięte, zwracany jest pusty ciąg.

### Składnia:

svc.ShiftUp(range: str, wholerow: bool = False, opt rows: int): str

### Parametry:

range: zakres, z którego komórki zostaną usunięte, jako ciąg.

wholerow: jeśli ustawiono wartość False (domyślnie), szerokość usuniętych wierszy będzie taka sama, jak szerokość określonego range. W przeciwnym razie usunięty wiersz obejmie wszystkie kolumny w arkuszu.

rows: liczba wierszy do usunięcia z określonego range. Wartością domyślną jest wysokość oryginalnego range, która jest jednocześnie maksymalną wartością tego argumentu.

### Przykład:

##### W języku Basic

        ' Usuwa zakres "A3:D3"; przesuwa wszystkie komórki poniżej o jeden wiersz w górę
        oDoc.ShiftUp("A3:D3")
        ' Usuwa pierwszy wiersz w zakresie "A3:D6"
        oDoc.ShiftUp("A3:D6", Rows := 1)
        ' Usunięte wiersze obejmują wszystkie kolumny w arkuszu
        oDoc.ShiftUp("A3:D6", WholeRow := True)

##### W języku Python

        myDoc.ShiftUp("A3:D3")
        myDoc.ShiftUp("A3:D6", rows = 1)
        myDoc.ShiftUp("A3:D6", wholerow = True)

## ShiftRight

Przesuwa zadany zakres komórek w prawo poprzez wstawienie pustych kolumn. Nie ma to wpływu na bieżący wybór.

W zależności od wartości argumentu wholecolumn wstawione kolumny mogą obejmować wysokość określonego zakresu lub wszystkie wiersze w kolumnie.

Ta metoda zwraca ciąg znaków reprezentujący nową lokalizację zakresu początkowego.

Jeżeli przesunięty zakres przekracza krawędzie arkusza, to nic się nie dzieje.

### Składnia:

svc.ShiftRight(range: str, wholecolumn: bool = False, opt columns: int): str

### Parametry:

range: zakres, w którym po lewej stronie zostaną wstawione puste kolumny, jako ciąg znaków.

wholecolumn: jeśli ustawiono wartość False (domyślnie), wówczas wysokość wstawianych kolumn będzie taka sama, jak wysokość określonego range. W przeciwnym razie wstawione kolumny obejmą wszystkie wiersze arkusza.

columns: liczba kolumn do wstawienia. Wartość domyślna to szerokość oryginalnego range.

### Przykład:

##### W języku Basic

        ' Przesuwa zakres "A3:A6" w prawo o jedną kolumnę; wpływa tylko na wiersze od 3 do 6
        oDoc.ShiftRight("A3:A6")
        ' Przesuwa zakres "A3:A6" w prawo o pięć kolumn
        oDoc.ShiftRight("A3:A6", Columns := 5)
        ' Wstawiona kolumna obejmuje wszystkie wiersze arkusza
        oDoc.ShiftRight("A3:A6", WholeColumn := True)

##### W języku Python

        myDoc.ShiftRight("A3:A6")
        myDoc.ShiftRight("A3:A6", columns = 5)
        myDoc.ShiftRight("A3:A6", wholecolumn = True)

## SortRange

Sortuje podany zakres na podstawie zestawu kolumn/wierszy, które są uważane za klucze. Kolejność sortowania może się różnić w zależności od kolumny/wiersza. Zwraca ciąg reprezentujący zmodyfikowany zakres komórek. Rozmiar modyfikowanego obszaru jest w pełni zdeterminowany rozmiarem obszaru źródłowego.

### Składnia:

svc.SortRange(range: str, sortkeys: any, sortorder: any = "ASC", destinationcell: str = "", containsheader: bool = False, casesensitive: bool = False, sortcolumns: bool = False): str

### Parametry:

range: zakres do posortowania jako ciąg.

sortkeys: skalar (jeśli jest to 1 kolumna/wiersz) lub tablica numerów kolumn/wierszy zaczynająca się od 1.

sortorder: skalar lub tablica ciągów znaków zawierająca wartości "ASC" (rosnąco), "DESC" (malejąco) lub "" (domyślnie rosnąco). Każdy element jest sparowany z odpowiadającym mu elementem w sortkeys. Jeśli tablica sortorder jest krótsza niż sortorder, pozostałe klucze są sortowane w kolejności rosnącej.

destinationcell: komórka docelowa posortowanego zakresu komórek w postaci ciągu. Jeśli podany jest zakres, pod uwagę brana jest tylko jego lewa górna komórka. Domyślnie zakres źródłowy jest nadpisywany.

containsheader: gdy True, pierwszy wiersz/kolumna nie jest sortowany.

casesensitive: tylko do porównań ciągów. Domyślnie = False

sortcolumns: jeśli True, kolumny są sortowane od lewej do prawej. Domyślnie = False: wiersze są sortowane od góry do dołu.

### Przykład:

##### W języku Basic

        ' Sortuj zakres na podstawie kolumn A (rosnąco) i C (malejąco)
        oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)

##### W języku Python

        myDoc.SortRange("A2:J200", (1, 3), ("ASC", "DESC"), casesensitive = True)

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.

Tematy pokrewne

Usługa SFDocuments.Chart

Usługa SFDocuments.Document

Usługa ScriptForge.UI