Съдържание
Индекс 🔎︎

# Услуга SFDocuments.Calc

Споделената библиотека SFDocuments предлага набор от методи и свойства за улесняване управлението и боравенето с документи на LibreOffice.

Услугата SFDocuments.Calc е подклас на услугата SFDocuments.Document. Всички методи и свойства, дефинирани за услугата Document, са достъпни и през екземпляр на услугата Calc.

Услугата Calc е предназначена основно за:

- боравене с листове в документ на Calc (копиране, вмъкване, преместване и т.н.)

- обмен на данни между структури от данни на Basic и диапазони на Calc

- копиране и импортиране на големи количества данни.

Тази страница от помощта описва методи и свойства, приложими само за документи на Calc.

## Извикване на услугата

Преди да използвате услугата Calc, библиотеката ScriptForge трябва да бъде заредена или импортирана:

• Макросите на Basic изискват зареждане на библиотеката ScriptForge чрез следния оператор:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Скриптовете на Python изискват импортиране от модула scriptforge:
from scriptforge import CreateScriptService

Услугата Calc е тясно свързана с услугата UI на библиотеката ScriptForge. Следват няколко примера за обръщения към услугата Calc.

##### В Basic

Долният програмен фрагмент създава екземпляр на услугата Calc, който съответства на текущо активния документ на Calc.

        Set oDoc = CreateScriptService("Calc")

Друг начин да се създаде екземпляр на услугата Calc, е да се използва услугата UI. В следващия пример се създава нов документ на Calc и oDoc е екземпляр на услугата Calc:

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

Или чрез метода OpenDocument на услугата UI:

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

Екземпляр на услугата Calc може да се създаде и като се зададе име на прозорец за метода CreateScriptService:

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

В горния пример "MyFile.ods" е името на отворен прозорец с документ. Ако този аргумент не е подаден, се взема предвид текущият прозорец.

Обръщение към услугата Calc може да се осъществи и чрез документа, сочен от ThisComponent. Това е особено полезно при изпълнение на макрос от развойната среда на Basic.

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

Препоръчва се ресурсите да бъдат освободени след употреба:

        Set oDoc = oDoc.Dispose()

Ако обаче документът бъде затворен с метода CloseDocument, освобождаването на ресурсите с гореописаната команда става излишно.

##### В 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)

Използването на префикса "SFDocuments." при извикването на услугата не е задължително.

## Определения

Много методи изискват като аргумент "Sheet" (лист) или "Range" (диапазон). Единичните клетки се смятат за частен случай на диапазон – Range.

И двете могат да бъдат изразени като низ или като референция (= обект) според ситуацията:

- В рамките на конкретен екземпляр на Calc листовете и диапазоните се подават като низове от рода на "Лист1" и "D2:F6".

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

### Пример:

Примерът по-долу копира данни от документа A (отворен само за четене и скрит) към документа B.

##### В 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)

##### В 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

Или името на листа като низ, или обект, получен чрез свойството .Sheet.

Съкращението "~" (тилда) представя текущия лист.

### RangeName

Или низ, обозначаващ съвкупност от съседни клетки в лист на текущия екземпляр, или обект, получен чрез свойството .Range.

Съкращението "~" (тилда) представя текущата селекция или първия избран диапазон, ако са избрани няколко диапазона.

Съкращението "*" представя всички използвани клетки.

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

Когато се задава SheetName (име на лист) като низ, ограждането на името на листа с единични кавички е задължително, ако то съдържа интервали " " или точки ".".

Долните примери илюстрират в кои случаи е задължителна употребата на единични кавички:

          ' Единичните кавички не са задължителни.
          oDoc.clearAll("SheetA.A1:B10")
          oDoc.clearAll("'SheetA'.A1:B10")
          ' Единичните кавички са задължителни.
          oDoc.clearAll("'Sheet.A'.A1:B10")

С изключение на свойството CurrentSelection услугата Calc работи само с единични диапазони от клетки.

Примери за валидни диапазони
1) $'ЛистX'.D2 2) $D$2 | Единична клетка
1) $'ЛистX'.D2:F6 2) D2:D10 | Единичен диапазон с няколко клетки
$'ЛистX'.* | Всички използвани клетки в дадения лист
1) $'ЛистX'.A:A (колона A) 2) 3:5 (редове от 3 до 5) | Всички клетки в непрекъснати колони или редове до последната използвана клетка
моятДиапазон | Диапазон с име „моятДиапазон“ на ниво електронна таблица
1) ~.диапазон 2) SheetX.диапазон | Име на диапазон на ниво лист
myDoc.Range("ЛистX.D2:F6") | Диапазон в листа ЛистX във файла, свързан с екземпляра myDoc на услугата Calc
~.~ или ~ | Текущата селекция в активния лист

## Свойства

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

Свойствата, налични специално за документи на Calc, са:

Име | Само за четене | Аргумент | Тип на резултата | Описание
--- | --- | --- | --- | ---
CurrentSelection | Не | Няма | Низ или масив от низове | Единичният избран диапазон като низ или списъкът на избраните диапазони като масив.
FirstCell | Да | SheetName или RangeName As String | String | Връща първата използвана клетка в даден диапазон или лист.
FirstColumn | Да | SheetName или RangeName As String | Long | Връща номера на най-лявата колона в даден диапазон или лист.
FirstRow | Да | SheetName или RangeName As String | Long | Връща номера на най-горния ред в даден диапазон или лист.
Height | Да | RangeName As String | Long | Броят редове (>= 1) в дадения диапазон.
LastCell | Да | SheetName или RangeName As String | String | Връща последната използвана клетка в даден диапазон или лист.
LastColumn | Да | SheetName или RangeName As String | Long | Последната използвана колона в даден диапазон или лист.
LastRow | Да | SheetName или RangeName As String | Long | Последният използван ред в даден диапазон или лист.
Range | Да | RangeName As String | Object | Референция към диапазон, която може да бъде използвана като аргумент на методи като CopyToRange.
Region | Да | RangeName As String | String | Връща адреса на най-малката област, която съдържа указания диапазон и е оградена от празни клетки или краищата на листа. Това е еквивалентно на прилагането на комбинацията Command + *Ctrl + * върху дадения диапазон.
Sheet | Да | SheetName As String | Object | Референция към лист, която може да бъде използвана като аргумент на методи като CopySheet.
SheetName | Да | RangeName As String | String | Връща името на листа по даден адрес на диапазон.
Sheets | Да | Няма | Масив от низове | Списъкът с имената на всички съществуващи листове.
Width | Да | RangeName As String | Long | Броят колони (>= 1) в дадения диапазон.
XCellRange | Да | RangeName As String | Object | UNO обект com.sun.star.Table.XCellRange.
XSheetCellCursor | Да | RangeName As String | Object | UNO обект com.sun.star.sheet.XSheetCellCursor. След преместване на курсора адресът на резултатния диапазон може да бъде получен чрез UNO свойството AbsoluteName на обекта курсор, което връща низова стойност, използваема като аргумент за свойствата и методите на услугата Calc.
XSpreadsheet | Да | SheetName As String | Object | UNO обект com.sun.star.sheet.XSpreadsheet.

