SFDocuments. Service Calc

La bibliothèque partagée SFDocuments fournit un certain nombre de méthodes et de propriétés pour faciliter la gestion et la manipulation des documents LibreOffice.

Le service SFDocuments.Calc est une sous-classe du service SFDocuments.Document. Toutes les méthodes et propriétés définies pour le service Document sont également accessibles à l'aide d'une instance de service Calc.

Le service Calc se concentre sur :

note

Cette page d'aide décrit les méthodes et propriétés applicables uniquement aux documents Calc.


Invocation du service

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

note

‚ÄĘ 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


Le service Calc est étroitement lié au service UI de la bibliothèque ScriptForge. Vous trouverez ci-dessous quelques exemples de la façon dont le service Calc peut être appelé.

En Basic :

L'extrait de code ci-dessous crée une instance de service Calc qui correspond au document Calc actuellement actif.


    Set oDoc = CreateScriptService("Calc")
  

Une autre façon de créer une instance du service Calc consiste à utiliser le service UI. Dans l'exemple suivant, un nouveau document Calc est créé et oDoc est une instance de service Calc :


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

Ou en utilisant la méthode OpenDocument du service UI :


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

Il est également possible d'instancier le service Calc à l'aide de la méthode CreateScriptService :


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

Dans l'exemple ci-dessus, "MyFile.ods" est le nom d'une fenêtre de document ouverte. Si cet argument n'est pas fourni, la fenêtre active est considérée.

Il est recommandé de libérer les ressources après utilisation :


    Set oDoc = oDoc.Dispose()
  

Cependant, si le document a été fermé à l'aide de la méthode CloseDocument, il devient inutile de libérer des ressources à l'aide de la commande décrite ci-dessus.

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

L'utilisation du préfixe "SFDocuments." lors de l'appel du service est facultative.


Définitions

De nombreuses méthodes nécessitent une "Sheet" ou une "Range" comme argument. Les cellules individuelles sont considérées comme un cas particulier d'une Range.

Les deux peuvent √™tre exprim√©s soit sous forme de cha√ģne, soit sous forme de r√©f√©rence (= objet) selon la situation¬†:

Exemple :

L'exemple ci-dessous copie les données du document A (ouvert en lecture seule et masqué) vers le document B.

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

Soit le nom de la feuille en tant que string ou un object produit par la propriété .Sheet.

Le raccourci "~" (tilde) représente la feuille active.

RangeName

Soit une cha√ģne d√©signant un ensemble de cellules contigu√ęs situ√©es dans une feuille de l'instance active ou un object produit par la propri√©t√© .Range.

Le raccourci "~" (tilde) représente la sélection actuelle ou la première plage sélectionnée si plusieurs plages sont sélectionnées.

Le raccourci "*" représente toutes les cellules utilisées.

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

À l'exception de la propriété CurrentSelection, le service Calc ne considère que des plages uniques de cellules.


Exemples de plages valides

1) $'SheetX'.D2
2) $D$2

Une cellule unique

1) $'SheetX'.D2:F6
2) D2:D10

Plage unique avec des cellules multiples

$'SheetX'.*

Toutes les cellules utilisées dans la feuille donnée

1) $'SheetX'.A:A (column A)
2) 3:5 (rows 3 to 5)

Toutes les cellules dans des colonnes ou des lignes contigu√ęs jusqu'√† la derni√®re cellule utilis√©e

myRange

Une plage nommée "myRange" au niveau du tableur

1) ~.someRange
2) SheetX.someRange

Un nom de plage au niveau de la feuille.

myDoc.Range("SheetX.D2:F6")

Une plage au sein de la feuille SheetX dans le fichier associé à l'instance myDoc Calc

~.~ ou ~

La sélection actuelle dans la feuille active


Propriétés

Toutes les propriétés génériques d'un document sont implicitement applicables également aux documents Calc. Pour plus d'informations, consultez la Page d'aide du service Document.

Les propriétés spécifiquement disponibles pour les documents Calc sont :

Nom

Lecture seule

Argument

Type de retour

Description

CurrentSelection

Non

Auncune

Cha√ģne ou matrice de cha√ģnes

La plage s√©lectionn√©e unique sous forme de cha√ģne ou la liste des plages s√©lectionn√©es sous forme de matrice.

FirstCell

Oui

SheetName or RangeName as String

String

Renvoie la première cellule utilisée dans une plage ou une feuille donnée.

FirstColumn

Oui

SheetName or RangeName as String

Long

Renvoie la première cellule utilisée dans une plage ou une feuille de données.

FirstRow

Oui

SheetName or RangeName as String

Long

Renvoie le numéro de ligne le plus haut dans une plage ou une feuille donnée.

Height

Oui

RangeName As String

Long

Le nombre de lignes (>= 1) dans la plage donnée.

LastCell

Oui

SheetName or RangeName as String

String

Renvoie la dernière cellule utilisée dans une plage ou une feuille donnée.

LastColumn

Oui

SheetName or RangeName as String

Long

La dernière colonne utilisée dans une plage ou une feuille donnée.

LastRow

Oui

SheetName or RangeName as String

Long

La dernière ligne utilisée dans une plage ou une feuille donnée.

Range

Oui

RangeName As String

Object

Une référence de plage qui peut être utilisée comme argument de méthodes telles que CopyToRange.

Region

Oui

RangeName As String

String

Renvoie l'adresse de la plus petite zone qui contient la plage spécifiée afin que la zone soit entourée de cellules vides ou des bords de la feuille. Cela équivaut à appliquer le raccourci à la plage donnée.

Sheet

Oui

SheetName As String

Object

Une référence de feuille qui peut être utilisée comme argument de méthodes telles que CopySheet.

SheetName

Yes

RangeName As String

String

Returns the sheet name of a given range address.

Sheets

Oui

Auncune

Matrice de cha√ģnes

La liste contenant les noms de toutes les feuilles existantes.

Width

Oui

RangeName As String

Long

Le nombre de colonnes (>= 1) dans la plage donnée.

XCellRange

Oui

RangeName As String

Object

Un objet UNO com.sun.star.Table.XCellRange.

