SFDocuments.Calc service

The SFDocuments shared library provides a number of methods and properties to facilitate the management and handling of LibreOffice documents.

The SFDocuments.Calc service is a subclass of the SFDocuments.Document service. All methods and properties defined for the Document service can also be accessed using a Calc service instance.

The Calc service is focused on:

• Handling sheets within a Calc document (copy, insert, move, etc)

• Exchanging data between Basic data structures and Calc ranges

• Copying and importing massive amounts of data

This help page describes methods and properties that are applicable only to Calc documents.

A szolgáltatás igénybevétele

Before using the Calc service the ScriptForge library needs to be loaded or imported:

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService

The Calc service is closely related to the UI service of the ScriptForge library. Below are a few examples of how the Calc service can be invoked.

The code snippet below creates a Calc service instance that corresponds to the currently active Calc document.

    Set oDoc = CreateScriptService("Calc")
  

A Calc szolgáltatás egy példányának létrehozásának másik módja a UI szolgáltatás használata. A következő példában egy új Calc dokumentum jön létre, és az oDoc egy Calc szolgáltatáspéldány:

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

Or using the OpenDocument method from the UI service:

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

It is also possible to instantiate the Calc service specifying a window name for the CreateScriptService method:

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

In the example above, "MyFile.ods" is the name of an open document window. If this argument is not provided, the active window is considered.

It is also possible to invoke the Calc service using the document referenced by ThisComponent. This is specially useful when running a macro from within the Basic IDE.

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

It is recommended to free resources after use:

    Set oDoc = oDoc.Dispose()
  

However, if the document was closed using the CloseDocument method, it becomes unnecessary to free resources using the command described above.

    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)
  

The use of the prefix "SFDocuments." while calling the service is optional.

Meghatározások

Many methods require a "Sheet" or a "Range" as argument. Single cells are considered a special case of a Range.

Both may be expressed either as a string or as a reference (= object) depending on the situation:

• Within a specific Calc instance, sheets and ranges are given as strings such as "Sheet1" and "D2:F6".

• Additionally, the .Sheet and .Range properties return a reference that may be used as argument of a method called from another instance of the Calc service.

The example below copies data from document A (opened as read-only and hidden) to document B.

    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)
  

    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

Either the sheet name as a string or an object produced by the .Sheet property.

The shortcut "~" (tilde) represents the current sheet.

RangeName

Either a string designating a set of contiguous cells located in a sheet of the current instance or an object produced by the .Range property.

The shortcut "~" (tilde) represents the current selection or the first selected range if multiple ranges are selected.

The shortcut "*" represents all used cells.

The sheet name is optional when defining a range. If no sheet name is provided, then the active sheet is used. Surrounding single quotes and $ signs are allowed but ignored.

When specifying a SheetName as a string, the use of single quotes to enclose the sheet name are required if the name contains blank spaces " " or periods ".".

The examples below illustrate in which cases the use of single quotes is mandatory:

      ' The use of single quotes is optional
      oDoc.clearAll("SheetA.A1:B10")
      oDoc.clearAll("'SheetA'.A1:B10")
      ' The use of single quotes is required
      oDoc.clearAll("'Sheet.A'.A1:B10")
    

Except for the CurrentSelection property, the Calc service considers only single ranges of cells.

Tulajdonságok

All the properties generic to any document are implicitly applicable also to Calc documents. For more information, read the Document service Help page.

The properties specifically available for Calc documents are:

Visit LibreOffice API Documentation's website to learn more about XCellRange, XSheetCellCursor and XSpreadsheet UNO objects.

Metódusok

A1Style

Returns a range address as a string based on sheet coordinates, i.e. row and column numbers.

If only a pair of coordinates is given, then an address to a single cell is returned. Additional arguments can specify the bottom-right cell of a rectangular range.

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

row1, column1: Specify the row and column numbers of the top-left cell in the range to be considered. Row and column numbers start at 1.

row2, column2: Adja meg a figyelembe veendő tartomány jobb alsó cellájának sor- és oszlopszámát. Ha ezeket az argumentumokat nem adjuk meg, vagy ha a row1 és column1 értékeknél kisebb értékeket adunk meg, akkor a row1 és column1 által képviselt egyetlen cellatartomány címét kapjuk vissza.

sheetname: The name of the sheet to be appended to the returned range address. The sheet must exist. The default value is "~" corresponding to the currently active sheet.

The examples below in Basic and Python consider that "Sheet1" is the currently active sheet.

    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
  

    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
  

The method A1Style can be combined with any of the many properties and methods of the Calc service that require a range as argument, such as GetValue, GetFormula, ClearAll, etc.

Activate

If the argument sheetname is provided, the given sheet is activated and it becomes the currently selected sheet. If the argument is absent, then the document window is activated.

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

sheetname: A dokumentumban aktiválandó munkalap neve. Az alapértelmezett érték egy üres karakterlánc, ami azt jelenti, hogy a dokumentumablak az aktív munkalap megváltoztatása nélkül aktiválódik.

The example below activates the sheet named "Sheet4" in the currently active document.

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

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

Egy lap aktiválásának csak akkor van értelme, ha azt egy Calc dokumentumon végzi. Ahhoz, hogy megbizonyosodjunk arról, hogy Calc dokumentum van kéznél, használhatjuk a dokumentumobjektum isCalc tulajdonságát, amely True értéket ad vissza, ha Calc dokumentumról van szó, és False értéket egyébként.

Charts

Returns either the list with the names of all chart objects in a given sheet or a single Chart service instance.

