Service SFDocuments.Calc

Contenu

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

- Gestion des feuilles dans un document Calc (copier, insérer, déplacer, etc.)

- Échange de données entre les structures de données de base et les plages Calc

- Copier et importer des quantités massives de données

- Formatage simple des plages de cellules

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

## Invocation du service

Avant d'utiliser le service Calc, la bibliothèque ScriptForge doit être chargée ou importée :

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Les scripts Python nécessitent un import depuis le module scriptforge :
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 en spécifiant un nom de fenêtre pour 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 également possible d'invoquer le service Calc en utilisant le document référencé par ThisComponent. Ceci est particulièrement utile lors de l'exécution d'une macro à partir de l'IDE Basic.

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

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

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

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 :

- Dans une instance spécifique Calc , les feuilles et les plages sont données sous forme de chaînes telles que "Sheet1" et "D2:F6".

- De plus, les propriétés .Sheet et .Range renvoient une référence qui peut être utilisée comme argument d'une méthode appelée depuis une autre instance du service Calc.

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

Le nom de la feuille est facultatif lors de la définition d'une plage. Si aucun nom de feuille n'est fourni, la feuille active est utilisée. Les guillemets simples et les signes $ environnants sont autorisés mais ignorés.

Lorsque vous spécifiez un SheetName en tant que chaîne, l'utilisation de guillemets simples pour entourer le nom de la feuille est requise si le nom contient des espaces vides " " ou des points ".".

Les exemples ci-dessous illustrent dans quels cas l'utilisation de guillemets simples est obligatoire :

          ' L'utilisation de guillemets simples est facultative
          oDoc.clearAll("SheetA.A1:B10")
          oDoc.clearAll("'SheetA'.A1:B10")
          ' L'utilisation de guillemets simples est requise
          oDoc.clearAll("'Sheet.A'.A1:B10")

À 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.
DefinedNames | Oui | Auncune | Chaîne ou matrice de chaînes | Renvoie la liste complète et triée de toutes les plages nommées du document. Les noms définis dans une même feuille sont qualifiés par le nom de cette feuille.
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 Commande + *Ctrl + * à 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 | Oui | RangeName As String | String | Renvoie le nom de feuille d'une plage d'adresses donnée.
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.
XRectangle | Oui | RangeName As String | Object | Une structure UNO com.sun.star.awt.Rectangle, décrivant, en pixels, la zone sur l'écran où se trouve la plage.
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

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 AlignRange BorderRange Charts ClearAll ClearFormats ClearValues ColorizeRange CompactLeft CompactUp CopySheet CopySheetFromFile CopyToCell CopyToRange CreateChart CreatePivotTable DAvg | DCount DecorateFont DefineName DMax DMin DSum ExportRangeToFile FormatRange Forms GetColumnName GetFormula GetValue ImportFromCSVFile ImportFromDatabase ImportStylesFromFile InsertSheet Intersect MoveRange | MoveSheet Offset OpenRangeSelector PrintOut Printf RemoveDuplicates RemoveSheet RenameSheet SetArray SetCellStyle SetFormula SetValue 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

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

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.

## AlignRange

Aligner horizontalement ou verticalement une plage de cellules.

Une formule de filtre peut être spécifiée pour déterminer quelles cellules seront affectées.

### Syntaxe :

svc.AlignRange(targetrange: str, alignment: str, opt filterformula: str, opt filterscope: str)

### Paramètres :

targetrange: la cellule ou la plage sous forme de chaîne de caractères dans laquelle les cellules doivent être réalignées.

alignment : une chaîne combinant 1 ou 2 caractères majuscules consécutifs (les autres caractères sont ignorés) :

- L, R ou C : gauche, droite ou centre horizontalement.

- B, T ou M : en bas, en haut ou au centre verticalement (milieu).

filterformula : une formule Calc devant être appliquée à la plage de cellules spécifiée pour déterminer les cellules affectées. La formule spécifiée doit renvoyer True ou False. Si cet argument n'est pas spécifié, toutes les cellules de la plage sont affectées.

filterscope : détermine comment filterformula est étendu à la plage spécifiée. Cet argument est obligatoire si filterformula est spécifiée. Les valeurs suivantes sont acceptées :

- "CELL": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque cellule dans range.

- "ROW": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque ligne dans range.

- "COLUMN": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque colonne dans range.

### Exemple :