XSheetCellCursor

Oui

RangeName As String

Object

Un objet UNO com.sun.star.sheet.XSheetCellCursor. Apr√®s avoir d√©plac√© le curseur, l'adresse de plage r√©sultante est accessible via la propri√©t√© UNO AbsoluteName de l'objet curseur, qui renvoie une valeur de cha√ģne pouvant √™tre utilis√©e comme argument pour les propri√©t√©s et les m√©thodes du service Calc.

XSpreadsheet

Oui

SheetName As String

Object

Un objet UNO com.sun.star.sheet.XSpreadsheet


tip

Visitez le site Web de la documentation de l'API LibreOffice pour en savoir plus sur les objets UNO XCellRange, XSheetCellCursor et XSpreadsheet.


Méthodes

Liste des méthodes dans le service 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
SetValue
SetCellStyle
SetFormula
ShiftDown
ShiftLeft
ShiftRight
ShiftUp
SortRange


A1Style

Renvoie une adresse de plage sous forme de cha√ģne bas√©e sur les coordonn√©es de la feuille, c'est-√†-dire les num√©ros de ligne et de colonne.

Si seule une paire de coordonnées est fournie, une adresse à une seule cellule est renvoyée. Des arguments supplémentaires peuvent spécifier la cellule en bas à droite d'une plage rectangulaire.

Syntaxe :

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

Paramètres :

row1, column1 : spécifier les numéros de ligne et de colonne de la cellule en haut à gauche de la plage à considérer. Les numéros de ligne et de colonne commencent à 1.

row2, column2 : spécifier les numéros de ligne et de colonne de la cellule en bas à droite dans la plage à considérer. Si ces arguments ne sont pas fournis, ou si des valeurs inférieures à row1 et column1 sont données, alors l'adresse de la plage de cellules unique représentée par row1 et column1 est renvoyé.

sheetname : le nom de la feuille à ajouter à l'adresse de plage renvoyée. La feuille doit exister. La valeur par défaut est "~" correspondant à la feuille actuellement active.

Exemple :

Les exemples ci-dessous en Basic et Python considèrent que "Sheet1" est la feuille actuellement active.

En 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
  
En 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
  
tip

La méthode A1Style peut être combinée avec l'une des nombreuses propriétés et méthodes du service Calc qui nécessitent une plage comme argument, telles que GetValue, GetFormula, ClearAll, etc.


Activate

Si l'argument sheetname est fourni, la feuille donnée est activée et elle devient la feuille actuellement sélectionnée. Si l'argument est absent, alors la fenêtre du document est activée.

Syntaxe :

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

Paramètres :

sheetname : Le nom de la feuille √† activer dans le document. La valeur par d√©faut est une cha√ģne vide, ce qui signifie que la fen√™tre du document sera activ√©e sans changer la feuille active.

Exemple :

L'exemple ci-dessous active la feuille nommée "Sheet4" dans le document actuellement actif.

En Basic :

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

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

L'activation d'une feuille n'a de sens que si elle est effectuée sur un document Calc. Pour vous assurer d'avoir un document Calc à portée de main, vous pouvez utiliser la propriété isCalc de l'objet document, qui renvoie True s'il s'agit d'un document Calc et False sinon.


Charts

Renvoie soit la liste avec les noms de tous les objets de diagramme dans une feuille donnée, soit une seule instance de service Chart.

Syntaxe :

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

Paramètres :

sheetname¬†: le nom de la feuille √† partir de laquelle la liste des diagrammes doit √™tre r√©cup√©r√©e ou o√Ļ se trouve le diagramme sp√©cifi√©.

chartname : le nom défini par l'utilisateur de l'objet diagramme à renvoyer. Si le diagramme n'a pas de nom défini par l'utilisateur, le nom d'objet interne peut être utilisé. Si cet argument est absent, la liste des noms de diagrammes dans la feuille spécifiée est renvoyée.

tip

Utilisez la barre latérale du Navigateur pour vérifier les noms attribués aux diagrammes dans la catégorie Objets OLE.


Exemple :

En Basic :

L'exemple ci-dessous montre le nombre d'objets de diagramme dans "Sheet1".


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

L'exemple suivant acc√®de au diagramme nomm√© ¬ę MyChart ¬Ľ dans ¬ę Sheet1 ¬Ľ et imprime son type.


    Dim oChart as Object
    oChart = oDoc.Charts("Sheet1", "MyChart")
    MsgBox oChart.ChartType
  
En 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

Efface tous les contenus et formats de la plage donnée.

Syntaxe :

svc.ClearAll(range: str)

Paramètres :

range¬†: la plage √† effacer, sous forme de cha√ģne.

Exemple :

En Basic :

      oDoc.ClearAll("SheetX.A1:F10")
  
En Python

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

ClearFormats

Efface les formats et les styles dans la plage donnée.

Syntaxe :

svc.ClearFormats(range: str)

Paramètres :

range¬†: la plage dont les formats et les styles doivent √™tre effac√©s, sous forme de cha√ģne.

Exemple :

En Basic :

      oDoc.ClearFormats("SheetX.*")
  
En Python

    myDoc.ClearFormats("SheetX.*")
  

ClearValues

Efface les valeurs et les formules dans la plage donnée.

Syntaxe :

svc.ClearValues(range: str)

Paramètres :

plage¬†: la plage dont les valeurs et les formules doivent √™tre effac√©es, sous forme de cha√ģne.

Exemple :

En Basic :

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

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

CompactLeft

Deletes the columns of a specified range that match a filter expressed as a Calc formula. The filter is applied to each column to decide whether it will be deleted or not.

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.

note

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


Syntaxe :

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

Paramètres :

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

wholecolumn: If this option is set to True the entire column will be deleted from the sheet. The default value is False, which means that the deleted column will be limited to the height of the specified range.

filterformula: The filter to be applied to each column to determine whether or not it will be deleted. The filter is expressed as a Calc formula that should be applied to the first column. When the formula returns True for a column, that column will be deleted. The default filter deletes all empty columns.