• If only sheetname is specified, a zero-based array of strings containing the names of all charts is returned.

• If a chartname is provided, then a single object corresponding to the desired chart is returned. The specified chart must exist.

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

sheetname: The name of the sheet from which the list of charts is to be retrieved or where the specified chart is located.

chartname: A visszaadandó diagram objektum felhasználó által definiált neve. Ha a diagramnak nincs felhasználó által definiált neve, akkor a belső objektumnév használható. Ha ez az argumentum hiányzik, akkor a megadott lapon található diagramnevek listája kerül visszaadásra.

Use the Navigator sidebar to check the names assigned to charts under the OLE objects category.

The example below shows the number of chart objects in "Sheet1".

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

The following example accesses the chart named "MyChart" in "Sheet1" and prints its type.

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

    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

Clears all the contents and formats of the given range.

A filter formula can be specified to determine which cells shall be affected.

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

range: The range to be cleared, as a string.

filterformula: Egy Calc-képlet, amelyet az adott tartományra kell alkalmazni annak meghatározására, hogy mely cellák lesznek érintettek. A megadott képletnek True vagy False értéket kell visszaadnia. Ha ez az argumentum nincs megadva, akkor a tartomány összes cellája érintett.

filterscope: Determines how filterformula is expanded to the given range. This argument is mandatory if a filterformula is specified. The following values are accepted:

• "CELL": The formula specified in the filterformula argument is expanded once for each cell in range.

• "ROW": The formula specified in the filterformula argument is expanded once for each row in range.

• "COLUMN": The formula specified in the filterformula argument is expanded once for each column in range.

    ' Clears all cells in the range SheetX.A1:J10
    oDoc.ClearAll("SheetX.A1:J10")
    ' Clears all cells in the range SheetX.A1:J10 that have a value greater than 100
    oDoc.ClearAll("SheetX.A1:J10", "=SheetX.A1>100", "CELL")
    ' Clears all rows in the range SheetX.A1:J10 whose sum is greater than 500
    oDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:J1)>100", "ROW")
    ' Clears all columns in the range SheetX.A1:J10 whose sum is greater than 500
    oDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:A10)>100", "COLUMN")
  

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

ClearFormats

Clears the formats and styles in the given range.

A filter formula can be specified to determine which cells shall be affected.

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

range: The range whose formats and styles are to be cleared, as a string.

      oDoc.ClearFormats("SheetX.*")
  

    myDoc.ClearFormats("SheetX.*")
  

Refer to the ClearAll method documentation for examples on how to use the arguments filterformula and filterscope.

ClearValues

Clears the values and formulas in the given range.

A filter formula can be specified to determine which cells shall be affected.

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

range: The range whose values and formulas are to be cleared, as a string.

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

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

Refer to the ClearAll method documentation for examples on how to use the arguments filterformula and filterscope.

CompactLeft

Törli egy megadott tartomány azon oszlopait, amelyek megfelelnek egy Calc-képletként kifejezett szűrőnek. A szűrő minden egyes oszlopra vonatkozik annak eldöntésére, hogy törlésre kerül-e vagy sem.

The deleted column can be limited to the height of the specified range or span to the height of the entire sheet, thus deleting whole columns.

This method returns a string with the range address of the compacted range. If all columns are deleted, then an empty string is returned.

If a range of cells is selected, calling this method will not impact the selection.

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

range: The range from which columns will be deleted, as a string.

wholecolumn: Ha ez az opció True értékre van állítva, akkor a teljes oszlop törlődik a lapról. Az alapértelmezett érték False, ami azt jelenti, hogy a törölt oszlop a megadott range magasságára lesz korlátozva.

filterformula: Az egyes oszlopokra alkalmazandó szűrő, amely meghatározza, hogy az oszlop törlésre kerül-e vagy sem. A szűrő egy Calc képletként van kifejezve, amelyet az első oszlopra kell alkalmazni. Ha a képlet True értéket ad vissza egy oszlopra, akkor az adott oszlop törlésre kerül. Az alapértelmezett szűrő minden üres oszlopot töröl.

Például tegyük fel, hogy az A1:J200 tartomány van kiválasztva (magasság = 200), így az alapértelmezett képlet =(DARABÜRES(A1:A200)=200). Ez azt jelenti, hogy ha az első oszlopban (A oszlop) mind a 200 cella üres, akkor az oszlop törlődik. Vegye figyelembe, hogy a képlet csak az első oszlopra vonatkozóan van kifejezve. Belsőleg a CompactLeft módszer általánosítja ezt a képletet az összes többi oszlopra.

Calc functions used in the filterformula argument must be expressed using their English names. Visit the Wiki page List of Calc Functions for a complete list of Calc functions in English.

    ' Delete all empty columns in the range G1:L10 from Sheet1
    newrange = oDoc.CompactLeft("Sheet1.G1:L10")
    ' The example below is similar, but the entire column is deleted from the sheet
    newrange = oDoc.CompactLeft("Sheet1.G1:L10", WholeColumn := True)
    ' Deletes all columns where the first row is marked with an "X"
    newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
    ' Deletes all columns where the sum of values in the column is odd
    newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")
  

    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

Törli egy megadott tartomány azon sorait, amelyek megfelelnek egy Calc-képletként kifejezett szűrőnek. A szűrő minden egyes sorra vonatkozik annak eldöntésére, hogy törlésre kerül-e vagy sem.

The deleted rows can be limited to the width of the specified range or span to the width of the entire sheet, thus deleting whole rows.