Посетете уебсайта с документацията на LibreOffice API, за да научите повече за UNO обектите XCellRange, XSheetCellCursor и XSpreadsheet.

## Методи

Списък с методи на услугата 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 RemoveSheet RenameSheet SetArray SetCellStyle SetFormula SetValue ShiftDown ShiftLeft ShiftRight ShiftUp SortRange

## A1Style

Връща адрес на диапазон като низ на базата на координати в лист, т.е. номера на редове и колони.

Ако е подадена само една двойка координати, се връща адрес на единична клетка. Допълнителни аргументи могат да указват долния десен ъгъл на правоъгълен диапазон.

### Синтаксис:

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

### Параметри:

row1, column1: указват номера на реда и номера на колоната на горната лява клетка в разглеждания диапазон. Номерата на редове и колони започват от 1.

row2, column2: указват номера на ред и номера на колона на долната дясна клетка в разглеждания диапазон. Ако тези аргументи не са подадени, или ако са подадени стойности, по-малки от row1 и column1, се връща адресът на единичната клетка, представена от row1 и column1.

sheetname: името на листа, което да бъде добавено към връщания адрес на диапазон. Листът трябва да съществува. Подразбираната стойност е "~", съответстваща на текущия активен лист.

### Пример:

В примерите на Basic и Python по-долу се приема, че текущо активният лист е "Sheet1".

##### В 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

##### В 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

Методът A1Style може да бъде комбиниран с всяко от многото свойства и методи на услугата Calc, което изисква диапазон като аргумент, например GetValue, GetFormula, ClearAll и т.н.

## Activate

Ако аргументът sheetname е подаден, даденият лист се активира и става текущо избран. Ако аргументът отсъства, се активира прозорецът на документа.

### Синтаксис:

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

### Параметри:

sheetname: името на листа, който да бъде активиран в документа. Подразбираната стойност е празен низ, което означава, че ще бъде активиран прозорецът на документа, без да се променя активният лист.

### Пример:

Примерът по-долу активира листа с име "Sheet4" в текущо активния документ.

##### В Basic

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

##### В Python

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

Активирането на лист има смисъл само ако се извършва върху документ на Calc. За да се уверите, че е налице документ на Calc, можете да използвате свойството isCalc на обекта документ, което връща True, ако той е документ на Calc, и False в противен случай.

## Charts

Връща списъка с имената на всички обекти диаграми в даден лист или единичен екземпляр на услугата Chart.

- Ако е зададен само sheetname, се връща индексиран от нула масив, съдържащ имената на всички диаграми.

- Ако е подаден chartname, се връща единичен обект, съответстващ на желаната диаграма. Указаната диаграма трябва да съществува.

### Синтаксис:

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

### Параметри:

sheetname: името на листа, от който трябва да се извлече списъкът с диаграми или в който се намира зададената диаграма.

chartname: зададеното от потребителя име на обекта диаграма, който да бъде върнат. Ако диаграмата няма име, дефинирано от потребителя, може да се използва вътрешното име на обекта. Ако този аргумент отсъства, се връща списъкът с имената на диаграмите в текущия лист.

Използвайте страничната лента Навигатор, за да проверите имената, присвоени на диаграмите, в категорията OLE обекти.

### Пример:

##### В Basic

Следващият пример показва броя обекти диаграми в "Sheet1":

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

Следващият пример осъществява достъп до диаграмата с име "MyChart" в листа "Sheet1" и отпечатва типа ѝ.

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

##### В 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

Изчиства цялото съдържание и форматите от дадения диапазон.

Може да се зададе филтрираща формула, за да се определи кои клетки да бъдат засегнати.

### Синтаксис:

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

### Параметри:

range: диапазонът, който да бъде изчистен, като низ.

filterformula: формула на Calc, която да бъде приложена върху дадения диапазон, за да се определи кои клетки да бъдат засегнати. Зададената формула трябва да връща True или False. Ако този аргумент не е подаден, се обработват всички клетки в диапазона.

filterscope: определя как filterformula се разширява до зададения диапазон. Този аргумент е задължителен, ако е зададен filterformula. Приемат се следните стойности:

- "CELL": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка клетка в range.

- "ROW": формулата, зададена в аргумента filterformula, се разширява по веднъж за всеки ред в range.

- "COLUMN": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка колона в range.

### Пример:

##### В Basic

        ' Изчиства всички клетки в диапазона ЛистX.A1:J10
        oDoc.ClearAll("ЛистX.A1:J10")
        ' Изчиства всички клетки в диапазона ЛистX.A1:J10, чиято стойност е по-голяма от 100.
        oDoc.ClearAll("ЛистX.A1:J10", "=ЛистX.A1>100", "CELL")
        ' Изчиства всички редове в диапазона ЛистX.A1:J10, чиято сума е по-голяма от 500.
        oDoc.ClearAll("ЛистX.A1:J10", "=SUM(ЛистX.A1:J1)>100", "ROW")
        ' Изчиства всички колони в диапазона ЛистX.A1:J10, чиято сума е по-голяма от 500.
        oDoc.ClearAll("ЛистX.A1:J10", "=SUM(ЛистX.A1:A10)>100", "COLUMN")

##### В Python

        myDoc.ClearAll("ЛистX.A1:F10")
        myDoc.ClearAll("ЛистX.A1:J10", "=ЛистX.A1>100", "CELL")
        myDoc.ClearAll("ЛистX.A1:J10", "=SUM(ЛистX.A1:J1)>100", "ROW")
        myDoc.ClearAll("ЛистX.A1:J10", "=SUM(ЛистX.A1:A10)>100", "COLUMN")

## ClearFormats

Изчиства форматите и стиловете в дадения диапазон.

Може да се зададе филтрираща формула, за да се определи кои клетки да бъдат засегнати.

### Синтаксис:

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

### Параметри:

range: диапазонът, чиито формати и стилове трябва да се изчистят, като низ.

filterformula: формула на Calc, която да бъде приложена върху дадения диапазон, за да се определи кои клетки да бъдат засегнати. Зададената формула трябва да връща True или False. Ако този аргумент не е подаден, се обработват всички клетки в диапазона.

filterscope: определя как filterformula се разширява до зададения диапазон. Този аргумент е задължителен, ако е зададен filterformula. Приемат се следните стойности:

- "CELL": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка клетка в range.

- "ROW": формулата, зададена в аргумента filterformula, се разширява по веднъж за всеки ред в range.

- "COLUMN": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка колона в range.

### Пример:

##### В Basic

          oDoc.ClearFormats("SheetX.*")