For example, suppose range A1:J200 is selected (height = 200), so the default formula is =(COUNTBLANK(A1:A200)=200). This means that if all 200 cells are empty in the first column (Column A), then the column is deleted. Note that the formula is expressed with respect to the first column only. Internally the CompactLeft method will generalize this formula for all the remaining columns.

Exemple :

En Basic :

    ' 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)")
  
En Python

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

CompactUp

Deletes the rows of a specified range that match a filter expressed as a Calc formula. The filter is applied to each row to decide whether it will be deleted or not.

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.

note

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


Syntaxe :

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

Paramètres :

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

wholerow: If this option is set to True the entire row will be deleted from the sheet. The default value is False, which means that the deleted row will be limited to the width of the specified range.

filterformula: The filter to be applied to each row to determine whether or not it will be deleted. The filter is expressed as a Calc formula that should be applied to the first row. When the formula returns True for a row, that row will be deleted. The default filter deletes all empty rows.

For example, suppose range A1:J200 is selected (width = 10), so the default formula is =(COUNTBLANK(A1:J1)=10). This means that if all 10 cells are empty in the first row (Row 1), then the row is deleted. Note that the formula is expressed with respect to the first row only. Internally the CompactUp method will generalize this formula for all the remaining rows.

Exemple :

En Basic :

    ' 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)")
  
En Python

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

CopySheet

Copie une feuille spécifiée avant une feuille existante ou à la fin de la liste des feuilles. La feuille à copier peut être contenue dans n'importe quel document Calc ouvert. Renvoie True en cas de succès.

Syntaxe :

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

Paramètres :

sheetname : Le nom de la feuille √† copier sous forme de cha√ģne ou sa r√©f√©rence en tant qu'objet.

newname : le nom de la feuille à insérer. Le nom ne doit pas être utilisé dans le document.

beforesheet¬†: le nom (cha√ģne) ou l'index (num√©rique, √† partir de 1) de la feuille avant laquelle ins√©rer la feuille copi√©e. Cet argument est facultatif et le comportement par d√©faut consiste √† ajouter la feuille copi√©e √† la derni√®re position.

Exemple :

En Basic :

L'exemple suivant fait une copie de la feuille ¬ę¬†SheetX¬†¬Ľ et la place comme derni√®re feuille dans le document actuel. Le nom de la feuille copi√©e est "SheetY".


    Dim oDoc as Object
    'Obtient l'objet Document de la fenêtre active
    Set oDoc = CreateScriptService("Calc")
    oDoc.CopySheet("SheetX", "SheetY")
  

L'exemple ci-dessous copie "SheetS" de "File.ods" et la colle à la dernière position de "FileB.ods" avec le nom "ShettY":


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

Pour copier des feuilles entre des documents ouverts, utilisez CopySheet. Pour copier des feuilles de documents fermés, utilisez CopySheetFromFile.


CopySheetFromFile

Copie une feuille spécifiée d'un document Calc fermé et la colle avant une feuille existante ou à la fin de la liste des feuilles du fichier référencé par un objet Document.

Si le fichier n'existe pas, une erreur est générée. Si le fichier n'est pas un fichier Calc valide, une feuille vierge est insérée. Si la feuille source n'existe pas dans le fichier d'entrée, un message d'erreur est inséré en haut de la feuille nouvellement collée.

Syntaxe :

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

Paramètres :

filename : identifie le fichier à ouvrir. Il doit suivre la notation SF_FileSystem.FileNaming. Le fichier ne doit pas être protégé par un mot de passe.

sheetname¬†: le nom de la feuille √† copier sous forme de cha√ģne.

newname : le nom de la feuille copiée à insérer dans le document. Le nom ne doit pas être utilisé dans le document.

beforesheet¬†: Le nom (cha√ģne) ou l'index (num√©rique, √† partir de 1) de la feuille avant laquelle ins√©rer la feuille copi√©e. Cet argument est facultatif et le comportement par d√©faut consiste √† ajouter la feuille copi√©e √† la derni√®re position.

Exemple :

L'exemple suivant copie "SheetX" à partir de "myFile.ods" et la colle dans le document désigné par "oDoc" en tant que "SheetY" à la première position.

En Basic :

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

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

CopyToCell

Copie une plage source spécifiée (valeurs, formules et formats) dans une plage ou une cellule de destination. La méthode reproduit le comportement d'une opération Copier/Coller d'une plage à une seule cellule.

Cela renvoie une cha√ģne repr√©sentant la plage de cellules modifi√©e. La taille de la zone modifi√©e est enti√®rement d√©termin√©e par la taille de la zone source.

La plage source peut appartenir à un autre document ouvert.

Syntaxe :

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

Paramètres :

sourcerange¬†: la plage source sous forme de cha√ģne lorsqu'elle appartient au m√™me document ou en tant que r√©f√©rence lorsqu'elle appartient √† un autre document Calc ouvert.

destinationcell¬†: la cellule de destination dans laquelle la plage de cellules copi√©e sera coll√©e, sous forme de cha√ģne. Si une plage est donn√©e, seule sa cellule en haut √† gauche est prise en compte.

Exemple :

En Basic :

Voici un exemple o√Ļ la source et la destination se trouvent dans le m√™me fichier¬†:


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

L'exemple ci-dessous illustre comment copier une plage à partir d'un autre document Calc ouvert :


    Dim ui as Variant : ui = CreateScriptService("UI")
    Dim oDocSource As Object, oDocDestination As Object
    'Ouvrir le document source en arrière-plan (masqué)
    Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
    Set oDocDestination = CreateScriptService("Calc")
    oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
    'N'oubliez pas de fermer le document source car il a été ouvert comme masqué
    oDocSource.CloseDocument()
  
En 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()
  
tip

Pour simuler un copier/coller d'une plage vers une seule cellule, utilisez CopyToCell. Pour simuler un copier/coller d'une plage vers une plage plus grande (avec les mêmes cellules répliquées plusieurs fois), utilisez CopyToRange.


CopyToRange

Copie vers le bas et/ou vers la droite une plage source spécifiée (valeurs, formules et formats) vers une plage de destination. La méthode imite le comportement d'une opération Copier/Coller d'une plage source vers une plage de destination plus large.