This method returns a string with the range address of the compacted range. If all rows are deleted, then an empty string is returned.

If a range of cells is selected, calling this method will not impact the selection.

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

range: The range from which rows will be deleted, as a string.

wholerow: Ha ez az opció True értékre van állítva, akkor a teljes sor törlődik a lapról. Az alapértelmezett érték False, ami azt jelenti, hogy a törölt sor a megadott range szélességére lesz korlátozva.

filterformula: Az egyes sorokra alkalmazandó szűrő, amely meghatározza, hogy a sor törlésre kerül-e vagy sem. A szűrő egy Calc képletként van kifejezve, amelyet az első sorra kell alkalmazni. Ha a képlet True értéket ad vissza egy sorra, akkor az adott sor törlésre kerül. Az alapértelmezett szűrő minden üres sort töröl.

Például tegyük fel, hogy az A1:J200 tartomány van kiválasztva (szélesség = 10), így az alapértelmezett képlet =(DARABÜRES(A1:J1)=10). Ez azt jelenti, hogy ha az első sorban (1. sor) mind a 10 cella üres, akkor a sor törlésre kerül. Vegye figyelembe, hogy a képlet csak az első sorra vonatkozóan van kifejezve. Belsőleg a CompactUp módszer általánosítja ezt a képletet az összes többi sorra.

A filterformula argumentumban megadott képletben használt Calc függvényeket az angol nevükkel kell kifejezni. Az angol nyelvű Calc-függvények teljes listáját a List of Calc Functions Wiki oldalon találja.

    ' Delete all empty rows in the range G1:L10 from Sheet1
    newrange = oDoc.CompactUp("Sheet1.G1:L10")
    ' The example below is similar, but the entire row is deleted from the sheet
    newrange = oDoc.CompactUp("Sheet1.G1:L10", WholeRow := True)
    ' Deletes all rows where the first column is marked with an "X"
    newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
    ' Deletes all rows where the sum of values in the row is odd
    newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")
  

    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

Egy megadott munkalapot egy meglévő munkalap elé vagy a munkalapok listájának végére másol. A másolandó munkalap bármely nyitott Calc dokumentumban lehet. Siker esetén True értéket ad vissza.

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

sheetname: The name of the sheet to be copied as a string or its reference as an object.

newname: The name of the sheet to insert. The name must not be in use in the document.

beforesheet: Annak a munkalapnak a neve (karakterlánc) vagy indexe (szám, 1-től kezdődően), amely elé a másolt munkalap beszúrásra kerül. Ez az argumentum opcionális, és az alapértelmezett viselkedés szerint a másolt munkalapot az utolsó pozícióba szúrja be.

The following example makes a copy of the sheet "SheetX" and places it as the last sheet in the current document. The name of the copied sheet is "SheetY".

    Dim oDoc as Object
    'Gets the Document object of the active window
    Set oDoc = CreateScriptService("Calc")
    oDoc.CopySheet("SheetX", "SheetY")
  

The example below copies "SheetX" from "FileA.ods" and pastes it at the last position of "FileB.ods" with the name "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")
  

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

To copy sheets between open documents, use CopySheet. To copy sheets from documents that are closed, use CopySheetFromFile.

CopySheetFromFile

Egy megadott munkalapot másol egy zárt Calc dokumentumból, és beilleszti egy meglévő munkalap elé vagy a Document objektum által hivatkozott fájl munkalaplistájának végére.

Ha a fájl nem létezik, hibaüzenet jelenik meg. Ha a fájl nem érvényes Calc fájl, akkor egy üres lap kerül beillesztésre. Ha a forráslap nem létezik a bemeneti fájlban, az újonnan beillesztett lap tetejére hibaüzenet kerül.

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

filename: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation. The file must not be protected with a password.

sheetname: The name of the sheet to be copied as a string.

newname: The name of the copied sheet to be inserted in the document. The name must not be in use in the document.

beforesheet: Annak a munkalapnak a neve (karakterlánc) vagy indexe (szám, 1-től kezdődően), amely elé a másolt munkalap beszúrásra kerül. Ez az argumentum opcionális, és az alapértelmezett viselkedés szerint a másolt munkalapot az utolsó pozícióba szúrja be.

The following example copies "SheetX" from "myFile.ods" and pastes it into the document referred to by "oDoc" as "SheetY" at the first position.

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

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

CopyToCell

Copies a specified source range (values, formulas and formats) to a destination range or cell. The method reproduces the behaviour of a Copy/Paste operation from a range to a single cell.

It returns a string representing the modified range of cells. The size of the modified area is fully determined by the size of the source area.

The source range may belong to another open document.

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

sourcerange: The source range as a string when it belongs to the same document or as a reference when it belongs to another open Calc document.

destinationcell: The destination cell where the copied range of cells will be pasted, as a string. If a range is given, only its top-left cell is considered.

Next is an example where the source and destination are in the same file:

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

The example below illustrates how to copy a range from another open Calc document:

    Dim ui as Variant : ui = CreateScriptService("UI")
    Dim oDocSource As Object, oDocDestination As Object
    'Open the source document in the background (hidden)
    Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
    Set oDocDestination = CreateScriptService("Calc")
    oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
    'Do not forget to close the source document because it was opened as hidden
    oDocSource.CloseDocument()
  

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

A tartományból egy cellába történő másolás/beillesztés szimulálásához használja a CopyToCell parancsot. Egy tartományból egy nagyobb tartományba történő másolás/beillesztés szimulálásához (ugyanazokat a cellákat többször is megismételve) használja a CopyToRange parancsot.