##### En Basic :

          ' Centrez toutes les cellules numériques, horizontalement et verticalement.
          doc.AlignRange("SheetX.A1:J30", "Middle,Center", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### En Python

          # Centrez toutes les cellules numériques, horizontalement et verticalement.
          doc.AlignRange('SheetX.A1:J30', 'Middle,Center', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## BorderRange

Appliquez un ensemble de bordures linéaires à l'intérieur et autour d'une plage de cellules.

Les cellules concernées peuvent être déterminées à l'aide d'une formule de filtre et de sa portée.

Toutes les bordures ont la même largeur standard, le même style et la même couleur. Les lignes bordures existantes dans les cellules, lignes ou colonnes concernées sont d'abord supprimées. Les autres cellules de la plage restent inchangées.

Pour effacer toute la plage, définissez border sur "" et ignorez l'argument filterformula.

### Syntaxe :

svc.BorderRange(targetrange: str, border: str, opt filterformula: str, opt filterscope: str)

### Paramètres :

targetrange: la cellule ou la plage sous forme de chaîne de caractères sur laquelle des bordures doivent être appliquées.

border : une chaîne de caractères combinant les caractères majuscules suivants (les autres caractères sont ignorés) :

- B, L, T, R : lignes extérieures bas, gauche, haut, droit

- H,V: lignes intérieures horizontales, verticales.

- U, D : diagonales ascendantes, descendantes.

filterformula : une formule Calc devant être appliquée à la plage de cellules spécifiée pour déterminer les cellules affectées. La formule spécifiée doit renvoyer True ou False. Si cet argument n'est pas spécifié, toutes les cellules de la plage sont affectées.

filterscope : détermine comment filterformula est étendu à la plage spécifiée. Cet argument est obligatoire si filterformula est spécifiée. Les valeurs suivantes sont acceptées :

- "CELL": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque cellule dans range.

- "ROW": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque ligne dans range.

- "COLUMN": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque colonne dans range.

### Exemple :

##### En Basic :

            'Encadrer toutes les cellules numériques d'une ligne inférieure, y compris les lignes horizontales intérieures.
            doc.BorderRange("SheetX.A1:J30", "HB", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### En Python

            # Encadrer toutes les cellules numériques d'une ligne inférieure, y compris les lignes horizontales intérieures.
            doc.BorderRange('SheetX.A1:J30', 'HB', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

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

- Si seul sheetname est spécifié, une matrice de chaînes de base zéro contenant les noms de tous les diagrammes est renvoyée.

- Si un chartname est fourni, un seul objet correspondant au diagramme souhaité est renvoyé. Le diagramme spécifié doit exister.

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

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.

Une formule de filtre peut être spécifiée pour déterminer quelles cellules seront affectées.

### Syntaxe :

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

### Paramètres :

range : la plage à effacer, sous forme de chaîne.

filterformula : une formule Calc devant être appliquée à la plage de cellules spécifiée pour déterminer les cellules affectées. La formule spécifiée doit renvoyer True ou False. Si cet argument n'est pas spécifié, toutes les cellules de la plage sont affectées.

filterscope : détermine comment filterformula est étendu à la plage spécifiée. Cet argument est obligatoire si filterformula est spécifiée. Les valeurs suivantes sont acceptées :

- "CELL": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque cellule dans range.

- "ROW": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque ligne dans range.

- "COLUMN": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque colonne dans range.

### Exemple :

##### En Basic :

        ' Efface toutes les cellules de la plage SheetX.A1:J10
        oDoc.ClearAll("SheetX.A1:J10")
        ' Efface toutes les cellules de la plage SheetX.A1:J10 qui ont une valeur supérieure à 100
        oDoc.ClearAll("SheetX.A1:J10", "=SheetX.A1>100", "CELL")
        ' Efface toutes les lignes de la plage SheetX.A1:J10 dont la somme est supérieure à 500
        oDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:J1)>500", "ROW")
        ' Efface toutes les colonnes de la plage SheetX.A1:J10 dont la somme est supérieure à 500
        oDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:A10)>500", "COLUMN")

##### En Python

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

## ClearFormats

Efface les formats et les styles de cellule dans la plage spécifiée.

Une formule de filtre peut être spécifiée pour déterminer quelles cellules seront affectées.

### Syntaxe :

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

### Paramètres :

range : la plage dont les formats et les styles doivent être effacés, sous forme de chaîne.

filterformula : une formule Calc devant être appliquée à la plage de cellules spécifiée pour déterminer les cellules affectées. La formule spécifiée doit renvoyer True ou False. Si cet argument n'est pas spécifié, toutes les cellules de la plage sont affectées.

filterscope : détermine comment filterformula est étendu à la plage spécifiée. Cet argument est obligatoire si filterformula est spécifiée. Les valeurs suivantes sont acceptées :

- "CELL": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque cellule dans range.

- "ROW": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque ligne dans range.

- "COLUMN": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque colonne dans range.

### Exemple :

##### En Basic :

          oDoc.ClearFormats("SheetX.*")

##### En Python

        myDoc.ClearFormats("SheetX.*")

Reportez-vous à la documentation de la méthode ClearAll pour des exemples d'utilisation des arguments filterformula et filterscope.

## ClearValues

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

Une formule de filtre peut être spécifiée pour déterminer quelles cellules seront affectées.

### Syntaxe :

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

### Paramètres :

plage : la plage dont les valeurs et les formules doivent être effacées, sous forme de chaîne.

filterformula : une formule Calc devant être appliquée à la plage de cellules spécifiée pour déterminer les cellules affectées. La formule spécifiée doit renvoyer True ou False. Si cet argument n'est pas spécifié, toutes les cellules de la plage sont affectées.

filterscope : détermine comment filterformula est étendu à la plage spécifiée. Cet argument est obligatoire si filterformula est spécifiée. Les valeurs suivantes sont acceptées :

- "CELL": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque cellule dans range.

- "ROW": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque ligne dans range.

- "COLUMN": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque colonne dans range.

### Exemple :

##### En Basic :

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

##### En Python

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

Reportez-vous à la documentation de la méthode ClearAll pour des exemples d'utilisation des arguments filterformula et filterscope.

## ColorizeRange

Définir les couleurs de premier plan et d'arrière-plan d'une série de cellules.

Les cellules concernées peuvent être déterminées à l'aide d'une formule de filtre et de sa portée.

### Syntaxe :

svc.ColorizeRange(targetrange: str, opt foreground: int, opt background: int, opt filterformula: str, opt filterscope: str)

### Paramètres :

targetrange: la cellule ou la plage sous forme de chaîne de caractères dans laquelle les cellules doivent être (re)colorées.

foreground : la couleur de premier plan résultant de la fonction RVB(). Une valeur négative efface la couleur de premier plan.

background : la couleur d'arrière-plan, résultat de la fonction RVB(). Une valeur négative supprime la couleur d'arrière-plan.

filterformula : une formule Calc devant être appliquée à la plage de cellules spécifiée pour déterminer les cellules affectées. La formule spécifiée doit renvoyer True ou False. Si cet argument n'est pas spécifié, toutes les cellules de la plage sont affectées.

filterscope : détermine comment filterformula est étendu à la plage spécifiée. Cet argument est obligatoire si filterformula est spécifiée. Les valeurs suivantes sont acceptées :

- "CELL": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque cellule dans range.

- "ROW": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque ligne dans range.

- "COLUMN": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque colonne dans range.

### Exemple :

##### En Basic :

            ' Colorier la ou les cellules numériques en rouge.
            doc.ColorizeRange("SheetX.A1:J30", background := RGB(255, 0, 0), filterformula := "=IsNumeric(A1), filterscope := "CELL")

##### En Python

            # Colorier la ou les cellules numériques en rouge.
            basic = CreateScriptService('basic')
            doc.ColorizeRange('SheetX.A1:J30', background = basic.RGB(255, 0, 0), filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## CompactLeft

Supprime les colonnes d'une plage spécifiée qui correspondent à un filtre exprimé sous forme de formule Calc. Le filtre est appliqué à chaque colonne pour décider si elle sera supprimée ou non.

La colonne supprimée peut être limitée à la hauteur de la plage spécifiée ou s'étendre à la hauteur de la feuille entière, supprimant ainsi des colonnes entières.

Cette méthode renvoie une chaîne avec l'adresse de plage de la plage compactée. Si toutes les colonnes sont supprimées, une chaîne vide est renvoyée.

Si une plage de cellules est sélectionnée, l'appel de cette méthode n'aura pas d'impact sur la sélection.

### Syntaxe :

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

### Paramètres :

range : la plage à partir de laquelle les colonnes seront supprimées, sous forme de chaîne.

wholecolumn : si cette option est définie sur True, la colonne entière sera supprimée de la feuille. La valeur par défaut est False, ce qui signifie que la colonne supprimée sera limitée à la hauteur de la plage spécifiée.

filterformula : le filtre à appliquer à chaque colonne pour déterminer si elle sera supprimée ou non. Le filtre est exprimé sous la forme d'une formule Calc qui doit être appliquée à la première colonne. Lorsque la formule renvoie True pour une colonne, cette colonne sera supprimée. Le filtre par défaut supprime toutes les colonnes vides.

Par exemple, supposons que la plage A1:J200 est sélectionnée (hauteur = 200), la formule par défaut est donc =(COUNTBLANK(A1:A200)=200). Cela signifie que si les 200 cellules sont vides dans la première colonne (colonne A), la colonne est supprimée. Notez que la formule est exprimée par rapport à la première colonne uniquement. En interne, la méthode CompactLeft généralisera cette formule pour toutes les colonnes restantes.

Les fonctions Calc utilisées dans l'argument filterformula doivent être exprimées en utilisant leurs noms anglais. Visitez la page Wiki Liste des fonctions Calc pour une liste complète des fonctions Calc en anglais.

### Exemple :

##### En Basic :

        ' Supprimer toutes les colonnes vides dans la plage G1:L10 de Sheet1
        newrange = oDoc.CompactLeft("Sheet1.G1:L10")
        ' L'exemple ci-dessous est similaire, mais toute la colonne est supprimée de la feuille
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", WholeColumn := True)
        ' Supprime toutes les colonnes dont la première ligne est marquée d'un "X"
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Supprime toutes les colonnes où la somme des valeurs de la colonne est impaire
        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

Supprime les lignes d'une plage spécifiée qui correspondent à un filtre exprimé sous forme de formule Calc. Le filtre est appliqué à chaque ligne pour décider si elle sera supprimée ou non.

Les lignes supprimées peuvent être limitées à la largeur de la plage spécifiée ou s'étendre à la largeur de la feuille entière, supprimant ainsi des lignes entières.

Cette méthode renvoie une chaîne avec l'adresse de plage de la plage compactée. Si toutes les lignes sont supprimées, une chaîne vide est renvoyée.

Si une plage de cellules est sélectionnée, l'appel de cette méthode n'aura pas d'impact sur la sélection.

### Syntaxe :

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

### Paramètres :

plage : la plage à partir de laquelle les lignes seront supprimées, sous forme de chaîne.

wholerow : si cette option est définie sur True, la ligne entière sera supprimée de la feuille. La valeur par défaut est False, ce qui signifie que la ligne supprimée sera limitée à la largeur de la plage spécifiée.

filterformula : Le filtre à appliquer à chaque ligne pour déterminer si elle sera supprimée ou non. Le filtre est exprimé sous la forme d'une formule Calc qui doit être appliquée à la première ligne. Lorsque la formule renvoie True pour une ligne, cette ligne sera supprimée. Le filtre par défaut supprime toutes les lignes vides.

Par exemple, supposons que la plage A1:J200 est sélectionnée (largeur = 10), la formule par défaut est donc =(COUNTBLANK(A1:J1)=10). Cela signifie que si les 10 cellules sont vides dans la première ligne (ligne 1), la ligne est supprimée. Notez que la formule est exprimée par rapport à la première ligne uniquement. En interne, la méthode CompactUp généralisera cette formule pour toutes les lignes restantes.

Les fonctions Calc utilisées dans la formule spécifiée dans l'argument filterformula doivent être exprimées en utilisant leurs noms anglais. Visitez la page Wiki Liste des fonctions Calc pour une liste complète des fonctions Calc en anglais.

### Exemple :

##### En Basic :

        ' Supprimer toutes les lignes vides dans la plage G1:L10 de Sheet1
        newrange = oDoc.CompactUp("Sheet1.G1:L10")
        ' L'exemple ci-dessous est similaire, mais la ligne entière est supprimée de la feuille
        newrange = oDoc.CompactUp("Sheet1.G1:L10", WholeRow := True)
        ' Supprime toutes les lignes dont la première colonne est marquée d'un "X"
        newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Supprime toutes les lignes où la somme des valeurs de la ligne est impaire
        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")

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

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.

- Copie vers le bas et/ou vers la droite une plage source définie (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.

- Si la hauteur (ou largeur) de la destination est = 1, alors la destination est étendue vers le bas (ou vers la droite) jusqu'à la hauteur (ou largeur) de la plage source.

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 de données à utiliser comme source pour le diagramme. Cette plage peut faire référence à n’importe quelle feuille du document Calc.

columnheader : lorsque True, la ligne supérieure de la plage est utilisée comme étiquette 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"

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

Crée une nouvelle table dynamique avec les propriétés définies par les arguments passés à la méthode.

Un nom doit être fourni pour la table dynamique. Si une table dynamique portant le même nom existe déjà dans la feuille ciblée, il sera remplacé sans avertissement.

Cette méthode renvoie une chaîne contenant la plage où la nouvelle table dynamique a été placé.

### 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 : Le nom défini par l'utilisateur de la nouvelle table dynamique.

sourcerange : la plage contenant les données brutes, sous forme de chaîne. On suppose que la première ligne contient les noms de champs utilisés par la table dynamique.

targetcell : la cellule en haut à gauche où la nouvelle table dynamique sera insérée. Si une plage est spécifiée, seule sa cellule en haut à gauche est prise en compte.

datafields : Il peut s’agir d’une chaîne de caractères unique ou d’un tableau contenant des chaînes de caractères définissant les noms des champs et les fonctions à appliquer. Lorsqu’une matrice est spécifiée, ellel doit respecter la syntaxe suivante : Array("FieldName[;Function]", ...).

Les fonctions autorisées sont : Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP et Median. Les noms de fonction doivent être fournis en anglais. Lorsque toutes les valeurs sont numériques, Sum est la fonction par défaut, sinon la fonction par défaut est Count.

rowfields une chaîne de caractères unique ou une matrice contenant les noms des champs qui seront utilisés comme lignes de la table dynamique.

columnfields : une chaîne de caractères unique ou une matrice contenant les noms des champs qui seront utilisés comme colonnes de la table dynamique.

filterbutton : éétermine si un bouton de filtre sera affiché au-dessus de la table dynamique (par défaut = True).

rowtotals : indique si une colonne distincte pour les totaux des lignes sera ajoutée à la table dynamique (par défaut = True).

columntotals : indique si une ligne distincte pour les totaux de colonnes sera ajoutée à la table dynamique (par défaut : 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", _ ' Un champ à une seule ligne
            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)

Pour en savoir plus sur les tables dynamiques dans LibreOffice Calc, consultez la page d'aide du Table dynamique.

## DAvg, DCount, DMax, DMin and DSum

Appliquez respectivement les fonctions Moyenne, Compte, Max, Min et Somme à toutes les cellules contenant des valeurs numériques sur une plage donnée, à l'exclusion des valeurs des lignes filtrées et masquées et des colonnes masquées, comme pour les fonctions de la barre d'état.

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

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.

## DecorateFont

Définir des propriétés de police simples et faciles à utiliser pour une plage de cellules.

Les cellules concernées peuvent être déterminées à l'aide d'une formule de filtre et de sa portée.

Pour appliquer des décorations de police plus complexes, utilisez les nombreuses et habituelles propriétés UNO disponibles dans les interfaces XCell ou XCellRange.

### Syntaxe :

svc.DecorateFont(targetrange: str, opt fontname: str, opt fontsize: int, opt decoration: str, opt filterformula: str, opt filterscope: str)

### Paramètres :

targetrange : la cellule ou la plage sous forme de chaîne de caractères dans laquelle la mise en forme des polices de cellules doit être réappliquée.

fontname : le nom de la police à utiliser. Le nom n'est pas vérifié. Par défaut = aucun changement.

fontsize : la taille de la police en pixels. Par défaut = aucun changement.

decoration : une chaîne combinant un ou plusieurs des caractères majuscules suivants (les autres caractères sont ignorés). Par défaut = aucun changement.

- B, U, I, S : Gras, Souligné, Italique, Barré.

filterformula : une formule Calc devant être appliquée à la plage de cellules spécifiée pour déterminer les cellules affectées. La formule spécifiée doit renvoyer True ou False. Si cet argument n'est pas spécifié, toutes les cellules de la plage sont affectées.

filterscope : détermine comment filterformula est étendu à la plage spécifiée. Cet argument est obligatoire si filterformula est spécifiée. Les valeurs suivantes sont acceptées :

- "CELL": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque cellule dans range.

- "ROW": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque ligne dans range.

- "COLUMN": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque colonne dans range.

### Exemple :

##### En Basic :

            'Modifier la taille de la police et appliquer les attributs gras et souligné aux cellules numériques.
            doc.DecorateFont("SheetX.A1:J30", fontsize := 15, decoration := "Bold,Underline", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### En Python

            # Modifier la taille de la police et appliquer les attributs gras et souligné aux cellules numériques.
            doc.DecorateFont('SheetX.A1:J30', fontsize = 15, decoration = 'Bold,Underline', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## DefineName

Définir un nouveau nom dans la feuille de calcul, au niveau global ou au niveau de la feuille. Si le nom existe déjà, il est écrasé sans avertissement. Après sa création, le nouveau nom peut être utilisé dans des formules. Renvoie True en cas de succès.

Utilisez la propriété DefinedNames pour examiner les plages nommées existantes.

### Syntaxe :

svc.DefineName(definedname: str, value: any, opt sheetname: str): boolean

### Paramètres :

definedname : le nom à créer ou à modifier sans avertissement. Notez que des homonymes peuvent exister, mais pas dans la même feuille ni au niveau global.

value : le nouveau nom comme :

- une référence de plage sous forme de chaîne de caractères, souvent une cellule unique

- une valeur scalaire sous forme de nombre ou de chaîne de caractères

- une formule commençant avec le signe "="

Lorsque Value est une plage, la cellule supérieure gauche est définie comme cellule de référence.

sheetname : l'étendue du nom défini est celle de la feuille spécifiée. Le raccourci "~" est accepté.

### Exemple :

##### En Basic :

            doc.DefineName("NewName", Sheet := "Sheet3", Value := "H2")

##### En Python

            doc.DefineName('NewName', sheet = 'Sheet3', value = 'H2')

## ExportRangeToFile

Exporte la plage spécifiée sous forme d'image ou de fichier PDF.

Cette méthode renvoie True si le fichier de destination a été enregistré avec succès.

Les lignes ou colonnes masquées dans la plage spécifiée ne sont pas exportées vers le fichier de destination.

### Syntaxe :

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

### Paramètres :

range : un nom de feuille ou une plage de cellules à exporter, sous forme de chaîne.

filename : le nom du fichier à enregistrer. Il doit suivre la notation SF_FileSystem.FileNaming.

imagetype : identifie le type de fichier de destination. Les valeurs possibles sont "jpeg", "pdf" (par défaut) et "png".

overwrite : lorsqu'il est défini sur True, le fichier de destination peut être écrasé (par défaut = False).

### Exemple :

##### En Basic :

        ' Exporte la totalité de la feuille sous forme de fichier PDF
        oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
        ' Exporte la plage sous forme de fichier PNG et écrase le fichier de destination s'il existe
        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)

## FormatRange

Appliquer un format de nombre donné à une cellule ou à une plage de cellules.

Les cellules concernées peuvent être déterminées à l'aide d'une formule de filtre et de sa portée.

### Syntaxe :

svc.FormatRange(targetrange: str, numberformat: str, opt locale: str, opt filterformula: str, opt filterscope: str)

### Paramètres :

targetrange : la cellule ou la plage sous forme de chaîne de caractères devant recevoir le format.

numberformat: le format à appliquer, sous forme de chaîne de caractère.

locale : Une combinaison la-CO (langue-PAYS) indiquant les paramètres régionaux utilisés. Les paramètres régionaux par défaut correspondent à la valeur de la propriété platform.FormatLocale.

filterformula : une formule Calc devant être appliquée à la plage de cellules spécifiée pour déterminer les cellules affectées. La formule spécifiée doit renvoyer True ou False. Si cet argument n'est pas spécifié, toutes les cellules de la plage sont affectées.

filterscope : détermine comment filterformula est étendu à la plage spécifiée. Cet argument est obligatoire si filterformula est spécifiée. Les valeurs suivantes sont acceptées :

- "CELL": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque cellule dans range.

- "ROW": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque ligne dans range.

- "COLUMN": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque colonne dans range.

### Exemple :

##### En Basic :

            ' Formater uniquement les cellules contenant une valeur numérique.
            doc.FormatRange("SheetX.A1:J30", "0,00E+00", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### En Python

            # Formater uniquement les cellules contenant une valeur numérique.
            doc.FormatRange('SheetX.A1:J30', '0,00E+00', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## Forms

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

- Une matrice de base zéro (ou un tuple en Python) avec les noms de tous les formulaires contenus dans une feuille donnée (si l'argument form est absent)

- Une instance de service SFDocuments.Form représentant le formulaire spécifié comme argument.

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

numérodecolonne: Le numéro de colonne sous forme de valeur entière dans l'intervalle 1 ... 16384.

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

Le nombre maximal de colonnes autorisées sur une feuille Calc est de 16384.

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

Les noms des fonctions Calc utilisées dans les formules renvoyées sont exprimés en anglais. Visitez la page Wiki Liste des fonctions Calc pour une liste complète des fonctions Calc en anglais.

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

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 :

- L'encodage du fichier d'entrée est UTF8.

- Le séparateur de champ est une virgule, un point-virgule ou un caractère de tabulation.

- Le délimiteur de chaîne est le guillemet double (").

- Toutes les lignes sont incluses.

- Les chaînes entre guillemets sont formatées en texte.

- Les nombres spéciaux sont détectés.

- Toutes les colonnes sont présumées être des textes, sauf si elles sont reconnues comme des nombres valides.

- La langue est anglais/américain, ce qui implique que le séparateur décimal est "." et le séparateur des milliers est ",".

### Exemple :

##### En Basic :

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

##### En Python

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

Pour en savoir plus sur les options de filtre CSV, consultez la page d'aide des options de filtre CSV.

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

### ImportStylesFromFile

Cette méthode charge tous les styles appartenant à une ou plusieurs familles de styles d'un fichier fermé dans le document actif. Le document actif doit être un document Calc ou Writer.

Sont toujours importés ensemble :

- ParagraphStyles et CharacterStyles

- NumberingStyles et ListStyles

Renvoie True si les styles ont été importés avec succès.

### Syntaxe :

svc.ImportStylesFromFile(filename: str, families: str[1..*], overwrite = False): bool

### Paramètres :

filename : le fichier à partir duquel charger les styles dans la notation FileSystem. Le fichier est présumé être du même type de document que le document actif.

families : une des familles de style présentes dans le document réel, sous la forme d'une chaîne sensible à la casse ou d'un tableau de telles chaînes. Laissez cet argument vide pour importer toutes les familles.

overwrite : lorsque True, les styles réels peuvent être écrasés. La valeur par défaut est False.

### Exemple :

##### En Basic :

        oDoc.ImportStylesFromFile("C:\User\Documents\myFile.ods", "ParagraphStyles", True)

##### En Python

        doc.ImportStylesFromFile('C:\User\Documents\myFile.ods', ("ParagraphStyles",), False)

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

## Intersect

Renvoie la chaîne représentant l'intersection entre les deux plages d'entrée, ou une chaîne de longueur nulle lorsque l'intersection est vide.

### Syntaxe :

svc.Intersect(range1:str, range2: str): str

### Paramètres :

plage1 : la chaîne d’adresse de la plage 1.

plage2 : la chaîne d’adresse de la plage 2.

### Exemple :

L'exemple suivant intersecte deux plages et renvoie la plage commune entre les deux :

##### En Basic :

        Dim commonrange As String
        commonrange = oDoc.Intersect("A1:D8", "C3:F4")
        Print commonrange ' affiche "$Feuille1.$C$3:$D$4"

##### En Python

        common_range = myDoc.Intersect("A1:D8", "C3:F4")
        print(common_range) # renvoie '$Feuille1.$C$3:$D$4' au shell Python

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

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.

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 :

- %S - le nom de la feuille contenant la plage, y compris les guillemets simples si nécessaire.

- %R1 - le numéro de ligne de la cellule en haut à gauche de la plage.

- %C1 - la lettre de la colonne de la cellule en haut à gauche de la plage.

- %R2 - le numéro de ligne de la cellule en bas à droite de la plage.

- %C2 - la lettre de la colonne de la cellule en bas à droite de la plage.

### 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'):
            # ...

## RemoveDuplicates

Supprime les lignes en double d'une plage spécifiée. La comparaison pour déterminer si une ligne donnée est un doublon est effectuée sur la base d'un sous-ensemble de colonnes de la plage.

Cette méthode renvoie une chaîne contenant la plage résultante.

La suppression des lignes en double est effectuée en commençant par la première ligne de la plage en descendant, ce qui signifie que si deux lignes ou plus sont des doublons, seule la première est conservée.

### Syntaxe :

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

### Paramètres :

plage : la plage à partir de laquelle les doublons seront supprimés, sous forme de chaîne.

columns : une matrice contenant des numéros de colonne indiquant quelles colonnes seront prises en compte pour déterminer si une ligne est un doublon ou non. Si cet argument est laissé vide, seule la première colonne est utilisée. Les éléments de cette matrice doivent se trouver dans l'intervalle entre 1 et la largeur de la plage.

header : spécifie si la première ligne est une ligne d'en-tête (par défaut = False).

casesensitive : spécifie si les comparaisons de chaînes sont sensibles à la casse (par défaut = False).

mode : spécifie ce qu'il faut faire avec les lignes en double. Si mode = "CLEAR" alors les doublons sont simplement supprimés de la feuille en laissant les cellules vides. Si mode = "COMPACT" alors les doublons sont supprimés et les lignes vides sont compactées (par défaut = "COMPACT").

### Exemple :

##### En Basic :

        ' Supprime les lignes en double où les valeurs de la colonne A sont en double
        ' Notez que tous les arguments optionnels utilisent leur valeur par défaut
        oDoc.RemoveDuplicates("A1:B10")
        ' Supprime les lignes en double en considérant que la première ligne contient des en-têtes
        ' Les colonnes A et B sont utilisées pour déterminer si une ligne est un doublon
        ' Les cellules contenant des valeurs en double sont laissées vides
        oDoc.RemoveDuplicates("A1:D10", columns := Array(1, 2), header := True, mode := "CLEAR")

##### En Python

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

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

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.

## 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, opt filterformula: str, opt filterscope: 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.

filterformula : une formule Calc devant être appliquée à la plage de cellules spécifiée pour déterminer les cellules affectées. La formule spécifiée doit renvoyer True ou False. Si cet argument n'est pas spécifié, toutes les cellules de la plage sont affectées.

filterscope : détermine comment filterformula est étendu à la plage spécifiée. Cet argument est obligatoire si filterformula est spécifiée. Les valeurs suivantes sont acceptées :

- "CELL": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque cellule dans range.

- "ROW": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque ligne dans range.

- "COLUMN": la formule spécifiée dans l'argument filterformula est développée une fois pour chaque colonne dans range.

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

Reportez-vous à la documentation de la méthode ClearAll pour des exemples d'utilisation des arguments filterformula et filterscope.

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

Les fonctions Calc utilisées dans l'argument formula doivent être exprimées en utilisant leurs noms anglais. Visitez la page Wiki Liste des fonctions Calc pour une liste complète des fonctions Calc en anglais.

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

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

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

Selon la valeur de l'argument wholerow, les lignes insérées peuvent soit s'étendre sur la largeur de la plage spécifiée, soit s'étendre sur toutes les colonnes de la ligne.

Cette méthode renvoie une chaîne représentant le nouvel emplacement de la plage initiale.

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.

En fonction de la valeur de l'argument wholecolumn, les colonnes supprimées peuvent soit s'étendre sur la hauteur de la plage spécifiée, soit s'étendre sur toutes les lignes de la colonne.

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.

Selon la valeur de l'argument wholerow, les lignes supprimées peuvent soit s'étendre sur la largeur de la plage spécifiée, soit s'étendre sur toutes les colonnes de la ligne.

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.

En fonction de la valeur de l'argument wholecolumn, les colonnes insérées peuvent soit s'étendre sur la hauteur de la plage spécifiée, soit s'étendre sur toutes les lignes de la colonne.

Cette méthode renvoie une chaîne représentant le nouvel emplacement de la plage initiale.

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

Triez la plage donnée sur n’importe quel nombre de colonnes/lignes. L'ordre de tri peut varier selon la colonne/ligne. Si le nombre de clés de tri est > 3 alors la plage est triée plusieurs fois, par groupes de 3 clés, en commençant par la dernière clé. 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.

sortorder : un scalaire ou une matrice de chaînes contenant les valeurs "ASC" (ascendant), "DESC" (décroissant). Chaque élément est associé à l'élément correspondant dans les sortkeys. Si la matrice sortorder est plus courte 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 : si 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)

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.

Rubriques connexes

Service SFDocuments.Chart

Service SFDocuments.Document

Service ScriptForge.UI

Aidez-nous !