La m√©thode renvoie une cha√ģne repr√©sentant la plage de cellules modifi√©e.

La plage source peut appartenir à un autre document ouvert.

Syntaxe :

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

Paramètres :

sourcerange¬†: la plage source sous forme de cha√ģne lorsqu'elle appartient au m√™me document ou en tant que r√©f√©rence lorsqu'elle appartient √† un autre document Calc ouvert.

destinationrange¬†: la destination de la plage de cellules copi√©e, sous forme de cha√ģne.

Exemple :

En Basic :

Copier dans le même document :


    oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
    ' Renvoie une cha√ģne de plage¬†: "$SheetY.$C$5:$J$14"
  

Copier d'un fichier vers un autre :


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

Crée un nouvel objet diagramme affichant les données dans la plage spécifiée. L'objet diagramme renvoyé peut être manipulé davantage à l'aide du service Chart.

Syntaxe :

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

Paramètres :

chartname : le nom défini par l'utilisateur du diagramme à créer. Le nom doit être unique dans la même feuille.

sheetname: le nom de la feuille o√Ļ le diagramme sera plac√©.

range : La plage à utiliser comme source de données pour le diagramme. La plage peut se référer à n'importe quelle feuille du document Calc.

columnheader : lorsque True, la ligne la plus haute de la plage est utilisée comme étiquettes pour l'axe des catégories ou la légende (par défaut = False).

rowheader : lorsque True, la colonne la plus à gauche de la plage est utilisée comme étiquettes pour l'axe des catégories ou la légende. (par défaut = False).

Exemple :

Les exemples ci-dessous en Basic et Python créent un diagramme à l'aide des données contenues dans la plage "A1:B5" de "Sheet1" et placent le diagramme dans "Sheet2".

En Basic :

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

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

Reportez-vous à la page d'aide sur le Chart service de ScriptForge pour en savoir plus sur la façon de manipuler davantage les objets diagrammes. Il est possible de modifier les propriétés telles que le type de diagramme, les titres du diagramme et des axes et la position du diagramme.


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.

Syntaxe :

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

Paramètres :

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: It can be either a single string or an array containing strings that define field names and functions to be applied. When an array is specified, it must follow the syntax Array("FieldName[;Function]", ...).

The allowed functions are: Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP and Median. Function names must be provided in English. When all values are numerical, Sum is the default function, otherwise the default function is 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)

Exemple :

En Basic :

    Dim vData As Variant, oDoc As Object, ui As Object, sTable As String, sPivot As String
    Set ui = CreateScriptService("UI")
    Set oDoc = ui.CreateDocument("Calc")
    vData = Array(Array("Item", "State", "Team", "2002", "2003", "2004"), _
        Array("Books", "Michigan", "Jean", 14788, 30222, 23490), _
        Array("Candy", "Michigan", "Jean", 26388, 15641, 32849), _
        Array("Pens", "Michigan", "Jean", 16569, 32675, 25396), _
        Array("Books", "Michigan", "Volker", 21961, 21242, 29009), _
        Array("Candy", "Michigan", "Volker", 26142, 22407, 32841))
    sTable = oDoc.SetArray("A1", vData)
    sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _
        Array("2002", "2003;count", "2004;average"), _ ' Three data fields
        "Item", _ ' A single row field
        Array("State", "Team"), False) ' Two column fields
  
En Python

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

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


DAvg, DCount, DMax, DMin and DSum

Appliquez respectivement les fonctions Moyenne, NB, Max, Min et Somme à toutes les cellules contenant des valeurs numériques sur une plage donnée.

Syntaxe :

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

Paramètres :

range¬†:¬†la plage √† laquelle la fonction sera appliqu√©e, sous forme de cha√ģne.

Exemple :

L'exemple ci-dessous applique la fonction Sum à la plage "A1:A1000" de la feuille actuellement sélectionnée :

En Basic :

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

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

Les cellules de la plage donnée qui contiennent du texte seront ignorées par toutes ces fonctions. Par exemple, la méthode DCount ne comptera pas les cellules contenant du texte, mais uniquement les cellules numériques.


ExportRangeToFile

Exports the specified range as an image or PDF file.

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

note

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


Syntaxe :

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

Paramètres :

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

Exemple :

En Basic :

    ' 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)
  
En Python

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

Forms

En fonction des paramètres fournis, cette méthode renverra :

Syntaxe :

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

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

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

Paramètres :

sheetname¬†: le nom de la feuille, sous forme de cha√ģne, √† partir de laquelle le formulaire sera r√©cup√©r√©.

form : le nom ou l'index correspondant à un formulaire stocké dans la feuille spécifiée. Si cet argument est absent, la méthode renverra une liste avec les noms de tous les formulaires disponibles dans la feuille.

Exemple :

Dans les exemples suivants, la première ligne récupère les noms de tous les formulaires stockés dans "Sheet1" et la deuxième ligne récupère l'objet Form du formulaire nommé "Form_A" qui est stocké dans "Sheet1".

En Basic :

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

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

GetColumnName

Convertit un num√©ro de colonne compris entre 1 et 1024 en sa lettre correspondante (colonne 'A', 'B', ..., 'AMJ'). Si le num√©ro de colonne donn√© est en dehors de la plage autoris√©e, une cha√ģne de longueur nulle est renvoy√©e.

Syntaxe :

svc.GetColumnName(columnnumber: int): str

Paramètres :

columnnumber : le numéro de la colonne sous forme de valeur entière dans l'intervalle 1 ... 1024.

Exemple :

En Basic :

Affiche une bo√ģte de message avec le nom de la troisi√®me colonne, qui est par d√©faut "C".


    MsgBox oDoc.GetColumnName(3)
  
En Python

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

Le nombre maximum de colonnes autorisé sur une feuille Calc est de 1024.


GetFormula

Obtenir la ou les formules stock√©es dans la plage de cellules donn√©e sous la forme d'une cha√ģne unique, d'une matrice de cha√ģnes 1D ou 2D.

Syntaxe :

svc.GetFormula(range: str): any

Paramètres :