CopyToRange

Egy megadott forrástartományt (értékek, képletek és formátumok) lefelé és/vagy jobbra másol egy céltartományba. A módszer a másolás/beillesztés művelet viselkedését utánozza egy forrás tartományból egy nagyobb céltartományba.

• Ha a célterület magassága (vagy szélessége) > 1 sor (vagy oszlop), akkor a forrás magasságának (vagy szélességének) <= a célterület magasságának (vagy szélességének) kell lennie. Ellenkező esetben nem történik semmi.

• If the height (or width) of the destination is = 1 then the destination is expanded downwards (or rightwards) up to the height (or width) of the source range.

The method returns a string representing the modified range of cells.

The source range may belong to another open document.

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

sourcerange: The source range as a string when it belongs to the same document or as a reference when it belongs to another open Calc document.

destinationrange: The destination of the copied range of cells, as a string.

Copy within the same document:

    oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
    ' Returns a range string: "$SheetY.$C$5:$J$14"
  

Copy from one file to another:

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

    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

Creates a new chart object showing the data in the specified range. The returned chart object can be further manipulated using the Chart service.

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

chartname: The user-defined name of the chart to be created. The name must be unique in the same sheet.

sheetname: The name of the sheet where the chart will be placed.

range: The range to be used as the data source for the chart. The range may refer to any sheet of the Calc document.

columnheader: When True, the topmost row of the range is used as labels for the category axis or the legend (Default = False).

rowheader: When True, the leftmost column of the range is used as labels for the category axis or the legend. (Default = False).

The examples below in Basic and Python create a chart using the data contained in the range "A1:B5" of "Sheet1" and place the chart in "Sheet2".

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

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

A ScriptForge Chart szolgáltatás súgóoldalán megtudhatja, hogyan lehet tovább manipulálni a diagramobjektumokat. Lehetőség van olyan tulajdonságok módosítására, mint a diagram típusa, a diagram és a tengelyek címei és a diagram pozíciója.

CreatePivotTable

Creates a new pivot table with the properties defined by the arguments passed to the method.

A name must be provided for the pivot table. If a pivot table with the same name already exists in the targeted sheet, it will be replaced without warning.

This method returns a string containing the range where the new pivot table was placed.

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: The user-defined name of the new pivot table.

sourcerange: The range containing the raw data, as a string. It is assumed that the first row contains the field names that are used by the pivot table.

targetcell: The top-left cell where the new pivot table will be placed. If a range is specified, only its top-left cell is considered.

datafields: Ez lehet egyetlen karakterlánc vagy egy tömb, amely a mezők nevét és az alkalmazandó függvényeket meghatározó karakterláncokat tartalmazza. Tömb megadásakor a Array("FieldName[;Function]", ...) szintaxist kell követnie.

A megengedett függvények a következők: Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP és Median. A függvényneveket angol nyelven kell megadni. Ha minden érték numerikus, akkor a Sum az alapértelmezett függvény, egyébként az alapértelmezett függvény a Count.

rowfields: A single string or an array with the field names that will be used as the pivot table rows.

columnfields: A single string or an array with the field names that will be used as the pivot table columns.

filterbutton: Determines whether a filter button will be displayed above the pivot table (Default = True).

rowtotals: Specifies if a separate column for row totals will be added to the pivot table (Default = True).

columntotals Specifies if a separate row for column totals will be added to the pivot table (Default = True)

    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"), _ ' Three data fields
        "Item", _ ' A single row field
        Array("State", "Team"), False) ' Two column fields
  

    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"],
                                  "Elem",
                                  ["State", "Team"], False)
  

To learn more about Pivot Tables in LibreOffice Calc, read the Pivot Table help page.

DAvg, DCount, DMax, DMin and DSum

Alkalmazza az Átlag, Darab, Max, Min és Szum függvényeket az adott tartományban lévő összes számértéket tartalmazó cellára, kivéve a szűrt és rejtett sorok és rejtett oszlopok értékeit, ugyanúgy, mint az állapotsorfüggvények esetében.

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: The range to which the function will be applied, as a string.

The example below applies the Sum function to the range "A1:A1000" of the currently selected sheet:

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

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

Cells in the given range that contain text will be ignored by all of these functions. For example, the DCount method will not count cells with text, only numerical cells.

ExportRangeToFile

Exports the specified range as an image or PDF file.

This method returns True if the destination file was successfully saved.

Hidden rows or columns in the specified range are not exported to the destination file.

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

range: A sheet name or a cell range to be exported, as a string.

filename: The name of the file to be saved. It must follow the SF_FileSystem.FileNaming notation.

imagetype: Identifies the destination file type. Possible values are "jpeg", "pdf" (default) and "png".

overwrite: When set to True, the destination file may be overwritten (Default = False).

    ' Exports the entire sheet as a PDF file
    oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
    ' Exports the range as a PNG file and overwrites the destination file if it exists
    oDoc.ExportRangeToFile("SheetX.A1:D10", "C:\Temp\image.png", "png", Overwrite := True)
  

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

Forms

Depending on the parameters provided this method will return:

• A zero-based Array (or a tuple in Python) with the names of all the forms contained in a given sheet (if the form argument is absent)

• A SFDocuments.Form service instance representing the form specified as argument.

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

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

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

sheetname: The name of the sheet, as a string, from which the form will be retrieved.