##### В Python

        myDoc.ClearFormats("SheetX.*")

Вижте документацията на метода ClearAll по-горе за примери как се използват аргументите filterformula и filterscope.

## ClearValues

Изчиства стойностите и формулите в дадения диапазон.

Може да се зададе филтрираща формула, за да се определи кои клетки да бъдат засегнати.

### Синтаксис:

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

### Параметри:

range: диапазонът, чиито стойности и формули трябва да се изчистят, като низ.

filterformula: формула на Calc, която да бъде приложена върху дадения диапазон, за да се определи кои клетки да бъдат засегнати. Зададената формула трябва да връща True или False. Ако този аргумент не е подаден, се обработват всички клетки в диапазона.

filterscope: определя как filterformula се разширява до зададения диапазон. Този аргумент е задължителен, ако е зададен filterformula. Приемат се следните стойности:

- "CELL": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка клетка в range.

- "ROW": формулата, зададена в аргумента filterformula, се разширява по веднъж за всеки ред в range.

- "COLUMN": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка колона в range.

### Пример:

##### В Basic

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

##### В Python

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

Вижте документацията на метода ClearAll по-горе за примери как се използват аргументите filterformula и filterscope.

## CompactLeft

Изтрива колоните на зададен диапазон, които съответстват на филтър, изразен като формула на Calc. Филтърът се прилага върху всяка колона, за да се реши дали да бъде изтрита.

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

Този метод връща низ с адреса на уплътнения диапазон. Ако всички колони са изтрити, се връща празен низ.

Ако е избран диапазон от клетки, извикването на този метод няма да повлияе върху селекцията.

### Синтаксис:

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

### Параметри:

range: диапазонът, от който ще бъдат изтрити колони, като низ.

wholecolumn: ако тази настройка има стойност True, целите колони ще бъдат изтрити от листа. Подразбираната стойност е False, която означава, че изтриваните колони ще бъдат ограничени до височината на зададения диапазон range.

filterformula: филтърът, който да бъде приложен върху всяка колона, за да се определи дали да бъде изтрита. Филтърът е изразен като формула на Calc, която трябва да се приложи върху първата колона. Когато формулата върне True за някоя колона, тази колона ще бъде изтрита. Подразбираният филтър изтрива всички празни колони.

Например, да кажем, че е избран диапазонът A1:J200 (височина = 200), така че подразбираната формула е =(COUNTBLANK(A1:A200)=200). Това означава, че ако всичките 200 клетки в първата колона (колона A) са празни, колоната се изтрива. Обърнете внимание, че формулата е построена само спрямо първата колона. Методът CompactLeft ще я обобщи вътрешно за всички останали колони.

Функциите на Calc, използвани в аргумента filterformula, трябва да са изразени с английските си имена. Посетете уикистраницата List of Calc Functions за пълен списък с функциите на Calc на английски.

### Пример:

##### В Basic

        ' Изтриваме всички празни колони в диапазона G1:L10 от Лист1.
        newrange = oDoc.CompactLeft("Лист1.G1:L10")
        ' Примерът по-долу е подобен, но целите колони се изтриват от листа.
        newrange = oDoc.CompactLeft("Лист1.G1:L10", WholeColumn := True)
        ' Изтрива всички колони, в които първият ред е отбелязан с "X".
        newrange = oDoc.CompactLeft("Лист1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Изтрива всички колони, за които сумата на стойностите в колоната е нечетна.
        newrange = oDoc.CompactLeft("Лист1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")

##### В Python

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

## CompactUp

Изтрива редовете на зададен диапазон, които съответстват на филтър, изразен като формула на Calc. Филтърът се прилага върху всеки ред, за да се реши дали да бъде изтрит.

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

Този метод връща низ с адреса на уплътнения диапазон. Ако всички редове са изтрити, се връща празен низ.

Ако е избран диапазон от клетки, извикването на този метод няма да повлияе върху селекцията.

### Синтаксис:

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

### Параметри:

range: диапазонът, от който ще бъдат изтрити редове, като низ.

wholerow: ако тази настройка има стойност True, целите редове ще бъдат изтрити от листа. Подразбираната стойност е False, която означава, че изтриваните редове ще бъдат ограничени до ширината на зададения диапазон range.

filterformula: филтърът, който да бъде приложен върху всеки ред, за да се определи дали да бъде изтрит. Филтърът е изразен като формула на Calc, която трябва да се приложи върху първия ред. Когато формулата върне True за някой ред, този ред ще бъде изтрит. Подразбираният филтър изтрива всички празни редове.

Например, да кажем, че е избран диапазонът A1:J200 (ширина = 10), така че подразбираната формула е =(COUNTBLANK(A1:J1)=10). Това означава, че ако всичките 10 клетки в първия ред (ред 1) са празни, редът се изтрива. Обърнете внимание, че формулата е построена само спрямо първия ред. Методът CompactUp ще я обобщи вътрешно за всички останали редове.

Функциите на Calc във формулата, зададена с аргумента filterformula, трябва да са изразени с английските си имена. Посетете уикистраницата List of Calc Functions за пълен списък с функциите на Calc на английски.

### Пример:

##### В Basic

        ' Изтриваме всички празни редове в диапазона G1:L10 от Лист1.
        newrange = oDoc.CompactUp("Лист1.G1:L10")
        ' Примерът по-долу е подобен, но целите редове се изтриват от листа.
        newrange = oDoc.CompactUp("Лист1.G1:L10", WholeRow := True)
        ' Изтрива всички редове, в които първата колона е отбелязана с "X".
        newrange = oDoc.CompactUp("Лист1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Изтрива всички редове, за които сумата на стойностите в реда е нечетна.
        newrange = oDoc.CompactUp("Лист1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")

##### В Python

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

## CopySheet

Копира указан лист преди съществуващ лист или в края на списъка с листове. Копираният лист трябва да е в някой отворен документ на Calc. Връща True при успех.

### Синтаксис:

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

### Параметри:

sheetname: името на листа, който да бъде копиран, като низ, или референция към обекта му.

newname: името на листа, който да бъде вмъкнат. Името не трябва да е вече използвано в документа.

beforesheet: името (низ) или индексът (число, броено от 1) на листа, преди който да бъде вмъкнат копираният лист. Този аргумент е незадължителен и подразбираното поведение е копираният лист да се добави на последна позиция.

### Пример:

##### В Basic

Следващият пример създава копие на листа "SheetX" и го вмъква като последен лист в текущия документ. Името на копирания лист е "SheetY".

        Dim oDoc as Object
        ' Получава обекта Document на текущия прозорец.
        Set oDoc = CreateScriptService("Calc")
        oDoc.CopySheet("SheetX", "SheetY")

Долният пример копира "SheetX" от "FileA.ods" и го поставя на последната позиция във "FileB.ods" с името "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")

##### В 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")

За да копирате листове между отворени документи, използвайте CopySheet. За да копирате листове от документи, които са затворени, използвайте CopySheetFromFile.

## CopySheetFromFile

Копира указан лист от затворен документ на Calc и го поставя преди съществуващ лист или в края на списъка с листове на файла, сочен от обект Document.

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

### Синтаксис:

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

### Параметри:

filename: посочва кой файл да бъде отворен. Трябва да следва нотацията, зададена с SF_FileSystem.FileNaming. Файлът не трябва да е защитен с парола.

sheetname: името на листа, който да бъде копиран, като низ.

newname: името на копирания лист, който да бъде вмъкнат в документа. Името не трябва да е вече използвано в документа.

beforesheet: името (низ) или индексът (число, броено от 1) на листа, преди който да бъде вмъкнат копираният лист. Този аргумент е незадължителен и подразбираното поведение е копираният лист да се добави на последна позиция.

### Пример:

Следващият пример копира "SheetX" от "myFile.ods" и го поставя в документа, сочен от "oDoc", под името "SheetY", на първа позиция.

##### В Basic

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

##### В Python

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

## CopyToCell

Копира указан диапазон източник (стойности, формули и формати) към диапазон или клетка местоназначение. Този метод възпроизвежда поведението на операция „копиране и поставяне“ от диапазон към единична клетка.

Връща низ, представящ променения диапазон от клетки. Размерът на променената област изцяло се определя от размера на областта източник.

Диапазонът източник може да принадлежи на друг отворен документ.

### Синтаксис:

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

### Параметри:

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

destinationcell: клетката местоназначение, където ще бъде поставен копираният диапазон от клетки, като низ. Ако е подаден диапазон, се взема предвид само горната му лява клетка.

### Пример:

##### В Basic

Следва пример, в който източникът и местоназначението са в един и същ файл:

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

Долният пример показва как да копирате диапазон от друг отворен документ на Calc.

        Dim ui as Variant : ui = CreateScriptService("UI")
        Dim oDocSource As Object, oDocDestination As Object
        ' Отваряме документа източник във фонов режим (скрито)
        Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
        Set oDocDestination = CreateScriptService("Calc")
        oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
        ' Не забравяйте да затворите документа източник, защото той е отворен като „скрит“.
        oDocSource.CloseDocument()

##### В 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()

За да симулирате копиране и поставяне от диапазон в единична клетка, използвайте CopyToCell. За да симулирате копиране и поставяне от диапазон в по-голям диапазон (със същите клетки, размножени неколкократно), използвайте CopyToRange.

## CopyToRange

Копира надолу и/или надясно указан диапазон източник (стойности, формули и формати) в диапазон местоназначение. Този метод имитира поведението на операция „копиране и поставяне“ от диапазон източник към по-голям диапазон местоназначение.

- Ако височината (или ширината) на областта местоназначение е > 1 ред (или колона), височината (или ширината) на източника трябва да е <= височината (или ширината) на местоназначението. В противен случай не става нищо.

- Ако височината (или ширината) на местоназначението е = 1, то се разширява надолу (или надясно) до височината (или ширината) на диапазона източник.

Методът връща низ, представящ променения диапазон от клетки.

Диапазонът източник може да принадлежи на друг отворен документ.

### Синтаксис:

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

### Параметри:

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

destinationrange: местоназначението на копирания диапазон от клетки, като низ.

### Пример:

##### В Basic

Копиране в рамките на същия документ:

        oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
        ' Връща низ за диапазон: "$SheetY.$C$5:$J$14"

Копиране от един файл в друг:

        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")

##### В 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

Създава нов обект диаграма, показващ данните в указания диапазон. Върнатият обект диаграма може да бъде управляван впоследствие чрез услугата Chart.

### Синтаксис:

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

### Параметри:

chartname: дефинираното от потребителя име за създаваната диаграма. Името трябва да е уникално в рамките на листа.

sheetname: името на листа, в който да бъде разположена диаграмата.

range: диапазонът, който да се използва като източник на данни за диаграмата. Може да сочи към всеки лист от документа на Calc.

columnheader: когато е True, най-горният ред на диапазона се използва като надписи за оста на категориите или легендата (подразбира се False).

rowheader: когато е True, най-лявата колона на диапазона се използва като надписи за оста на категориите или легендата (подразбира се False).

### Пример:

Примерите по-долу на Basic и Python създават диаграма с данните от диапазона "A1:B5" на листа "Sheet1" и я разполагат в "Sheet2".

##### В Basic

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

##### В Python

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

Вижте помощната страница за услугата Chart на ScriptForge, за да научите повече за боравенето с обекти диаграми. Могат да се променят свойства като типа на диаграмата, заглавията на диаграмата и на осите и позицията на диаграмата.

## CreatePivotTable

Създава нова обобщена таблица със свойства, определени от подадените към метода аргументи.

За обобщената таблица трябва да бъде зададено име. Ако в листа цел вече има обобщена таблица със същото име, тя ще бъде заместена без предупреждение.

Този метод връща низ, съдържащ диапазона, в който е разположена новата обобщена таблица.

### Синтаксис:

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

### Параметри:

pivottablename: дефинираното от потребителя име на новата обобщена таблица.

sourcerange: диапазонът, съдържащ началните данни, като низ. Приема се, че първата колона съдържа имената на полетата, използвани в обобщената таблица.

targetcell: горната лява клетка, от която да бъде разположена новата обобщена таблица. Ако е зададен диапазон, се взема предвид само горната му лява клетка.

datafields: може да бъде единичен низ или масив с низове, които дефинират имената на полетата и функциите, които да бъдат приложени. Когато е зададен масив, той трябва да следва синтаксиса Array("ИмеНаПоле[;Функция]", ...).

Разрешените функции са: Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP и Median. Имената на функциите трябва да бъдат на английски. Когато всички стойности са числови, се подразбира функцията Sum, в противен случай – функцията Count.

rowfields: единичен низ или масив с имената на полета, които да бъдат използвани за редовете на обобщената таблица.

columnfields: единичен низ или масив с имената на полета, които да бъдат използвани за колоните на обобщената таблица.

filterbutton: определя дали над обобщената таблица да се показва бутон за филтриране (подразбира се True).

rowtotals: указва дали към обобщената таблица да се добави отделна колона за суми на редовете (подразбира се True).

columntotals: указва дали към обобщената таблица да се добави отделен ред за суми на колоните (подразбира се True).

### Пример:

##### В 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("Стока", "Град", "Екип", "2002", "2003", "2004"), _
            Array("Книги", "Пловдив", "Иван", 14788, 30222, 23490), _
            Array("Бонбони", "Пловдив", "Иван", 26388, 15641, 32849), _
            Array("Химикалки", "Пловдив", "Иван", 16569, 32675, 25396), _
            Array("Книги", "Пловдив", "Петя", 21961, 21242, 29009), _
            Array("Бонбони", "Пловдив", "Петя", 26142, 22407, 32841))
        sTable = oDoc.SetArray("A1", vData)
        sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _
            Array("2002", "2003;count", "2004;average"), _ ' Три полета с данни
            "Стока", _ ' Едно поле за редове
            Array("Град", "Екип"), False) ' Две полета за колони