range¬†: la plage √† partir de laquelle obtenir les formules, sous forme de cha√ģne.

Exemple :

En Basic :

L'exemple suivant renvoie une matrice de 3 par 2 avec les formules dans la plage "A1:B3" (3 lignes par 2 colonnes) :


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

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

GetValue

Obtenir la ou les valeurs stock√©es dans la plage de cellules donn√©e sous la forme d'une valeur unique, d'une matrice 1D ou d'une matrice 2D. Toutes les valeurs sont soit des doubles, soit des cha√ģnes.

Syntaxe :

svc.GetValue(range: str): any

Paramètres :

range¬†: la plage √† partir de laquelle obtenir les valeurs, sous forme de cha√ģne.

Exemple :

En Basic :

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

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

Si une cellule contient une date, le numéro correspondant à cette date sera renvoyé. Pour convertir des valeurs numériques en dates dans des scripts Basic, utilisez la fonction intégrée Basic CDate. Dans les scripts Python, utilisez la fonction CDate du service Basic.


ImportFromCSVFile

Importe le contenu d'un fichier texte au format CSV et le place dans une cellule de destination donnée.

La zone de destination est effacée de tous les contenus et formats avant d'insérer le contenu du fichier CSV. La taille de la zone modifiée est entièrement déterminée par le contenu du fichier d'entrée.

La m√©thode renvoie une cha√ģne repr√©sentant la plage de cellules modifi√©e.

Syntaxe :

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

Paramètres :

filename : identifie le fichier à ouvrir. Il doit suivre la notation SF_FileSystem.FileNaming.

destinationcell¬†: la cellule de destination dans laquelle ins√©rer les donn√©es import√©es, sous forme de cha√ģne. Si √† la place une plage est donn√©e, seule sa cellule en haut √† gauche est prise en compte.

filteroptions : les arguments du filtre d'entrée CSV. Le filtre par défaut fait les hypothèses suivantes :

Exemple :

En Basic :

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

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

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


ImportFromDatabase

Importe le contenu d'une table de base de données, d'une requête ou d'un jeu de résultats, c'est-à-dire le résultat d'une commande SELECT SQL, en l'insérant dans une cellule de destination.

La zone de destination est effacée de tous les contenus et formats avant d'insérer le contenu importé. La taille de la zone modifiée est entièrement déterminée par le contenu de la table ou de la requête.

La méthode renvoie True lorsque l'import a réussi.

Syntaxe :

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

Paramètres :

filename : identifie le fichier à ouvrir. Il doit suivre la notation SF_FileSystem.FileNaming.

registrationname : le nom à utiliser pour trouver la base de données dans le registre des bases de données. Cet argument est ignoré si un filename est fourni.

destinationcell¬†: la destination des donn√©es import√©es, sous forme de cha√ģne. Si une plage est donn√©e, seule sa cellule en haut √† gauche est prise en compte.

sqlcommand : un nom de table ou de requête (sans guillemets ni crochets environnants) ou une instruction SELECT SQL dans laquelle les noms de table et de champ peuvent être entourés de crochets ou de guillemets pour améliorer sa lisibilité.

directsql : lorsque True, la commande SQL est envoyée au moteur de base de données sans pré-analyse. La valeur par défaut est False. L'argument est ignoré pour les tables. Pour les requêtes, l'option appliquée est celle définie lors de la définition de la requête.

Exemple :

En Basic :

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

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

InsertSheet

Insère une nouvelle feuille vide avant une feuille existante ou à la fin de la liste des feuilles.

Syntaxe :

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

Paramètres :

sheetname : le nom de la nouvelle feuille.

beforesheet¬†: le nom (cha√ģne) ou l'index (num√©rique, √† partir de 1) de la feuille avant laquelle ins√©rer la nouvelle feuille. Cet argument est facultatif et le comportement par d√©faut consiste √† ins√©rer la feuille √† la derni√®re position.

Exemple :

L'exemple suivant ins√®re une nouvelle feuille vide nomm√©e ¬ę¬†SheetX¬†¬Ľ et la place avant ¬ę¬†SheetY¬†¬Ľ¬†:

En Basic :

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

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

MoveRange

D√©place une plage source sp√©cifi√©e vers une plage de cellules de destination. La m√©thode renvoie une cha√ģne repr√©sentant la plage de cellules modifi√©e. La dimension de la zone modifi√©e est enti√®rement d√©termin√©e par la taille de la zone source.

Syntaxe :

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

Paramètres :

source¬†: la plage source des cellules, sous forme de cha√ģne.

destination¬†: la cellule de destination, sous forme de cha√ģne. Si une plage est donn√©e, sa cellule en haut √† gauche est consid√©r√©e comme la destination.

Exemple :

En Basic :

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

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

MoveSheet

Déplace une feuille existante et la place avant une feuille spécifiée ou à la fin de la liste des feuilles.

Syntaxe :

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

Paramètres :

sheetname : le nom de la feuille à déplacer. La feuille doit exister ou une exception est levée.

beforesheet¬†: le nom (cha√ģne) ou l'index (num√©rique, √† partir de 1) de la feuille avant laquelle la feuille d'origine sera plac√©e. Cet argument est facultatif et le comportement par d√©faut consiste √† d√©placer la feuille √† la derni√®re position.

Exemple :

L'exemple ci-dessous déplace la feuille existante "SheetX" et la place avant "SheetY":

En Basic :

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

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

Offset

Renvoie une nouvelle plage (sous forme de cha√ģne) d√©cal√©e d'un certain nombre de lignes et de colonnes d'une plage donn√©e.

Cette méthode a le même comportement que la Fonction DECALER homonyme de Calc.

Syntaxe :

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

Paramètres :

reference¬†: la plage, sous forme de cha√ģne, que la m√©thode utilisera comme r√©f√©rence pour effectuer l'op√©ration de d√©calage.

rows : nombre de lignes dont la plage initiale est décalée vers le haut (valeur négative) ou vers le bas (valeur positive). Utilisez 0 (par défaut) pour rester sur la même ligne.