form A megadott munkalapon tárolt űrlap neve vagy indexszáma. Ha ez az argumentum hiányzik, a metódus egy listát ad vissza, amely a munkalapon elérhető összes űrlap nevét tartalmazza.

A következő példákban az első sor a "Munkalap1"-ben tárolt összes űrlap nevét kapja meg, a második sor pedig a "Munkalap1"-ben tárolt "Űrlap_A" nevű űrlap Form objektumát hívja le.

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

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

GetColumnName

Az 1 és 1024 közötti oszlopszámot átalakítja a megfelelő betűre ('A', 'B', ..., 'AMJ' oszlop). Ha a megadott oszlopszám kívül esik a megengedett tartományon, akkor egy nulla hosszúságú karakterláncot kap vissza.

svc.GetColumnName(columnnumber: int): str

columnnumber: The column number as an integer value in the interval 1 ... 1024.

Displays a message box with the name of the third column, which by default is "C".

    MsgBox oDoc.GetColumnName(3)
  

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

The maximum number of columns allowed on a Calc sheet is 1024.

GetFormula

Get the formula(s) stored in the given range of cells as a single string, a 1D or a 2D array of strings.

The names of Calc functions used in the returned formulas are expressed in English. Visit the Wiki page List of Calc Functions for a complete list of Calc functions in English.

svc.GetFormula(range: str): any

range: The range where to get the formulas from, as a string.

The following example returns a 3 by 2 array with the formulas in the range "A1:B3" (3 rows by 2 columns):

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

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

GetValue

Get the value(s) stored in the given range of cells as a single value, a 1D array or a 2D array. All values are either doubles or strings.

svc.GetValue(range: str): any

range: The range where to get the values from, as a string.

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

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

Ha egy cella dátumot tartalmaz, akkor az adott dátumnak megfelelő számot kapja vissza. A Basic parancsfájlokban a numerikus értékek dátumokká alakításához használja a Basic CDate beépített függvényét. Python parancsfájlokban használja a CDate függvényt a Basic szolgáltatásból.

ImportFromCSVFile

Imports the contents of a CSV-formatted text file and places it on a given destination cell.

A célterületet a CSV-fájl tartalmának beillesztése előtt minden tartalomtól és formátumtól megtisztítja. A módosított terület méretét teljes mértékben a bemeneti fájl tartalma határozza meg.

The method returns a string representing the modified range of cells.

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

filename: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation.

destinationcell: The destination cell to insert the imported data, as a string. If instead a range is given, only its top-left cell is considered.

filteroptions: The arguments for the CSV input filter. The default filter makes following assumptions:

• The input file encoding is UTF8.

• The field separator is a comma, a semi-colon or a Tab character.