##### В Python

        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Calc")
        vData = [["Стока", "Град", "Екип", "2002", "2003", "2004"],
                 ["Книги", "Пловдив", "Иван", 14788, 30222, 23490],
                 ["Бонбони", "Пловдив", "Иван", 26388, 15641, 32849],
                 ["Химикалки", "Пловдив", "Иван", 16569, 32675, 25396)],
                 ["Книги", "Пловдив", "Петя", 21961, 21242, 29009],
                 ["Бонбони", "Пловдив", "Петя", 26142, 22407, 32841]]
        sTable = doc.SetArray("A1", vData)
        sPivot = doc.CreatePivotTable("PT1", sTable, "H1",
                                      ["2002", "2003;count", "2004;average"],
                                      "Стока",
                                      ["Град", "Екип"], False)

За да научите повече за обобщените таблици в LibreOffice Calc, прочетете помощната страница Обобщени таблици.

## DAvg, DCount, DMax, DMin and DSum

Прилагане на функциите съответно Average, Count, Max, Min или Sum върху всички клетки с числови стойности в даден диапазон.

### Синтаксис:

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

### Параметри:

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

### Пример:

Примерът по-долу прилага функцията Sum върху диапазона "A1:A1000" на текущо избрания лист:

##### В Basic

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

##### В Python

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

Клетките в зададения диапазон, които съдържат текст, ще бъдат игнорирани от всички тези функции. Например методът DCount няма да брои клетките с текст, а само тези с числа.

## ExportRangeToFile

Експортира указания диапазон като изображение или PDF файл.

Този метод връща True, ако файлът местоназначение е създаден успешно.

Скритите редове и колони в зададения диапазон не се експортират във файла местоназначение.

### Синтаксис:

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

### Параметри:

range: име на лист или диапазон от клетки, който да бъде експортиран, като низ.

filename: името на файла, който да бъде записан. То трябва да следва нотацията, зададена с SF_FileSystem.FileNaming.

imagetype: определя типа на файла местоназначение. Възможни стойности са "jpeg", "pdf" (подразбира се) и "png".

overwrite: когато е True, файлът местоназначение може да бъде презаписан (подразбира се False).

### Пример:

##### В Basic

        ' Експортира целия лист като PDF файл.
        oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
        ' Експортира диапазона като PNG файл и презаписва файла местоназначение, ако той съществува.
        oDoc.ExportRangeToFile("SheetX.A1:D10", "C:\Temp\image.png", "png", Overwrite := True)

##### В Python

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

## Forms

В зависимост от подадените параметри, този метод връща:

- индексиран от нула масив (или кортеж в Python) с имената на всички формуляри, съдържащи се в даден лист (ако отсъства аргументът form)

- екземпляр на услугата SFDocuments.Form, представящ зададения като аргумент формуляр.

### Синтаксис:

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

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

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

### Параметри:

sheetname: името на листа, от който ще бъде извлечен формулярът, като низ.

form: името или индексът на формуляр, съхраняван в посочения лист. Ако този аргумент отсъства, методът ще върне списък с имената на всички формуляри, налични в листа.

### Пример:

В следващите примери първият ред получава имената на всички формуляри, съхранявани в "Sheet1", а вторият извлича обекта Form на формуляра с име "Form_A", който се съхранява в "Sheet1".

##### В Basic

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

##### В Python

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

## GetColumnName

Преобразува номер на колона между 1 и 1024 в съответните букви (колона A, B, …, AMJ). Ако даденият номер на колона е извън допустимия диапазон, се връща низ с нулева дължина.

### Синтаксис:

svc.GetColumnName(columnnumber: int): str

### Параметри:

columnnumber: номерът на колона като целочислена стойност в интервала 1 – 1024.

### Пример:

##### В Basic

Показва прозорец за съобщение с името на третата колона, което по подразбиране е "C".

        MsgBox oDoc.GetColumnName(3)

##### В Python

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

Максималният брой колони, разрешен в лист на Calc, е 1024.

## GetFormula

Получаване на формулата или формулите в дадения диапазон от клетки като единичен низ, едномерен или двумерен масив от низове.

Имената на функциите на Calc във върнатите формули са на английски. Посетете уикистраницата List of Calc Functions за пълен списък с функциите на Calc на английски.

### Синтаксис:

svc.GetFormula(range: str): any

### Параметри:

range: диапазонът, от който да бъдат извлечени формулите, като низ.

### Пример:

##### В Basic

Следващият пример връща масив с размери 3 на 2 с формулите в диапазона "A1:B3" (3 реда на 2 колони):

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

##### В Python

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

## GetValue

Получаване на стойността или стойностите, съхранявани в дадения диапазон, като единична стойност, едномерен масив или двумерен масив. Всички стойности са или числа от тип double, или низове.

### Синтаксис:

svc.GetValue(range: str): any

### Параметри:

range: диапазонът, от който да бъдат извлечени стойностите, като низ.

### Пример:

##### В Basic

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

##### В Python

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

Ако някоя клетка съдържа дата, се връща числото, съответстващо на датата. За преобразуване на числови стойности в дати в скриптове на Basic използвайте вградената функция вградената функция CDate. В скриптове на Python използвайте функцията CDate от услугата Basic.

## ImportFromCSVFile

Импортира съдържанието на текстов файл във формат CSV и го разполага върху дадена клетка местоназначение.

Преди да се вмъкне съдържанието на CSV файла, областта местоназначение се изчиства от всякакво съдържание и формати. Размерът на променената област се определя изцяло от съдържанието на входния файл.

Методът връща низ, представящ променения диапазон от клетки.

### Синтаксис:

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

### Параметри:

filename: името на файла, който да бъде отворен. То трябва да следва нотацията, зададена с SF_FileSystem.FileNaming.

destinationcell: клетката местоназначение за вмъкване на импортираните данни, като низ. Ако вместо това е подаден диапазон, се взема предвид само горната му лява клетка.

filteroptions: аргументите за входния филтър за CSV. Подразбираният филтър прави следните предположения:

- Кодирането на входния файл е UTF8.

- Разделителят на полета е запетая, точка и запетая или знак за табулация.