columns : nombre de colonnes dont la plage initiale est décalée vers la gauche (valeur négative) ou vers la droite (valeur positive). Utilisez 0 (par défaut) pour rester dans la même colonne.

height : la hauteur verticale pour une zone qui commence à la nouvelle position de plage. Omettez cet argument lorsque aucun redimensionnement vertical n'est nécessaire.

width : la largeur horizontale pour une zone qui commence à la nouvelle position de plage. Omettez cet argument lorsque aucun redimensionnement horizontal n'est nécessaire.

Les arguments rows et columns ne doivent pas conduire à une ligne ou une colonne de départ nulle ou négative.

Les arguments height et width ne doivent pas conduire à un nombre de lignes ou de colonnes nul ou négatif.

Exemple :

En Basic :

    oDoc.Offset("A1", 2, 2)
    'SheetX.$C$3 (A1 déplacé de deux lignes et de deux colonnes vers le bas)
    oDoc.Offset("A1", 2, 2, 5, 6)
    'SheetX.$C$3:$H$7 (A1 décalé de deux lignes et colonnes avec une largeur de 5 lignes et 6 colonnes)
  
En Python

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

OpenRangeSelector

Ouvre une bo√ģte de dialogue non modale qui peut √™tre utilis√©e pour s√©lectionner une plage dans le document et renvoie une cha√ģne contenant la plage s√©lectionn√©e.

note

Cette m√©thode ouvre la m√™me bo√ģte de dialogue que celle utilis√©e par LibreOffice lorsque le bouton R√©duire est enfonc√©. Par exemple, la bo√ģte de dialogue Outils - Recherche de valeur cible a un bouton R√©duire √† droite du champ Cellule de formule.


Cette méthode ne modifie pas la sélection active.

Syntaxe :

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

Paramètres :

title¬†: le titre de la bo√ģte de dialogue, sous forme de cha√ģne.

selection¬†: une plage facultative qui est initialement s√©lectionn√©e lorsque la bo√ģte de dialogue est affich√©e.

singlecell : lorsque True (par défaut), seule la sélection d'une seule cellule est autorisée. LorsqueFalse, la sélection de plage est autorisée.

closeafterselect¬†: lorsque True (par d√©faut), la bo√ģte de dialogue est ferm√©e imm√©diatement apr√®s la s√©lection. Lorsque False, l'utilisateur peut modifier la s√©lection autant de fois que n√©cessaire, puis fermer manuellement la bo√ģte de dialogue.

Exemple :

En Basic :

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

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

Printf

Renvoie la cha√ģne d'entr√©e apr√®s avoir remplac√© ses caract√®res symboliques par leurs valeurs dans une plage donn√©e.

Cette méthode ne modifie pas la sélection active.

tip

Cette méthode peut être utilisée pour extraire rapidement des parties spécifiques d'un nom de plage, telles que le nom de la feuille ou les premières colonne et ligne de cellule, et les utiliser pour composer une nouvelle adresse de plage.


Syntaxe :

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

Paramètres :

inputstr¬†: la cha√ģne contenant les jetons qui seront remplac√©s par les valeurs correspondantes dans range.

range : un RangeName à partir duquel les valeurs seront extraites. Si elle contient un nom de feuille, la feuille doit exister.

tokencharacter : caractère utilisé pour identifier les jetons. Par défaut, "%" est le caractère symbolique. Les jetons suivants sont acceptés :

Exemple :

En Basic :

L'exemple ci-dessous extrait chaque élément du RangeName défini dans sRange et les utilise pour composer un 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)
  

La méthode Printf peut être combinée avec SetFormula pour créer des formules sur plusieurs cellules. Par exemple, considérons une table avec des valeurs numériques dans la plage "A1:E10" à partir de laquelle des formules doivent être créées pour additionner les valeurs de chaque ligne et placer les résultats dans la plage "F1:F10":


    Dim sFormula as String, sRange as String
    sRange = "A1:E10"
    ' Notez l'utilisation du caractère "$"
    sFormula = "=SUM($%C1%R1:$%C2%R1)"
    oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))
  
En 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

Cette méthode envoie le contenu de la feuille donnée à l'imprimante par défaut ou à l'imprimante définie par la méthode SetPrinter du service Document.

Renvoie True si la feuille a été imprimée avec succès.

Syntaxe :

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

Paramètres :

sheetname : la feuille à imprimer, la valeur par défaut est la feuille active.

pages¬†: les pages √† imprimer sous forme de cha√ģne, comme dans l'interface utilisateur. Exemple¬†: "1-4;10;15-18". La valeur par d√©faut est toutes les pages.

copies : le nombre de copies. La valeur par défaut est 1.

Exemple :

En Basic :

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

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

RemoveSheet

Supprime une feuille existante du document.

Syntaxe :

svc.RemoveSheet(sheetname: str): bool

Paramètres :

sheetname : le nom de la feuille à supprimer.

Exemple :

En Basic :

    oDoc.RemoveSheet("SheetY")
  
En Python

    myDoc.RemoveSheet("SheetY")
  

RenameSheet

Renomme la feuille données et renvoie True en cas de succès.

Syntaxe :

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

Paramètres :

sheetname : le nom de la feuille à renommer.

newname : le nouveau nom de la feuille. Il ne doit pas encore exister.

Exemple :

Cet exemple renomme la feuille active en "SheetY" :

En Basic :

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

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

SetArray

Stocke la valeur donnée à partir d'une cellule cible spécifiée. La zone mise à jour s'étend à partir de la cellule cible ou du coin supérieur gauche de la plage donnée pour s'adapter à la taille de l'argument value d'entrée. Les vecteurs sont toujours étendus verticalement.

La m√©thode renvoie une cha√ģne repr√©sentant la zone modifi√©e sous forme de plage de cellules.

Syntaxe :

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

Paramètres :

targetcell¬†: la cellule ou une plage sous forme de cha√ģne √† partir de laquelle commencer √† stocker la valeur donn√©e.