• The string delimiter is the double quote (").

• All lines are included.

• Quoted strings are formatted as text.

• Special numbers are detected.

• All columns are presumed to be texts, except if recognized as valid numbers.

• The language is English/US, which implies that the decimal separator is "." and the thousands separator is ",".

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

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

To learn more about the CSV Filter Options, refer to the CSV Filter Options help page.

ImportFromDatabase

Imports the contents of a database table, query or resultset, i.e. the result of a SELECT SQL command, inserting it on a destination cell.

A célterületet az importált tartalom beillesztése előtt minden tartalomtól és formátumtól megtisztítja. A módosított terület méretét teljes mértékben a bemeneti tábla vagy lekérdezés tartalma határozza meg.

The method returns True when the import was successful.

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

filename: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation.

registrationname: The name to use to find the database in the databases register. This argument is ignored if a filename is provided.

destinationcell: The destination of the imported data, as a string. If a range is given, only its top-left cell is considered.

sqlcommand: Egy táblázat vagy lekérdezés neve (idézőjelek vagy szögletes zárójelek nélkül) vagy egy SELECT SQL utasítás, amelyben a táblázat- és mezőneveket szögletes zárójelekkel vagy idézőjelekkel lehet körülvenni az olvashatóság javítása érdekében.

directsql: Ha True, akkor az SQL parancsot előzetes elemzés nélkül küldi el az adatbázis-motornak. Az alapértelmezett érték False. Az argumentum táblázatok esetében figyelmen kívül hagyásra kerül. A lekérdezések esetében az alkalmazott opció a lekérdezés definiálásakor beállított opció.

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

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

InsertSheet

Inserts a new empty sheet before an existing sheet or at the end of the list of sheets.

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

sheetname: The name of the new sheet.

beforesheet: Annak a munkalapnak a neve (karakterlánc) vagy indexe (szám, 1-től kezdődően), amely elé az új munkalap beszúrásra kerül. Ez az argumentum opcionális, és az alapértelmezett viselkedés szerint a munkalapot az utolsó pozícióba szúrja be.

The following example inserts a new empty sheet named "SheetX" and places it before "SheetY":

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

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

MoveRange

Egy megadott forrástartományt áthelyez egy célcellatartományba. A metódus a módosított cellatartományt ábrázoló karakterláncot adja vissza. A módosított terület méretét teljes mértékben a forrásterület mérete határozza meg.

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

source: The source range of cells, as a string.

destination: The destination cell, as a string. If a range is given, its top-left cell is considered as the destination.

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

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

MoveSheet

Moves an existing sheet and places it before a specified sheet or at the end of the list of sheets.

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

sheetname: The name of the sheet to move. The sheet must exist or an exception is raised.

beforesheet: Annak a munkalapnak a neve (karakterlánc) vagy indexe (szám, 1-től kezdődően), amely elé az eredeti munkalap kerül. Ez az argumentum opcionális, és az alapértelmezett viselkedés szerint a munkalapot az utolsó pozícióba szúrja be.

The example below moves the existing sheet "SheetX" and places it before "SheetY":

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

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

Offset

Returns a new range (as a string) offset by a certain number of rows and columns from a given range.

This method has the same behavior as the homonymous Calc's Offset function.

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

reference: The range, as a string, that the method will use as reference to perform the offset operation.

rows: The number of rows by which the initial range is offset upwards (negative value) or downwards (positive value). Use 0 (default) to stay in the same row.

columns: Az oszlopok száma, amelyekkel a kezdeti tartomány balra (negatív érték) vagy jobbra (pozitív érték) eltolódik. Használja a 0-t (alapértelmezett), ha ugyanabban az oszlopban akar maradni.

height: The vertical height for an area that starts at the new range position. Omit this argument when no vertical resizing is needed.

width: The horizontal width for an area that starts at the new range position. Omit this argument when no horizontal resizing is needed.

Arguments rows and columns must not lead to zero or negative start row or column.

Arguments height and width must not lead to zero or negative count of rows or columns.

    oDoc.Offset("A1", 2, 2)
    'SheetX.$C$3 (A1 moved by two rows and two columns down)
    oDoc.Offset("A1", 2, 2, 5, 6)
    'SheetX.$C$3:$H$7 (A1 offset by two rows and columns with width of 5 rows and 6 columns)
  

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

OpenRangeSelector

Opens a non-modal dialog that can be used to select a range in the document and returns a string containing the selected range.

Ez a módszer ugyanazt a párbeszédablakot nyitja meg, amelyet a LibreOffice használ a zsugorítás gomb megnyomásakor. Például az Eszközök - Célértékkeresés párbeszédablakban a Képletcella mező jobb oldalán található a zsugorítás gomb.

This method does not change the current selection.

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

title: The title of the dialog, as a string.

selection: An optional range that is initially selected when the dialog is displayed.

singlecell: When True (default) only single-cell selection is allowed. When False range selection is allowed.

closeafterselect: Ha True (alapértelmezett), a párbeszédablak a kiválasztás után azonnal bezáródik. Ha False, a felhasználó annyiszor módosíthatja a kiválasztást, ahányszor csak szükséges, majd manuálisan bezárhatja a párbeszédablakot.

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

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

Printf

Returns the input string after substituting its token characters by their values in a given range.

This method does not change the current selection.

Ezzel a metódussal gyorsan kivehetjük a tartománynév bizonyos részeit, például a munkalap nevét vagy az első cella oszlopát és sorát, és ezekből egy új tartománycímet állíthatunk össze.

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

inputstr: The string containing the tokens that will be replaced by the corresponding values in range.

range: A RangeName from which values will be extracted. If it contains a sheet name, the sheet must exist.

tokencharacter: Character used to identify tokens. By default "%" is the token character. The following tokens are accepted:

• %S - The sheet name containing the range, including single quotes when necessary.

• %R1 - The row number of the top left cell of the range.

• %C1 - The column letter of the top left cell of the range.

• %R2 - The row number of the bottom right cell of the range.

• %C2 - The column letter of the bottom right cell of the range.

The example below extracts each element of the RangeName defined in sRange and uses them to compose a message.

    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)
  

A Printf módszer kombinálható a SetFormula módszerrel, hogy több cellán keresztül képleteket hozzon létre. Vegyünk például egy olyan táblázatot, amelynek numerikus értékei az "A1:E10" tartományban vannak, és amelyből képleteket kell létrehozni az egyes sorok értékeinek összegzésére, és az eredményeket az "F1:F10" tartományba helyezni:

    Dim sFormula as String, sRange as String
    sRange = "A1:E10"
    ' Note the use of the "$" character
    sFormula = "=SUM($%C1%R1:$%C2%R1)"
    oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))
  

    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

This method sends the contents of the given sheet to the default printer or to the printer defined by the SetPrinter method of the Document service.

Returns True if the sheet was successfully printed.

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

sheetname: The sheet to print, default is the active sheet.

pages: The pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default is all pages.

copies: The number of copies. Default is 1.

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

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

RemoveDuplicates

Removes duplicate rows from a specified range. The comparison to determine if a given row is a duplicate is done based on a subset of columns in the range.

This method returns a string containing the resulting range.

A duplikált sorok eltávolítása a tartomány első sorától kezdve lefelé haladva történik, ami azt jelenti, hogy ha két vagy több sor duplikált, akkor csak az első sor marad meg.

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

range: The range from which duplicates will be removed, as a string.

oszlopok: Az oszlopszámokat tartalmazó tömb, amely jelzi, hogy mely oszlopokat kell figyelembe venni annak meghatározásához, hogy egy sor duplikátum-e vagy sem. Ha ezt az argumentumot üresen hagyjuk, akkor csak az első oszlopot használjuk. A tömb elemeinek az 1 és a tartomány szélessége közötti intervallumban kell lenniük.

header: Specifies whether the first row is a header row (Default = False).

casesensitive: Specifies whether string comparisons are case-sensitive (Default = False).