- Разделителят за низове е двойна кавичка (").

- Включват се всички редове.

- Низовете в кавички се форматират като текст.

- Разпознават се специални числа.

- Всички колони се приемат за текстови, освен ако се разпознаят като валидни числа.

- Езикът е английски/САЩ, което означава десетичен разделител "." и разделител на хилядите ",".

### Пример:

##### В Basic

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

##### В Python

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

За да научите повече за настройките на филтъра за CSV, вижте помощната страница „Настройки на филтъра за CSV“.

## ImportFromDatabase

Импортира от база от данни съдържанието на таблица, заявка или резултатен набор, т.е. резултат от команда SELECT на SQL, и го вмъква върху клетка местоназначение.

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

Методът връща True, когато импортирането е успешно.

### Синтаксис:

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

### Параметри:

filename: името на файла, който да бъде отворен. То трябва да следва нотацията, зададена с SF_FileSystem.FileNaming.

registrationname: името, чрез което базата от данни да бъде намерена в регистъра на бази от данни. Този аргумент се игнорира, ако е подаден filename.

destinationcell: местоназначението на импортираните данни като низ. Ако е подаден диапазон, се взема предвид само горната му лява клетка.

sqlcommand: име на таблица или заявка (без ограждащи кавички или квадратни скоби) или оператор SELECT на SQL, в който имената на таблици и полета може да са оградени с квадратни скоби или кавички за по-добра четливост.

directsql: когато е True, командата на SQL се изпраща към СУБД без предварителен анализ. Подразбира се False. Аргументът се игнорира за таблици. За заявки прилаганата настройка е тази, която е била зададена при създаване на заявката.

### Пример:

##### В Basic

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

##### В Python

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

## InsertSheet

Вмъква нов празен лист преди съществуващ лист или в края на списъка с листове.

### Синтаксис:

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

### Параметри:

sheetname: името на новия лист.

beforesheet: името (низ) или индексът (число, броено от 1) на листа, преди който да бъде вмъкнат новият лист. Този аргумент е незадължителен и подразбираното поведение е листът да се вмъкне на последна позиция.

### Пример:

Следният пример вмъква нов празен лист с име "SheetX" преди "SheetY":

##### В Basic

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

##### В Python

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

## MoveRange

Премества указан диапазон източник към диапазон местоназначение. Методът връща низ, представящ променения диапазон от клетки. Размерите на променената област се определят изцяло от размера на областта източник.

### Синтаксис:

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

### Параметри:

source: диапазонът от клетки – източник, като низ.

destination: клетката местоназначение, като низ. Ако е подаден диапазон, за местоназначение се взема горната му лява клетка.

### Пример:

##### В Basic

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

##### В Python

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

## MoveSheet

Премества съществуващ лист и го поставя преди указан лист или в края на списъка с листове.

### Синтаксис:

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

### Параметри:

sheetname: името на листа, който да бъде преместен. Листът трябва да съществува, иначе възниква изключение.

beforesheet: името (низ) или индексът (число, броено от 1) на листа, преди който да бъде поставен оригиналният лист. Този аргумент е незадължителен и подразбираното поведение е листът да се премести на последна позиция.

### Пример:

Примерът по-долу премества съществуващия лист "SheetX" и го поставя преди "SheetY":

##### В Basic

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

##### В Python

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

## Offset

Връща нов диапазон (като низ), отместен с определен брой редове и колони от даден диапазон.

Този метод се държи по същия начин като едноименната функция Offset на Calc.

### Синтаксис:

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

### Параметри:

reference: диапазонът, като низ, който методът ще използва като отправна точка за операцията отместване.

rows: броят колони, с които началният диапазон да бъде отместен нагоре (отрицателна стойност) или надолу (положителна стойност). Използвайте 0 (подразбира се), за да го оставите на същия ред.

columns: броят колони, с които началният диапазон да бъде отместен наляво (отрицателна стойност) или надясно (положителна стойност). Използвайте 0 (подразбира се), за да го оставите на същата колона.

height: височината на областта, която започва от новата позиция на диапазона. Пропуснете този аргумент, ако не е необходимо преоразмеряване по вертикала.

width: ширината на областта, която започва от новата позиция на диапазона. Пропуснете този аргумент, ако не е необходимо преоразмеряване по хоризонтала.

Аргументите rows и columns не трябва да водят до нулев или отрицателен начален ред или колона.

Аргументите height и width не трябва да водят до нулев или отрицателен брой редове или колони.

### Пример:

##### В Basic

        oDoc.Offset("A1", 2, 2)
        'SheetX.$C$3 (A1, преместена с два реда надолу и две колони надясно)
        oDoc.Offset("A1", 2, 2, 5, 6)
        'SheetX.$C$3:$H$7 (A1, преместена с два реда и две колони и с размери 5 реда и 6 колони)

##### В Python

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

## OpenRangeSelector

Отваря немодален диалог за избиране на диапазон в документа и връща низ, съдържащ избрания диапазон.

Този метод отваря същия диалог, който се използва от LibreOffice при натискане на бутона „Свиване“. Например в диалога Инструменти - Удовлетворяване на условие има бутон „Свиване“ вдясно от полето Клетка с формула.

Този метод не променя текущата селекция.

### Синтаксис:

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

### Параметри:

title: заглавието на диалога като низ.

selection: незадължителен диапазон, който е избран отначало при показване на диалога.

singlecell: когато е True (подразбира се), може да се избира само единична клетка. Когато е False, е разрешено избирането на диапазон.

closeafterselect: ако е True (подразбира се), диалогът се затваря незабавно след като е направен избор. Ако е False, потребителят може да промени селекцията колкото пъти е необходимо и после ръчно да затвори диалога.

### Пример:

##### В Basic

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

##### В Python

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

## Printf

Връща входния низ, след като замести знаците маркери в него със стойностите им в даден диапазон.

Този метод не променя текущата селекция.

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

### Синтаксис:

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

### Параметри:

inputstr: низът с маркерите, които ще бъдат заменени със съответните стойности в range.

range: име на диапазон (RangeName), от който да бъдат извлечени стойностите. Ако то съдържа име на лист, листът трябва да съществува.

tokencharacter: знак, използван за означаване на маркерите. По подразбиране знакът за маркер е "%". Приемат се следните маркери:

- %S – името на листа, съдържащ диапазона, включително единични кавички, когато са необходими.

- %R1 – номерът на реда на горната лява клетка от диапазона.

- %C1 – буквата на колоната на горната лява клетка от диапазона.

- %R2 – номерът на реда на долната дясна клетка от диапазона.

- %C2 – буквата на колоната на долната дясна клетка от диапазона.

### Пример:

##### В Basic

Примерът по-долу извлича всички елементи от RangeName, дефиниран в sRange, и ги използва за съставяне на съобщение.

        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)

Методът Printf може да бъде комбиниран със SetFormula, за да се зададат формули в множество клетки. Да вземем например таблица с числови стойности в диапазона "A1:E10", от която трябва да се създадат формули, сумиращи стойностите от всеки ред, и резултатите да се разположат в диапазона "F1:F10":

        Dim sFormula as String, sRange as String
        sRange = "A1:E10"
        ' Обърнете внимание на употребата на знака "$".
        sFormula = "=SUM($%C1%R1:$%C2%R1)"
        oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))

