Service SFDocuments.Calc

Contenu
Index 🔎︎

# SFDocuments. Service Calc

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

Some methods are generic for all types of documents and are inherited from the Document service, whereas other methods are specific for the SF_Calc module.

The SF_Calc module is focused on:

- 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

## Invocation du service

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

##### En Basic :

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

        Set oDoc = CreateScriptService("Calc")

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

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

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

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

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

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

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

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

        Set oDoc = oDoc.Dispose()

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

##### En Python

        myDoc = CreateScriptService("Calc")

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

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

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

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 = svcUI.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = svcUI.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 dans une plage (par défaut = la feuille active). Les guillemets simples et les signes $ environnants sont autorisés mais ignorés.

À 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 | Description
CurrentSelection | Non | Auncune | Chaîne ou matrice de chaînes | The single selected range as a string or the list of selected ranges as an array
Height | Oui | RangeName As String | Long | The number of rows (>= 1) in the given range
LastCell | Oui | SheetName As String | String | The last used cell in 'A1' format in the given sheet
LastColumn | Oui | SheetName As String | Long | The last used column in the given sheet
LastRow | Oui | SheetName As String | Long | The last used row in the given sheet
Range | Oui | RangeName As String | Object | A range reference that can be used as argument of methods like CopyToRange
Sheet | Oui | SheetName As String | Object | A sheet reference that can be used as argument of methods like CopySheet
Sheets | Oui | Auncune | Matrice de chaînes | The list with the names of all existing sheets
Width | Oui | RangeName As String | Long | The number of columns (>= 1) in the given range
XCellRange | Oui | RangeName As String | Object | A com.sun.star.Table.XCellRange UNO object
XSpreadsheet | Oui | SheetName As String | Object | A com.sun.star.sheet.XSpreadsheet UNO object

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

## Méthodes

Liste des méthodes dans le service Calc
Activate ClearAll ClearFormats ClearValues CopySheet CopySheetFromFile CopyToCell CopyToRange DAvg DCount | DMax DMin DSum Forms GetColumnName GetFormula GetValue ImportFromCSVFile ImportFromDatabase InsertSheet | MoveRange MoveSheet Offset RemoveSheet RenameSheet SetArray SetValue SetCellStyle SetFormula SortRange

## Activate

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

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

        svcUI = CreateScriptService("UI")
        myDoc = svcUI.GetDocument(svcUI.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.

## ClearAll

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

### Syntaxe :

svc.ClearAll(range: str)

### Paramètres :

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

### Exemple :

##### En Basic :

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

##### En Python

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

## ClearFormats

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

### Syntaxe :

svc.ClearFormats(range: str)

### Paramètres :

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

### Exemple :

##### En Basic :

          oDoc.ClearFormats("SheetX.*")

##### En Python

        myDoc.ClearFormats("SheetX.*")

## ClearValues

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

### Syntaxe :

svc.ClearValues(range: str)

### Paramètres :

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

### Exemple :

##### En Basic :

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

##### En Python

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

## 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 = svcUI.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = svcUI.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 = svcUI.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 = svcUI.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = svcUI.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopyToRange(docA.Range("SheetX.A1:F10"), "SheetY.C5:J5")

## DAvg, DCount, DMax, DMin and DSum

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

### Syntaxe :

svc.DAvg(range: str): float

svc.DCount(range: str): float

svc.DMax(range: str): float

svc.DMin(range: str): float

svc.DSum(range: str): float

### Paramètres :

range : la plage à laquelle la fonction sera appliquée, sous forme de chaîne.

### Exemple :

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

##### En Basic :

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

##### En Python

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

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.

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

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

### Exemple :

##### En Basic :

Affiche une boîte de message avec le nom de la troisième colonne, qui est par défaut "C".

        MsgBox oDoc.GetColumnName(3)

##### En Python

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

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

## GetFormula

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

### Syntaxe :

svc.GetFormula(range: str): any

### Paramètres :

range : la plage à partir de laquelle obtenir les formules, sous forme de chaîne.

### Exemple :

##### En Basic :

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

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

##### En Python

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

## GetValue

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

### Syntaxe :

svc.GetValue(range: str): any

### Paramètres :

range : la plage à partir de laquelle obtenir les valeurs, sous forme de chaîne.

### Exemple :

##### En Basic :

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

##### En Python

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

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, reportez-vous à la page Wiki Options de filtre .

## ImportFromDatabase

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

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

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

### Syntaxe :

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

### Paramètres :

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

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

destinationcell : la destination des données importées, sous forme de chaîne. Si une plage est donnée, seule sa cellule en haut à gauche est prise en compte.

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

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

### Exemple :

##### En Basic :

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

##### En Python

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

## InsertSheet

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

### Syntaxe :

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

### Paramètres :

sheetname : le nom de la nouvelle feuille.

beforesheet : le nom (chaîne) ou l'index (numérique, à partir de 1) de la feuille avant laquelle insérer la nouvelle feuille. Cet argument est facultatif et le comportement par défaut consiste à insérer la feuille à la dernière position.

### Exemple :

L'exemple suivant insère une nouvelle feuille vide nommée « SheetX » et la place avant « SheetY » :

##### En Basic :

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

##### En Python

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

## MoveRange

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

### Syntaxe :

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

### Paramètres :

source : la plage source des cellules, sous forme de chaîne.

destination : la cellule de destination, sous forme de chaîne. Si une plage est donnée, sa cellule en haut à gauche est considérée comme la destination.

### Exemple :

##### En Basic :

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

##### En Python

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

## MoveSheet

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

### Syntaxe :

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

### Paramètres :

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

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

### Exemple :

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

##### En Basic :

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

##### En Python

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

## Offset

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

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

### Syntaxe :

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

### Paramètres :

reference : la plage, sous forme de chaîne, que la méthode utilisera comme référence pour effectuer l'opération de décalage.

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

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

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

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

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

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

### Exemple :

##### En Basic :

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

##### En Python

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

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

## SetValue

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

La méthode renvoie une chaîne représentant la zone modifiée sous forme de plage de cellules.

### Syntaxe :

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

### Paramètres :

targetrange : la plage où stocker la valeur donnée, sous forme de chaîne.

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

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

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

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

### Exemple :

##### En Basic :

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

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

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

##### En Python

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

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

## SetCellStyle

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

La méthode renvoie une chaîne représentant la zone modifiée sous forme de plage de cellules.

### Syntaxe :

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

### Paramètres :

targetrange : la plage à laquelle le style sera appliqué, sous forme de chaîne.

style: le nom du style de cellule à appliquer.

### Exemple :

##### En Basic :

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

##### En Python

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

## SetFormula

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

La méthode renvoie une chaîne représentant la zone modifiée sous forme de plage de cellules.

### Syntaxe :

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

### Paramètres :

targetrange: la plage où insérer les formules, sous forme de chaîne

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

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

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

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

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

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

### Exemple :

##### En Basic :

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

##### En Python

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

## SortRange

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

### Syntaxe :

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

### Paramètres :

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

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

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

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

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

casesensitive : uniquement pour les comparaisons de chaînes. Par défaut = False

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

### Exemple :

##### En Basic :

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

##### En Python

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

Toutes les routines ou identificateurs Basic ScriptForge précédés d'un trait de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans les macros Basic.

Rubriques connexes

SFDocuments.Document service

ScriptForge.UI service