mód: Meghatározza, hogy mi legyen a duplikált sorokkal. Ha mode = "CLEAR", akkor a duplikált sorokat egyszerűen eltávolítja a lapról, üresen hagyva a cellákat. Ha mode = "COMPACT", akkor a duplikátumokat eltávolítja és az üres sorokat tömöríti (alapértelmezett = "COMPACT").

    ' Removes duplicate rows where values in column A are duplicate
    ' Note that all optional arguments use their default value
    oDoc.RemoveDuplicates("A1:B10")
    ' Removes duplicate rows considering that the first row contains headers
    ' Columns A and B are used to determine if a row is a duplicate
    ' Cells containing duplicate values are left blank
    oDoc.RemoveDuplicates("A1:D10", columns := Array(1, 2), header := True, mode := "CLEAR")
  

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

RemoveSheet

Removes an existing sheet from the document.

svc.RemoveSheet(sheetname: str): bool

sheetname: The name of the sheet to remove.

    oDoc.RemoveSheet("SheetY")
  

    myDoc.RemoveSheet("SheetY")
  

RenameSheet

Renames the given sheet and returns True if successful.

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

sheetname: The name of the sheet to rename.

newname: the new name of the sheet. It must not exist yet.

This example renames the active sheet to "SheetY":

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

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

SetArray

Az adott értéket egy megadott célcellából kiindulva tárolja. A frissített terület a célcellától vagy a megadott tartomány bal felső sarkától kezdve kitágul a bemeneti value argumentum méretének megfelelően. A vektorok mindig függőlegesen kerülnek kiterjesztésre.

The method returns a string representing the modified area as a range of cells.

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

targetcell: The cell or a range as a string from where to start to store the given value.

érték: Egy skalár, egy vektor vagy egy tömb (Pythonban egy- vagy kétdimenziós listák és tuple-ok) a célcellából vagy a tartomány bal felső sarkából tárolandó új értékekkel, ha a targetcell egy tartomány. Az új értékeknek karakterláncoknak, numerikus értékeknek vagy dátumoknak kell lenniük. Más típusok esetén a megfelelő cellák kiürülnek.

The following example uses the builtin DimArray function to create an array and then store it in cell "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)
  

This example uses the RangeInit method of the ScriptForge Array service to create an array with values that are then stored from cell "A1" and downwards.

    'Fill 1st column with values from 1 to 1000
    oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))
  

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

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

Egy tömb teljes tartalmának egy lapra történő kiürítéséhez használja a SetArray parancsot. Egy tömb tartalmának csak a célzott cellatartomány határain belül történő kiürítéséhez használja a SetValue parancsot.

SetCellStyle

A megadott cellastílust alkalmazza a megadott céltartományra. A teljes tartomány frissül, a lap többi része pedig érintetlen marad. Ha a cellastílus nem létezik, hibaüzenet jelenik meg.

The method returns a string representing the modified area as a range of cells.

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

targetrange: The range to which the style will be applied, as a string.

style: The name of the cell style to apply.

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

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

Refer to the ClearAll method documentation for examples on how to use the arguments filterformula and filterscope.

SetFormula

Inserts the given (array of) formula(s) in the specified range. The size of the modified area is equal to the size of the range.

The method returns a string representing the modified area as a range of cells.

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

targetrange: The range to insert the formulas, as a string.

formula: A string, a vector or an array of strings with the new formulas for each cell in the target range.

The full range is updated and the remainder of the sheet is left unchanged.

If the given formula is a string, the unique formula is pasted along the whole range with adjustment of the relative references.

If the size of formula is smaller than the size of targetrange, then the remaining cells are emptied.

If the size of formula is larger than the size of targetrange, then the formulas are only partially copied until it fills the size of targetrange.

Vectors are always expanded vertically, except if targetrange has a height of exactly 1 row.

Calc functions used in the formula argument must be expressed using their English names. Visit the Wiki page List of Calc Functions for a complete list of Calc functions in English.

    oDoc.SetFormula("A1", "=A2")
    'Horizontal vector, partially empty
    oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
    'D2 contains the formula "=H2"
    oDoc.SetFormula("A1:D2", "=E1")
  

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

SetValue

Stores the given value in the specified range. The size of the modified area is equal to the size of the target range.

The method returns a string representing the modified area as a range of cells.

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

targetrange: The range where to store the given value, as a string.

value: A tartomány minden egyes cellájának új értékeit tartalmazó skalár, vektor vagy tömb. Az új értékeknek karakterláncoknak, számoknak vagy dátumoknak kell lenniük. Más típusok esetén a megfelelő cellák kiürülnek.

A teljes tartomány frissül, a lap többi része pedig változatlan marad. Ha a value mérete kisebb, mint a targetrange mérete, akkor a fennmaradó cellák kiürülnek.

If the size of value is larger than the size of targetrange, then value is only partially copied until it fills the size of targetrange.

Vectors are expanded vertically, except if targetrange has a height of exactly 1 row.

    oDoc.SetValue("A1", 2)
    'Below the Value array is smaller than the TargetRange (remaining cells are emptied)
    oDoc.SetValue("A1:F1", Array(1, 2, 3))
    'Below the Value and TargetRange have the same size
    oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))
  

If you want to fill a single row with values, you can use the Offset function. In the example below, consider that arrData is a one-dimensional array:

    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)
  

    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

Moves a given range of cells downwards by inserting empty rows. The current selection is not affected.

Depending on the value of the wholerow argument the inserted rows can either span the width of the specified range or span all columns in the row.

This method returns a string representing the new location of the initial range.

If the shifted range exceeds the sheet edges, then nothing happens.

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

range: The range above which rows will be inserted, as a string.

wholerow: Ha False (alapértelmezett), akkor a beillesztett sorok szélessége megegyezik a megadott range szélességével. Ellenkező esetben a beillesztett sor a lap összes oszlopát átfogja.