value¬†: un scalaire, un vecteur ou une matrice (en Python, listes et tuples √† une ou deux dimensions) avec les nouvelles valeurs √† stocker √† partir de la cellule cible ou du coin sup√©rieur gauche de la plage si targetcell est une plage. Les nouvelles valeurs doivent √™tre des cha√ģnes, des valeurs num√©riques ou des dates. D'autres types entra√ģneront le vidage des cellules correspondantes.

Exemple :

En Basic :

L'exemple suivant utilise la Fonction DimArray intégrée pour créer un tableau, puis le stocker dans la cellule "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)
  

Cet exemple utilise la méthode RangeInit du service ScriptForge Array pour créer une matrice avec des valeurs qui sont ensuite stockées à partir de la cellule "A1" et vers le bas.


    'Remplir la 1ère colonne avec des valeurs de 1 à 1000
    oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))
  
En 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)))
  
tip

Pour vider tout le contenu d'une matrice dans une feuille, utilisez SetArray. Pour vider le contenu d'une matrice uniquement dans les limites de la plage de cellules ciblée, utilisez SetValue.


SetValue

Stocke la valeur donnée dans la plage spécifiée. La taille de la zone modifiée est égale à la taille de la plage cible.

La m√©thode renvoie une cha√ģne repr√©sentant la zone modifi√©e sous forme de plage de cellules.

Syntaxe :

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

Paramètres :

targetrange¬†: la plage o√Ļ stocker la valeur donn√©e, sous forme de cha√ģne.

value¬†: un scalaire, un vecteur ou une matrice avec les nouvelles valeurs pour chaque cellule de la plage. Les nouvelles valeurs doivent √™tre des cha√ģnes, des valeurs num√©riques ou des dates. D'autres types entra√ģneront le vidage des cellules correspondantes.

La plage complète est mise à jour et le reste de la feuille reste inchangé. Si la taille de value est inférieure à la taille de targetrange, alors les cellules restantes seront vidées.

Si la taille de value est supérieure à la taille de targetrange, alors la value n'est que partiellement copiée jusqu'à ce qu'elle remplisse la taille de targetrange .

Les vecteurs sont étendus verticalement, sauf si targetrange a une hauteur d'exactement 1 ligne.

Exemple :

En Basic :

    oDoc.SetValue("A1", 2)
    'Ci dessous la matrice Value est plus petite que le TargetRange (les cellules restantes sont vidées)
    oDoc.SetValue("A1:F1", Array(1, 2, 3))
    'Ci-dessous Value et TargetRange ont la même taille
    oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))
  

Si vous souhaitez remplir une seule ligne avec des valeurs, vous pouvez utiliser la fonction Offset. Dans l'exemple ci-dessous, considérons que arrData est une matrice à une dimension :


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

SetCellStyle

Applique le style de cellule spécifié à la plage cible donnée. La plage complète est mise à jour et le reste de la feuille est laissé intact. Si le style de cellule n'existe pas, une erreur est générée.

La m√©thode renvoie une cha√ģne repr√©sentant la zone modifi√©e sous forme de plage de cellules.

Syntaxe :

svc.SetCellStyle(targetrange: str, style: str): str

Paramètres :

targetrange¬†:¬†la plage √† laquelle le style sera appliqu√©, sous forme de cha√ģne.

style: le nom du style de cellule à appliquer.

Exemple :

En Basic :

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

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

SetFormula

Insère (la matrice de) formule(s) donnée(s) dans la plage spécifiée. La taille de la zone modifiée est égale à la taille de la plage.

La m√©thode renvoie une cha√ģne repr√©sentant la zone modifi√©e sous forme de plage de cellules.

Syntaxe :

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

Paramètres :

targetrange: la plage o√Ļ ins√©rer les formules, sous forme de cha√ģne

formula¬†: une cha√ģne, un vecteur ou une matrice de cha√ģnes avec les nouvelles formules pour chaque cellule de la plage cible.

La plage complète est mise à jour et le reste de la feuille demeure inchangé.

Si la formule donn√©e est une cha√ģne, la formule unique est coll√©e sur toute la plage avec ajustement des r√©f√©rences relatives.

Si la taille de la formula est inférieure à la taille de la targetrange, alors les cellules restantes sont vidées.

Si la taille de formula est supérieure à la taille de targetrange, alors les formules ne sont que partiellement copiées jusqu'à ce qu'elles remplissent la taille de targetrange.

Les vecteurs sont toujours étendus verticalement, sauf si targetrange a une hauteur d'exactement 1 ligne.

Exemple :

En Basic :

    oDoc.SetFormula("A1", "=A2")
    ' vecteur horizontal, partiellement vide
    oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
    'D2 contient la formule "=H2"
    oDoc.SetFormula("A1:D2", "=E1")
  
En Python

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

ShiftDown

Déplace une plage donnée de cellules vers le bas en insérant des lignes vides. La sélection actuelle n'est pas affectée.

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.

Cette m√©thode renvoie une cha√ģne repr√©sentant le nouvel emplacement de la plage initiale.

note

Si la plage décalée dépasse les bords de la feuille, rien ne se passe.


Syntaxe :

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

Paramètres :

range¬†: la plage au-dessus de laquelle les lignes seront ins√©r√©es, sous forme de cha√ģne.

wholerow : si défini sur False (par défaut), la largeur des lignes insérées sera la même que la largeur de range spécifiée. Sinon, la ligne insérée s'étendra sur toutes les colonnes de la feuille.

rows : le nombre de lignes à insérer. La valeur par défaut est la hauteur de range d'origine. Le nombre de lignes doit être un nombre positif.

Exemple :

En Basic :

    ' Déplace la plage "A3:D3" vers le bas d'une ligne ; affecte uniquement les colonnes A à D
    oDoc.ShiftDown("A3:D3")
    ' La ligne insérée s'étend sur toutes les colonnes de la feuille
    oDoc.ShiftDown("A3:D3", WholeRow := True)
    ' Déplace la plage "A3:D3" vers le bas de cinq lignes
    oDoc.ShiftDown("A3:D3", Rows := 5)
    ' Déplace la plage "A3:D10" vers le bas de deux lignes et affiche le nouvel emplacement de la plage d'origine
    Dim sNewRange as String
    sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)
    MsgBox sNewRange   ' $Sheet1.$A$5:$D$12
  