##### В 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

Този метод изпраща съдържанието на дадения лист към подразбирания принтер или към принтера, зададен чрез метода SetPrinter на услугата Document.

Връща True, ако листът е бил успешно отпечатан.

### Синтаксис:

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

### Параметри:

sheetname: листът, който да се отпечата, подразбира се активният лист.

pages страниците, които да бъдат отпечатани, като низ, както в потребителския интерфейс. Пример: "1-4;10;15-18". Подразбират се всички страници.

copies: броят копия. Подразбира се 1.

### Пример:

##### В Basic

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

##### В Python

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

## RemoveSheet

Премахва съществуващ лист от документа.

### Синтаксис:

svc.RemoveSheet(sheetname: str): bool

### Параметри:

sheetname: името на листа за премахване.

### Пример:

##### В Basic

        oDoc.RemoveSheet("SheetY")

##### В Python

        myDoc.RemoveSheet("SheetY")

## RenameSheet

Преименува дадения лист и връща True при успех.

### Синтаксис:

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

### Параметри:

sheetname: името на листа, който да се преименува.

newname: новото име на листа. То не трябва да е вече съществуващо.

### Пример:

Този пример преименува активния лист на "SheetY":

##### В Basic

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

##### В Python

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

## SetArray

Съхранява дадената стойност, започвайки от указана целева клетка. Променената област започва от целевата клетка или горния ляв ъгъл на подадения диапазон и се простира до размера на входния аргумент value. Векторите винаги се разполагат вертикално.

Методът връща низ, представящ променената област като диапазон от клетки.

### Синтаксис:

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

### Параметри:

targetcell: клетката или диапазонът, където да е началото на съхранената стойност, като низ.

value: скалар, вектор или масив (в Python – едно- или двумерни списъци и кортежи) с новите стойности, които да се съхранят, започвайки от целевата клетка или от горния ляв ъгъл на диапазона, ако targetcell е диапазон. Новите стойности трябва да са низове, числа или дати. Други типове ще предизвикат изпразването на съответните клетки.

### Пример:

##### В Basic

В следващия пример с вградената функция DimArray се създава масив, който после се съхранява върху клетката "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)

В този пример с метода RangeInit на услугата ScriptForge се създава масив със стойности, който после се съхранява от клетката "A1" надолу.

        'Запълваме първата колона със стойности от 1 до 1000.
        oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))

##### В 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)))

За да разтоварите пълното съдържание на масив в лист, използвайте SetArray. За да разтоварите съдържанието на масив само в рамките на целевия диапазон от клетки, използвайте SetValue.

## SetCellStyle

Прилага указания стил за клетки върху дадения целеви диапазон. Променя се целият диапазон, а останалата част от листа остава незасегната. Ако стилът за клетки не съществува, възниква грешка.

Методът връща низ, представящ променената област като диапазон от клетки.

### Синтаксис:

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

### Параметри:

targetrange: диапазонът, върху който ще бъде приложен стилът, като низ.

style: името на стила за клетки, който да бъде приложен.

filterformula: формула на Calc, която да бъде приложена върху дадения диапазон, за да се определи кои клетки да бъдат засегнати. Зададената формула трябва да връща True или False. Ако този аргумент не е подаден, се обработват всички клетки в диапазона.

filterscope: определя как filterformula се разширява до зададения диапазон. Този аргумент е задължителен, ако е зададен filterformula. Приемат се следните стойности:

- "CELL": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка клетка в range.

- "ROW": формулата, зададена в аргумента filterformula, се разширява по веднъж за всеки ред в range.

- "COLUMN": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка колона в range.

### Пример:

##### В Basic

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

##### В Python

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

Вижте документацията на метода ClearAll по-горе за примери как се използват аргументите filterformula и filterscope.

## SetFormula

Вмъква дадената формула или масив от формули в указания диапазон. Размерът на променената област е равен на размера на диапазона.

Методът връща низ, представящ променената област като диапазон от клетки.

### Синтаксис:

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

### Параметри:

targetrange: диапазонът, в който да бъдат вмъкнати формулите, като низ.

formula: низ, вектор или масив от низове с новите формули за всички клетки от целевия диапазон.

Цялата област се обновява, а останалата част от листа остава непроменена.

Ако дадената формула е низ, уникалната формула се поставя из целия диапазон с коригиране на относителните обръщения.

Ако размерът на formula е по-малък от този на targetrange, оставащите клетки се изпразват.

Ако размерът на formula е по-голям от този на targetrange, формулите се копират само частично, докато се запълни размерът на targetrange.

Векторите винаги се разполагат вертикално, освен ако targetrange има височина от точно 1 ред.

Функциите на Calc, използвани в аргумента formula, трябва да са изразени с английските си имена. Посетете уикистраницата List of Calc Functions за пълен списък с функциите на Calc на английски.

### Пример:

##### В Basic

        oDoc.SetFormula("A1", "=A2")
        'Хоризонтален вектор, частично празен
        oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
        'D2 съдържа формулата "=H2".
        oDoc.SetFormula("A1:D2", "=E1")

##### В Python

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

## SetValue

Съхранява дадената стойност в указания диапазон. Размерът на променената област е равен на размера на целевия диапазон.

Методът връща низ, представящ променената област като диапазон от клетки.

### Синтаксис:

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

### Параметри:

targetrange: диапазонът, в който да бъде съхранена дадената стойност, като низ.

value: скалар, вектор или масив с новите стойности за всички клетки на диапазона. Новите стойности трябва да са низове, числа или дати. Други типове ще предизвикат изпразването на съответните клетки.

Целият диапазон се обновява, а останалата част от листа остава непроменена. Ако размерът на value е по-малък от този на targetrange, оставащите клетки се изпразват.

Ако размерът на value е по-голям от този на targetrange, value се копира само частично, докато се запълни размерът на targetrange.

Векторите се разполагат вертикално, освен ако targetrange има височина от точно 1 ред.

### Пример:

##### В Basic

        oDoc.SetValue("A1", 2)
        'По-долу масивът Value е по-малък от TargetRange (оставащите клетки се изпразват).
        oDoc.SetValue("A1:F1", Array(1, 2, 3))
        'По-долу Value и TargetRange имат еднакъв размер.
        oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))

Ако искате да запълните единичен ред със стойности, можете да използвате функцията Offset. В долния пример приемаме, че arrData е едномерен масив:

        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)

##### В 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

Премества даден диапазон от клетки надолу, като вмъква празни редове. Текущата селекция остава непроменена.

В зависимост от стойността на аргумента wholerow вмъкнатите редове могат да се простират или до ширината на указания диапазон, или през всички колони.

Този метод връща низ, представящ новото местоположение на началния диапазон.

Ако изместеният диапазон пресича границите на листа, не се случва нищо.

### Синтаксис:

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