rows: The number of rows to be inserted. The default value is the height of the original range. The number of rows must be a positive number.

    ' Moves the range "A3:D3" down by one row; affects only columns A to D
    oDoc.ShiftDown("A3:D3")
    ' The inserted row spans all columns in the sheet
    oDoc.ShiftDown("A3:D3", WholeRow := True)
    ' Moves the range "A3:D3" down by five rows
    oDoc.ShiftDown("A3:D3", Rows := 5)
    ' Moves the range "A3:D10" down by two rows and shows the new location of the original range
    Dim sNewRange as String
    sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)
    MsgBox sNewRange   ' $Sheet1.$A$5:$D$12
  

    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

Deletes the leftmost columns of a given range and moves to the left all cells to the right of the affected range. The current selection is not affected.

Depending on the value of the wholecolumn argument the deleted columns can either span the height of the specified range or span all rows in the column.

Ez a módszer egy karakterláncot ad vissza, amely a kezdeti tartomány fennmaradó részének helyét jelöli. Ha az eredeti tartomány összes cellája törlődött, akkor egy üres karakterláncot kapunk vissza.

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

range: The range from which cells will be deleted, as a string.

wholecolumn: Ha False (alapértelmezett), akkor a törölt oszlopok magassága megegyezik a megadott range magasságával. Ellenkező esetben a törölt oszlop a lap összes sorát átfogja.

columns: The number of columns to be deleted from the specified range. The default value is the width of the original range, which is also the maximum value of this argument.

    ' Deletes the range "B3:B6"; moves left all cells to the right
    oDoc.ShiftLeft("B3:B6")
    ' Deletes the first column in the range "A3:D6"
    oDoc.ShiftLeft("A3:D6", Columns := 1)
    ' The deleted columns (A to D) spans all rows in the sheet
    oDoc.ShiftLeft("A3:D6", WholeColumn := True)
  

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

ShiftUp

Deletes the topmost rows of a given range and moves upwards all cells below the affected range. The current selection is not affected.

Depending on the value of the wholerow argument the deleted rows can either span the width of the specified range or span all columns in the row.

Ez a módszer egy karakterláncot ad vissza, amely a kezdeti tartomány fennmaradó részének helyét jelöli. Ha az eredeti tartomány összes cellája törlődött, akkor egy üres karakterláncot kapunk vissza.

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

range: The range from which cells will be deleted, as a string.

wholerow: Ha False (alapértelmezett), akkor a törölt sorok szélessége megegyezik a megadott range szélességével. Ellenkező esetben a törölt sor a lap összes oszlopát átfogja.

rows: The number of rows to be deleted from the specified range. The default value is the height of the original range, which is also the maximum value of this argument.

    ' Deletes the range "A3:D3"; moves all cells below it by one row up
    oDoc.ShiftUp("A3:D3")
    ' Deletes the first row in the range "A3:D6"
    oDoc.ShiftUp("A3:D6", Rows := 1)
    ' The deleted rows spans all columns in the sheet
    oDoc.ShiftUp("A3:D6", WholeRow := True)
  

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

ShiftRight

Moves a given range of cells to the right by inserting empty columns. The current selection is not affected.

Depending on the value of the wholecolumn argument the inserted columns can either span the height of the specified range or span all rows in the column.

This method returns a string representing the new location of the initial range.

If the shifted range exceeds the sheet edges, then nothing happens.

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

range: The range which will have empty columns inserted to its left, as a string.

wholecolumn: Ha False (alapértelmezett), akkor a beillesztett oszlopok magassága megegyezik a megadott range magasságával. Ellenkező esetben a beillesztett oszlop a lap összes sorát átfogja.

columns: The number of columns to be inserted. The default value is the width of the original range.

    ' Moves the range "A3:A6" right by one column; affects only rows 3 to 6
    oDoc.ShiftRight("A3:A6")
    ' Moves the range "A3:A6" right by five columns
    oDoc.ShiftRight("A3:A6", Columns := 5)
    ' The inserted column spans all rows in the sheet
    oDoc.ShiftRight("A3:A6", WholeColumn := True)
  

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

SortRange

A megadott tartomány rendezése tetszőleges számú oszlop/sor alapján. A rendezési sorrend oszloponként/soronként változhat. Ha a rendezési kulcsok száma > 3, akkor a tartományt többször, 3 kulcsból álló csoportok szerint rendezi, az utolsó kulccsal kezdve. A módosított cellatartományt ábrázoló karakterláncot ad vissza. A módosított terület méretét teljes mértékben a forrásterület mérete határozza meg.

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

range: The range to be sorted, as a string.

sortkeys: A scalar (if 1 column/row) or an array of column/row numbers starting from 1.

sortorder: Egy skalár, vagy karakterláncok tömbje, ami az "ASC" (növekvő) vagy "DESC" (csökkenő) értékeket tartalmazza. Minden elem a sortkeys megfelelő elemével van párosítva. Ha a sortorder tömb rövidebb, mint a sortkeys, akkor a fennmaradó kulcsok növekvő sorrendben kerülnek rendezésre.

destinationcell: The destination cell of the sorted range of cells, as a string. If a range is given, only its top-left cell is considered. By default the source Range is overwritten.

containsheader: When True, the first row/column is not sorted.

casesensitive: Only for string comparisons. Default = False

sortcolumns: When True, the columns are sorted from left to right. Default = False : rows are sorted from top to bottom.

    'Sort range based on columns A (ascending) and C (descending)
    oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)
  

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

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.