En 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

Supprime les colonnes les plus à gauche d'une plage donnée et déplace vers la gauche toutes les cellules à droite de la plage affectée. La sélection actuelle n'est pas affectée.

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.

Cette m√©thode renvoie une cha√ģne repr√©sentant l'emplacement de la partie restante de la plage initiale. Si toutes les cellules de la plage d'origine ont √©t√© supprim√©es, une cha√ģne vide est renvoy√©e.

Syntaxe :

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

Paramètres :

range¬†: la plage √† partir de laquelle les cellules seront supprim√©es, sous forme de cha√ģne.

wholecolumn : si défini sur False (par défaut), la hauteur des colonnes supprimées sera la même que la hauteur de range spécifiée. Sinon, les colonnes supprimées s'étendront sur toutes les lignes de la feuille.

columns : nombre de colonnes à supprimer de range spécifiée. La valeur par défaut est la largeur de range d'origine, qui est également la valeur maximale de cet argument.

Exemple :

En Basic :

    ' Supprime la plage "B3:B6" ; déplace à gauche toutes les cellules vers la droite
    oDoc.ShiftLeft("B3:B6")
    ' Supprime la première colonne de la plage "A3:D6"
    oDoc.ShiftLeft("A3:D6", Columns := 1)
    ' Les colonnes supprimées (A à D) s'étendent sur toutes les lignes de la feuille
    oDoc.ShiftLeft("A3:D6", WholeColumn := True)
  
En Python

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

ShiftUp

Supprime les premières lignes d'une plage donnée et déplace vers le haut toutes les cellules en dessous de la plage affectée. La sélection actuelle n'est pas affectée.

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.

Cette m√©thode renvoie une cha√ģne repr√©sentant l'emplacement de la partie restante de la plage initiale. Si toutes les cellules de la plage d'origine ont √©t√© supprim√©es, une cha√ģne vide est renvoy√©e.

Syntaxe :

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

Paramètres :

range¬†: la plage √† partir de laquelle les cellules seront supprim√©es, sous forme de cha√ģne.

wholerow : si défini sur False (par défaut), la largeur des lignes supprimées sera la même que la largeur de range spécifiée. Sinon, la ligne supprimée s'étendra sur toutes les colonnes de la feuille.

columns : nombre de lignes à supprimer de range spécifiée. La valeur par défaut est la hauteur de range d'origine, qui est également la valeur maximale de cet argument.

Exemple :

En Basic :

    ' Supprime la plage "A3:D3" ; déplace toutes les cellules en dessous d'une ligne vers le haut
    oDoc.ShiftUp("A3:D3")
    ' Supprime la première ligne de la plage "A3:D6"
    oDoc.ShiftUp("A3:D6", Rows := 1)
    ' La ligne supprimée s'étend sur toutes les colonnes de la feuille
    oDoc.ShiftUp("A3:D6", WholeRow := True)
  
En Python

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

ShiftRight

Déplace une plage donnée de cellules vers la droite en insérant des colonnes vides. La sélection actuelle n'est pas affectée.

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.

Cette m√©thode renvoie une cha√ģne repr√©sentant le nouvel emplacement de la plage initiale.

note

Si la plage décalée dépasse les bords de la feuille, rien ne se passe.


Syntaxe :

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

Paramètres :

range¬†: la plage qui aura des colonnes vides ins√©r√©es √† sa gauche, sous forme de cha√ģne.

wholecolumn : si défini sur False (par défaut), la hauteur des colonnes insérées sera la même que la hauteur de range spécifiée. Sinon, les colonnes insérées s'étendront sur toutes les lignes de la feuille.

columns : le nombre de colonnes à insérer. La valeur par défaut est la largeur de range d'origine.

Exemple :

En Basic :

    ' Déplace la plage "A3:A6" vers la droite d'une colonne ; n'affecte que les lignes 3 à 6
    oDoc.ShiftRight("A3:A6")
    ' Déplace la plage "A3:A6" vers la droite de cinq colonnes
    oDoc.ShiftRight("A3:A6", Columns := 5)
    ' La colonne insérée s'étend sur toutes les lignes de la feuille
    oDoc.ShiftRight("A3:A6", WholeColumn := True)
  
En Python

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

SortRange

Trie la plage donn√©e en fonction d'un maximum de 3 colonnes/lignes. L'ordre de tri peut varier selon la colonne/ligne. Il renvoie une cha√ģne repr√©sentant la plage de cellules modifi√©e. La taille de la zone modifi√©e est enti√®rement d√©termin√©e par la taille de la zone source.

Syntaxe :

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

Paramètres :

range¬†: la plage √† trier, sous forme de cha√ģne.

sortkeys : un scalaire (si 1 colonne/ligne) ou une matrice de numéros de colonne/ligne commençant à 1. Le nombre maximum de clés est 3.

sortorder¬†: un scalaire ou une matrice de cha√ģnes contenant les valeurs "ASC" (croissant), "DESC" (d√©croissant) ou "" (par d√©faut, croissant). Chaque √©l√©ment est associ√© √† l'√©l√©ment correspondant dans les sortkeys. Si le tableau sortorder est plus court que sortkeys, les cl√©s restantes sont tri√©es par ordre croissant.

destinationcell¬†: la cellule de destination de la plage de cellules tri√©e, sous forme de cha√ģne. Si une plage est donn√©e, seule sa cellule en haut √† gauche est prise en compte. Par d√©faut, la plage source est √©cras√©e.

containsheader : lorsque True, la première ligne/colonne n'est pas triée.

casesensitive¬†: uniquement pour les comparaisons de cha√ģnes. Par d√©faut = False

sortcolumns : lorsque True, les colonnes sont triées de gauche à droite. Par défaut = False : les lignes sont triées de haut en bas.

Exemple :

En Basic :

    'Trier la plage en fonction des colonnes A (croissant) et C (décroissant)
    oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)
  
En Python

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

Toutes les routines ou identifiants de base ScriptForge qui sont préfixés par un caractère de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans des macros de base ou des scripts Python.


Aidez-nous !