### Параметри:

range: диапазонът, над който ще бъдат вмъкнати редове, като низ.

wholerow: ако е False (подразбира се), ширината на вмъкнатите редове ще бъде същата като на указания диапазон range. В противен случай вмъкнатите редове ще се простират през всички колони в листа.

rows: броят редове, които да бъдат вмъкнати. Подразбираната стойност е височината на оригиналния диапазон range. Броят редове трябва да е положително число.

### Пример:

##### В Basic

        ' Премества диапазона "A3:D3" с един ред надолу; засяга само колоните от A до D.
        oDoc.ShiftDown("A3:D3")
        ' Вмъкнатият ред се простира през всички колони в листа.
        oDoc.ShiftDown("A3:D3", WholeRow := True)
        ' Премества диапазона "A3:D3" надолу с пет реда.
        oDoc.ShiftDown("A3:D3", Rows := 5)
        ' Премества диапазона "A3:D10" надолу с два реда и показва новото местоположение на оригиналния диапазон.
        Dim sNewRange as String
        sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)
        MsgBox sNewRange   ' $Sheet1.$A$5:$D$12

##### В 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

Изтрива най-левите колони от даден диапазон и премества наляво всички клетки вдясно от засегнатите. Текущата селекция остава непроменена.

В зависимост от стойността на аргумента wholecolumn изтритите колони могат да се простират или до височината на указания диапазон, или през всички редове.

Този метод връща низ низ, представящ местоположението на оставащата част от началния диапазон. Ако са изтрити всички клетки от оригиналния диапазон, се връща празен низ.

### Синтаксис:

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

### Параметри:

range: диапазонът, от който ще бъдат изтрити клетки, като низ.

wholecolumn: ако е False (подразбира се), височината на изтритите колони ще бъде същата като на указания диапазон range. В противен случай изтритите колони ще се простират през всички редове в листа.

columns: броят колони, които да бъдат изтрити от указания диапазон range. Подразбира се ширината на оригиналния диапазон range, която е и максималната стойност на този аргумент.

### Пример:

##### В Basic

        ' Изтрива диапазона "B3:B6"; премества наляво всички клетки отдясно.
        oDoc.ShiftLeft("B3:B6")
        ' Изтрива първата колона в диапазона "A3:D6".
        oDoc.ShiftLeft("A3:D6", Columns := 1)
        ' Изтритите колони (от A до D) се простират през всички редове в листа.
        oDoc.ShiftLeft("A3:D6", WholeColumn := True)

##### В Python

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

## ShiftUp

Изтрива най-горните редове от даден диапазон и премества нагоре всички клетки под засегнатите. Текущата селекция остава непроменена.

В зависимост от стойността на аргумента wholerow изтритите редове могат да се простират или до ширината на указания диапазон, или през всички колони.

Този метод връща низ низ, представящ местоположението на оставащата част от началния диапазон. Ако са изтрити всички клетки от оригиналния диапазон, се връща празен низ.

### Синтаксис:

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

### Параметри:

range: диапазонът, от който ще бъдат изтрити клетки, като низ.

wholerow: ако е False (подразбира се), ширината на изтритите редове ще бъде същата като на указания диапазон range. В противен случай изтритите редове ще се простират през всички колони в листа.

rows: броят редове, които да бъдат изтрити от указания диапазон range. Подразбира се височината на оригиналния диапазон range, която е и максималната стойност на този аргумент.

### Пример:

##### В Basic

        ' Изтрива диапазона "A3:D3"; премества всички клетки под него с един ред нагоре.
        oDoc.ShiftUp("A3:D3")
        ' Изтрива първия ред в диапазона "A3:D6".
        oDoc.ShiftUp("A3:D6", Rows := 1)
        ' Изтритите редове се простират през всички колони в листа.
        oDoc.ShiftUp("A3:D6", WholeRow := True)

##### В Python

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

## ShiftRight

Премества даден диапазон от клетки надясно, като вмъква празни колони. Текущата селекция остава непроменена.

В зависимост от стойността на аргумента wholecolumn вмъкнатите колони могат да се простират или до височината на указания диапазон, или през всички редове.

Този метод връща низ, представящ новото местоположение на началния диапазон.

Ако изместеният диапазон пресича границите на листа, не се случва нищо.

### Синтаксис:

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

### Параметри:

range: диапазонът, вляво от който ще се вмъкват празни колони, като низ.

wholecolumn: ако е False (подразбира се), височината на вмъкнатите колони ще бъде същата като на указания диапазон range. В противен случай вмъкнатите колони ще се простират през всички редове в листа.

columns: броят колони, които да бъдат вмъкнати. Подразбираната стойност е ширината на оригиналния диапазон range.

### Пример:

##### В Basic

        ' Премества диапазона "A3:A6" надясно с една колона; засяга само редовете 3 – 6.
        oDoc.ShiftRight("A3:A6")
        ' Премества диапазона "A3:A6" надясно с пет колони.
        oDoc.ShiftRight("A3:A6", Columns := 5)
        ' Вмъкнатата колона се простира през всички редове в листа.
        oDoc.ShiftRight("A3:A6", WholeColumn := True)

##### В Python

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

## SortRange

Сортира дадения диапазон на базата на до 3 колони/реда. Редът на сортиране може да е различен за всяка колона/ред. Връща низ, представящ променения диапазон от клетки. Размерът на променената област се определя изцяло от размера на областта източник.

### Синтаксис:

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

### Параметри:

range: диапазонът, който да бъде сортиран, като низ.

sortkeys: скалар (при 1 колона/ред) или масив от номера на колони/редове, броени от 1. Максималният брой ключове е 3.

sortorder: скалар или масив от низове, съдържащи стойностите "ASC" (ascending, възходящ ред), "DESC" (descending, низходящ ред) или "" (подразбира се възходящ ред). Всеки елемент се сдвоява със съответния елемент в sortkeys. Ако масивът sortorder е по-къс от sortkeys, останалите ключове се сортират във възходящ ред.

destinationcell: клетката местоназначение за сортирания диапазон от клетки, като низ. Ако е подаден диапазон, се взема предвид само горната му лява клетка. По подразбиране се презаписва диапазонът източник.

containsheader: когато е True, първият ред/колона не се сортира.

casesensitive: само за сравняване на низове. Подразбира се False.

sortcolumns: когато е True, колоните се сортират от ляво надясно. Подразбира се False: редовете се сортират от горе надолу.

### Пример:

##### В Basic

        'Сортираме диапазона по колоните A (възходящ ред) и C (низходящ ред).
        oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)

##### В Python

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

В ScriptForge всички подпрограми или идентификатори на Basic с префикс „_“ са запазени за вътрешна употреба. Те не са предназначени за използване в макроси на Basic.

Теми, свързани с показаната

Услуга SFDocuments.Chart

SFDocuments.Document service

ScriptForge.UI service