Chapitre 7 Classeurs

StarOffice Basic fournit une interface complète pour la création et l'édition de classeurs commandées par programme. Ce chapitre décrit comment piloter les services, méthodes et propriétés concernés des classeurs.

La première section aborde la structure de base des classeurs et indique comment accéder au contenu de chaque cellule pour l'éditer.

La seconde section, axée sur les zones de cellules et sur les options de recherche et de remplacement du contenu des cellules, explique comment éditer efficacement les classeurs.

---

Remarque –

L'objet Range, qui permet d'accéder à toutes les zones d'une table, a été étendu dans la nouvelle API.

---

Structure des documents basés sur des tables (classeurs)

L'objet Document d'un classeur est basé sur le service com.sun.star.sheet.SpreadsheetDocument. Chaque document de ce type peut comporter plusieurs feuilles de calcul. Dans ce guide, un document basé sur des tables ou classeur désigne le document entier, tandis qu'une feuille de calcul (ou, de façon abrégée, une feuille) est une feuille (table) du document.

---

Remarque –

La terminologie concernant les feuilles de calcul et leur contenu est différente dans VBA et dans StarOffice Basic. Alors que l'objet Document est appelé Workbook dans VBA et les pages qu'il contient Worksheets, ces objets sont respectivement appelés SpreadsheetDocument et Sheet dans StarOffice Basic.

---

Classeurs

Vous pouvez accéder à chaque feuille de calcul d'un classeur via la liste Sheets.

Les exemples qui suivent indiquent comment accéder à une feuille par son numéro ou par son nom.

Exemple 1 : accès par le numéro (la numérotation commence à 0)

Dim Doc As Object
Dim Sheet As Object

Doc = StarDesktop.CurrentComponent
Sheet  = Doc. Sheets (0)

Exemple 2 : accès par le nom

Dim Doc As Object
Dim Sheet As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets.getByName("Sheet 1")

Dans le premier exemple, on accède à la feuille par son numéro (la numérotation commençant à 0). Dans le second, on y accède par son nom et par la méthode getByName.

L'objet Sheet obtenu par la méthode getByName prend en charge le service com.sun.star.sheet.Spreadsheet. Outre les différentes interfaces qu'il propose pour l'édition du contenu, ce service fournit les propriétés suivantes :

• IsVisible (Boolean) : la feuille est visible.

• PageStyle (String) : nom du modèle de page de la feuille.

Création, suppression et attribution de nom à des feuilles

La liste Sheets d'un classeur permet également de créer, de supprimer et de renommer des feuilles individuelles. L'exemple ci-dessous utilise la méthode hasByName pour vérifier si une feuille nommée MySheet existe. Si c'est le cas, la méthode détermine une référence d'objet correspondante à l'aide de la méthode getByName, puis enregistre cette référence dans une variable de Sheet. Si la feuille correspondante n'existe pas, elle est créée par l'appel createInstance et insérée dans le classeur par la méthode insertByName.

Dim Doc As Object
Dim Sheet As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

If Doc.Sheets.hasByName("MySheet") Then
   Sheet = Doc.Sheets.getByName("MySheet")
Else
   Sheet = Doc.createInstance("com.sun.star.sheet.Spreadsheet")
   Doc.Sheets.insertByName("MySheet", Sheet)
End If

Les méthodes getByName et insertByName proviennent de l'interface com.sun.star.container.XnameContainer, dont vous trouverez une description dans le Chapitre 4, Introduction à l'API StarOffice.

Lignes et colonnes

Chaque feuille contient une liste de ses propres lignes et colonnes. Ces listes sont disponibles via les propriétés Rows et Columns de l'objet Spreadsheet et prennent en charge les services com.sun.star.table.TableColumns et/ou com.sun.star.table.TableRows.

L'exemple suivant crée deux objets qui renvoient à la première ligne et à la première colonne d'une feuille, et stocke les références dans les variables d'objets FirstCol et FirstRow.

Dim Doc As Object
Dim Sheet As Object
Dim FirstRow As Object
Dim FirstCol As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

FirstCol = Sheet.Columns(0)
FirstRow = Sheet.Rows(0)

Les objets Column prennent en charge le service com.sun.star.table.TableColumn, dont les propriétés sont les suivantes :

• Width (long) : largeur d'une colonne en centièmes de millimètre.

• OptimalWidth (Boolean) : définit la largeur optimale d'une colonne.

• IsVisible (Boolean) : affiche une colonne.

• IsStartOfNewPage (Boolean) : insère un saut de page avant une colonne lors de l'impression.

Pour obtenir une largeur de colonne optimale, la propriété OptimalWidth doit être définie sur True. Il est possible de modifier la largeur d'une cellule individuelle sans modifier la largeur de la colonne qui la contient. Sur un plan pratique, OptimalWidth est davantage une méthode qu'une propriété.

Les objets Row sont basés sur le service com.sun.star.table.RowColumn, dont les propriétés sont les suivantes :

• Height (long) : hauteur de la ligne en centièmes de millimètre.

• OptimalHeight (Boolean) : définit la hauteur optimale de la ligne.

• IsVisible (Boolean) : affiche une ligne.

• IsStartOfNewPage (Boolean) : insère un saut de page avant une ligne lors de l'impression.

Si la propriété OptimalHeight d'une ligne est définie sur True, sa hauteur change automatiquement lorsque celle d'une cellule qu'elle contient est modifiée. L'optimisation automatique se poursuit jusqu'à ce qu'une hauteur absolue soit assignée à la ligne par la propriété Height.

L'exemple suivant active l'optimisation automatique de la hauteur de ligne pour les cinq premières lignes de la feuille et rend la deuxième colonne invisible.

Dim Doc As Object
Dim Sheet As Object
Dim Row As Object
Dim Col As Object
Dim I As Integer

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

For I = 0 To 4
   Row = Sheet.Rows(I)
   Row.OptimalHeight = True
Next I

Col = Sheet.Columns(1)
Col.IsVisible = False

---

Remarque –

Vous pouvez accéder aux listes Rows et Columns via un index dans StarOffice Basic. Contrairement à VBA, l'index de la première colonne est 0 (et non 1).

---

Insertion et suppression de lignes et de colonnes

Les objets Rows et Columns d'une feuille peuvent accéder à des lignes et colonnes existantes, mais également en insérer et en supprimer.

Dim Doc As Object
Dim Sheet As Object
Dim NewColumn As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

Sheet.Columns.insertByIndex(3, 1)
Sheet.Columns.removeByIndex(5, 1)

Cet exemple utilise la méthode insertByIndex pour insérer une nouvelle colonne à l'emplacement de la quatrième colonne dans la feuille (index 3, la numérotation commençant à 0). Le second paramètre spécifie le nombre de colonnes à insérer (dans cet exemple, une).

La méthode removeByIndex supprime la sixième colonne (index 5). Là aussi, le second paramètre spécifie le nombre de colonnes à supprimer.

Les méthodes d'insertion et de suppression de lignes utilisent la fonction de l'objet Rows de la même manière que les méthodes d'édition des colonnes utilisent l'objet Columns.

Cellules

Une feuille de calcul est constituée d'une liste de cellules à deux dimensions. Chaque cellule est définie par ses positions X et Y par rapport à la cellule supérieure gauche, dont la position est (0,0).

L'exemple suivant crée un objet qui renvoie à la cellule supérieure gauche et insère du texte dans cette cellule :

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

Cell = Sheet.getCellByPosition(0, 0)
Cell.String = "Test"

Outre ses coordonnées numériques, chaque cellule d'une feuille porte un nom : par exemple, la cellule supérieure gauche (0,0) d'une feuille est nommée A1. La lettre A représente la colonne et le chiffre 1 la ligne. Il convient de ne pas confondre le nom et la position d'une cellule, car le comptage des lignes commence à 1 pour les noms et à 0 pour les positions.

Dans StarOffice, une cellule peut être vide, ou bien contenir du texte, des nombres ou des formules. Le type de cellule n'est pas déterminé par le contenu qui y est enregistré, mais par la propriété de l'objet utilisé pour son entrée. Les nombres peuvent être insérés et appelés à l'aide de la propriété Value, le texte à l'aide de la propriété String et les formules à l'aide de la propriété Formula.

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

Cell = Sheet.getCellByPosition(0, 0)
Cell.Value = 100

Cell = Sheet.getCellByPosition(0, 1)
Cell.String = "Test"

Cell = Sheet.getCellByPosition(0, 2)
Cell.Formula = "=A1"

Cet exemple insère un nombre, du texte et une formule dans les champs A1, A2 et A3.

---

Remarque –

Les propriétés Value, String et Formula remplacent la méthode PutCell pour la définition des valeurs d'une cellule de tableau.

---

StarOffice utilise la propriété String comme du texte pour traiter le contenu saisi dans les cellules, même si ce contenu est un nombre. Les nombres sont alignés à gauche dans la cellule et non pas à droite. Lors de l'utilisation de formules, il convient également de différencier le texte et les nombres :

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

Cell = Sheet.getCellByPosition(0, 0)
Cell.Value = 100

Cell = Sheet.getCellByPosition(0, 1)
Cell.String = 1000

Cell = Sheet.getCellByPosition(0, 2)
Cell.Formula = "=A1+A2"

MsgBox Cell.Value 

Bien que la cellule A1 contienne la valeur 100 et la cellule A2 la valeur 1 000, la formule A1+A2 renvoie la valeur 100. En effet, le contenu de la cellule A2 a été saisi comme une chaîne et non comme un nombre.

Pour savoir si une cellule contient un nombre ou une chaîne, utilisez la propriété Type :

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
Cell = Sheet.getCellByPosition(1,1)

Cell.Value = 1000

Select Case Cell.Type
Case com.sun.star.table.CellContentType.EMPTY
   MsgBox "Content: Empty"
Case com.sun.star.table.CellContentType.VALUE
   MsgBox "Content: Value"
Case com.sun.star.table.CellContentType.TEXT
   MsgBox "Content: Text"
Case com.sun.star.table.CellContentType.FORMULA
   MsgBox "Content: Formula"
End Select

La propriété Cell.Type renvoie une valeur pour l'énumération com.sun.star.table.CellContentType qui identifie le type de contenu d'une cellule. Les valeurs possibles sont les suivantes :

• EMPTY : aucune valeur.

• VALUE : nombre.

• TEXT : chaîne.

• FORMULA : formule.

Insertion, suppression, copie et déplacement de cellules

Outre la modification directe du contenu d'une cellule, StarOffice Calc offre également une interface permettant d'insérer, de supprimer, de copier ou de fusionner des cellules. L'interface com.sun.star.sheet.XRangeMovement, accessible par l'objet Spreadsheet, fournit quatre méthodes de modification du contenu des cellules.

La méthode insertCell sert à insérer des cellules dans une feuille.

Dim Doc As Object
Dim Sheet As Object
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

CellRangeAddress.Sheet = 0
CellRangeAddress.StartColumn = 1
CellRangeAddress.StartRow = 1
CellRangeAddress.EndColumn = 2
CellRangeAddress.EndRow = 2

Sheet.insertCells(CellRangeAddress, com.sun.star.sheet.CellInsertMode.DOWN)

Cet exemple insère une plage de cellules comportant deux lignes sur deux colonnes dans la deuxième colonne et la deuxième ligne (portant toutes deux le numéro 1) de la première feuille (numéro 0) du classeur. Toutes les valeurs existantes de la plage de cellules spécifiée sont déplacées sous cette dernière.

Pour définir la plage de cellules à insérer, utilisez la structure com.sun.star.table.CellRangeAddress. Cette structure comporte les valeurs suivantes :

• Sheet (short) : numéro de la feuille (la numérotation commençant à 0).

• StartColumn (long) : première colonne de la plage de cellules (la numérotation commençant à 0).

• StartRow (long) : première ligne de la plage de cellules (la numérotation commençant à 0).

• EndColumn (long) : dernière colonne de la plage de cellules (la numérotation commençant à 0).

• EndRow (long) : dernière ligne de la plage de cellules (la numérotation commençant à 0).

La structure CellRangeAddress complétée doit être passée comme premier paramètre à la méthode insertCells. Le second paramètre de insertCells contient une valeur de l'énumération com.sun.star.sheet.CellInsertMode et définit le traitement réservé aux valeurs situées devant la position d'insertion. L'énumération CellInsertMode reconnaît les valeurs suivantes :

• NONE : les valeurs actives conservent leur position actuelle.

• DOWN : les cellules situées au niveau de la position d'insertion et en dessous sont déplacées vers le bas.

• RIGHT : les cellules situées au niveau de la position d'insertion et à droite sont déplacées vers la droite.

• ROWS : les lignes après la position d'insertion sont déplacées vers le bas.

• COLUMNS : les colonnes après la position d'insertion sont déplacées vers la droite.

La méthode removeRange est l'équivalent de la méthode insertCells. Cette méthode supprime de la feuille la plage de cellules définie dans la structure CellRangeAddress.

Dim Doc As Object
Dim Sheet As Object
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

CellRangeAddress.Sheet = 0
CellRangeAddress.StartColumn = 1
CellRangeAddress.StartRow = 1
CellRangeAddress.EndColumn = 2
CellRangeAddress.EndRow = 2

Sheet.removeRange(CellRangeAddress, com.sun.star.sheet.CellDeleteMode.UP)

Cet exemple supprime la plage de cellules B2:C3 de la feuille et déplace de deux colonnes vers le haut les cellules situées en dessous. Ce type de suppression est défini par l'une des valeurs suivantes provenant de l'énumération com.sun.star.sheet.CellDeleteMode :

• NONE : les valeurs actives conservent leur position actuelle.

• UP : les cellules situées au niveau de la position d'insertion et en dessous sont déplacées vers le haut.

• LEFT : les cellules situées au niveau de la position d'insertion et à droite sont déplacées vers la gauche.

• ROWS : les lignes après la position d'insertion sont déplacées vers le haut.

• COLUMNS : les colonnes après la position d'insertion sont déplacées vers la gauche.

L'interface XRangeMovement comporte deux méthodes supplémentaires pour déplacer (moveRange) ou copier (copyRange) les plages de cellules. L'exemple suivant déplace la plage B2:C3 de façon à ce qu'elle commence à la position A6 :

Dim Doc As Object
Dim Sheet As Object
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress
Dim CellAddress As New com.sun.star.table.CellAddress

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

CellRangeAddress.Sheet = 0
CellRangeAddress.StartColumn = 1
CellRangeAddress.StartRow = 1
CellRangeAddress.EndColumn = 2
CellRangeAddress.EndRow = 2

CellAddress.Sheet = 0
CellAddress.Column = 0
CellAddress.Row = 5

Sheet.moveRange(CellAddress, CellRangeAddress)

Outre la structure CellRangeAdress, la méthode moveRange attend une structure com.sun.star.table.CellAddress pour définir l'origine de la zone de destination du déplacement. La méthode CellAddress fournit les valeurs suivantes :

• Sheet (short) : numéro de la feuille (la numérotation commençant à 0).

• Column (long) : numéro de la colonne concernée (la numérotation commençant à 0).

• Row (long) : numéro de la ligne concernée (la numérotation commençant à 0).

Le contenu des cellules de la plage cible est toujours écrasé par la méthode moveRange. Contrairement à la méthode InsertCells, la méthode removeRange ne fournit pas de paramètre permettant des déplacements automatiques.

Les fonctions de la méthode copyRange sont identiques à celles de la méthode moveRange, si ce n'est que copyRange insère une copie de la plage de cellules au lieu de la déplacer.

---

Remarque –

Du point de vue de leur fonction, les méthodes insertCell, removeRange et copyRange de StarOffice Basic sont comparables aux méthodes Range.Insert, Range.Delete et Range.Copy de VBA. Les méthodes sont toutefois appliquées à l'objet Range correspondant dans VBA, tandis que dans StarOffice Basic, elles sont appliquées à l'objet Sheet associé.

---

Formatage

Un classeur fournit des propriétés et des méthodes de formatage des cellules et des pages.

Propriétés de cellules

Il existe de nombreuses options de formatage des cellules, telles que la spécification du type de police et de la taille du texte. Chaque cellule prend en charge les services com.sun.star.style.CharacterProperties et com.sun.star.style.ParagraphProperties, dont les principales propriétés sont décrites au Chapitre 6, Documents texte. Le formatage spécial des cellules est traité par le service com.sun.star.table.CellProperties. Les principales propriétés de ce service sont décrites dans les sections qui suivent.

Vous pouvez appliquer toutes les propriétés nommées à des cellules individuelles et à des plages de cellules.

---

Remarque –

L'objet CellProperties de l'API StarOffice est comparable à l'objet Interior de VBA, qui définit également les propriétés propres aux cellules.

---

Couleur d'arrière-plan et ombres

Le service com.sun.star.table.CellProperties fournit les propriétés suivantes pour la définition des couleurs d'arrière-plan et des ombres :

• CellBackColor (Long) : couleur d'arrière-plan de la cellule du tableau.

• IsCellBackgroundTransparent (Boolean) : définit une couleur d'arrière-plan transparente.

• ShadowFormat (struct) : spécifie l'ombre à appliquer aux cellules (structure correspondant à com.sun.star.table.ShadowFormat).

La structure com.sun.star.table.ShadowFormat et les spécifications détaillées des ombres de cellule ont la structure suivante :

• Location (enum) : position de l'ombre (valeur provenant de la structure com.sun.star.table.ShadowLocation).

• ShadowWidth (Short) : taille de l'ombre en centièmes de millimètre.

• IsTransparent (Boolean) : définit une ombre transparente.

• Color (Long) : couleur de l'ombre.

L'exemple suivant inscrit le nombre 1 000 dans la cellule B2, applique la couleur rouge à l'arrière-plan à l'aide de la propriété CellBackColor, puis crée une ombre gris clair pour la cellule, qui est déplacée de 1 mm vers la gauche et vers le bas.

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object
Dim ShadowFormat As New com.sun.star.table.ShadowFormat

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
Cell = Sheet.getCellByPosition(1,1)

Cell.Value = 1000

Cell.CellBackColor = RGB(255, 0, 0)

ShadowFormat.Location = com.sun.star.table.ShadowLocation.BOTTOM_RIGHT
ShadowFormat.ShadowWidth = 100
ShadowFormat.Color = RGB(160, 160, 160)

Cell.ShadowFormat = ShadowFormat

Justification

StarOffice fournit diverses fonctions permettant de modifier la justification d'un texte dans une cellule de tableau.

Les propriétés suivantes définissent la justification horizontale et verticale d'un texte :

• HoriJustify (enum) : justification horizontale du texte (valeur provenant de com.sun.star.table.CellHoriJustify).

• VertJustify (enum) : justification verticale du texte (valeur provenant de com.sun.star.table.CellVertJustify).

• Orientation (enum) : orientation du texte (valeur correspondant à com.sun.star.table.CellOrientation).

• IsTextWrapped (Boolean) : autorise les retours à la ligne automatiques à l'intérieur de la cellule.

• RotateAngle (Long) : angle de rotation du texte en centièmes de degré.

L'exemple suivant indique comment empiler le contenu d'une cellule pour que chaque caractère s'imprime l'un en dessous de l'autre dans le coin supérieur gauche de la cellule. Les caractères ne subissent aucune rotation.

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
Cell = Sheet.getCellByPosition(1,1)

Cell.Value = 1000

Cell.HoriJustify = com.sun.star.table.CellHoriJustify.LEFT
Cell.VertJustify = com.sun.star.table.CellVertJustify.TOP
Cell.Orientation = com.sun.star.table.CellOrientation.STACKED

Formats de nombre, de date et de texte

StarOffice propose plusieurs formats de date et d'heure prédéfinis. Chacun de ces formats comporte un numéro de série utilisé pour assigner le format correspondant aux cellules à l'aide de la propriété NumberFormat. StarOffice fournit les méthodes queryKey et addNew qui permettent d'accéder à des formats numériques existants et de créer ses propres formats numériques. Ces méthodes sont accessibles par l'appel d'objet suivant :

NumberFormats = Doc.NumberFormats

Un format se spécifie à l'aide d'une chaîne de format structurée de la même façon que la fonction de format de StarOffice Basic. Il existe toutefois une différence importante : alors que le format de commande requiert des abréviations, symboles décimaux et caractères séparateurs de milliers anglais, les abréviations propres au pays doivent être utilisées dans la structure d'un format de commande pour l'objet NumberFormats.

L'exemple suivant formate la cellule B2 pour que les nombres s'affichent avec trois décimales et qu'ils utilisent les virgules comme séparateurs de milliers.

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object
Dim NumberFormats As Object
Dim NumberFormatString As String
Dim NumberFormatId As Long
Dim LocalSettings As New com.sun.star.lang.Locale

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
Cell = Sheet.getCellByPosition(1,1)

Cell.Value = 23400.3523565

LocalSettings.Language = "en"
LocalSettings.Country = "us"

NumberFormats = Doc.NumberFormats
NumberFormatString = "#,##0.000"

NumberFormatId = NumberFormats.queryKey(NumberFormatString, LocalSettings, True)
If NumberFormatId = -1 Then
   NumberFormatId = NumberFormats.addNew(NumberFormatString, LocalSettings)
End If

MsgBox NumberFormatId
Cell.NumberFormat = NumberFormatId

La boîte de dialogue Formatage des cellules de StarOffice présente un aperçu des différentes options de formatage des cellules.

Propriétés de page

Les propriétés de page sont des options de formatage permettant de positionner le contenu d'un document sur une page, ainsi que des éléments visuels qui se répètent d'une page à l'autre. Il s'agit notamment des éléments suivants :

• formats de papier ;

• marges ;

• en-têtes et pieds de page.

La procédure de définition des formats de page diffère des autres formes de formatage. En effet, alors que les formats de cellules, de paragraphes et de caractères peuvent être appliqués directement, les formats de page peuvent également être définis et appliqués indirectement à l'aide des styles de page. Par exemple, les en-têtes ou les pieds de page sont ajoutés au style de page.

Les sections qui suivent décrivent les principales options de formatage des pages de feuilles de calcul. La plupart des styles décrits peuvent également être appliqués aux documents texte. Les propriétés de page valides pour les deux types de documents sont définies dans le service com.sun.star.style.PageProperties. Les propriétés de page qui ne s'appliquent qu'aux classeurs sont définies dans le service com.sun.star.sheet.TablePageStyle.

---

Remarque –

Les propriétés de page (marges, bordures, etc.) d'un document Microsoft Office sont définies par un objet PageSetup au niveau de l'objet Worksheet (Excel) ou Document (Word). Dans StarOffice, ces propriétés sont définies à l'aide d'un style de page lié au document associé.

---

Arrière-plan de page

Le service com.sun.star.style.PageProperties définit les propriétés d'arrière-plan de page suivantes :

• BackColor (long) : couleur d'arrière-plan.

• BackGraphicURL (String) : URL de l'image d'arrière-plan à utiliser.

• BackGraphicFilter (String) : nom du filtre d'interprétation de l'image d'arrière-plan.

• BackGraphicLocation (Enum) : position de l'image d'arrière-plan (valeur correspondant à l'énumération)

• BackTransparent (Boolean) : rend l'arrière-plan transparent.

Format de page

Le format de page est défini à l'aide des propriétés suivantes du service com.sun.star.style.PageProperties :

• IsLandscape (Boolean) : format paysage.

• Width (long) : largeur de page en centièmes de millimètre.

• Height (long) : hauteur de page en centièmes de millimètre.

• PrinterPaperTray (String) : nom du bac d'alimentation d'imprimante à utiliser.

L'exemple suivant règle la taille de page du style de page par défaut (Default) sur le format paysage DIN A5 (hauteur 14,8 cm, largeur 21 cm) :

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object
Dim PageStyles As Object
Dim DefPage As Object

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
PageStyles = StyleFamilies.getByName("PageStyles")
DefPage = PageStyles.getByName("Default")

DefPage.IsLandscape = True
DefPage.Width = 21000
DefPage.Height = 14800

Marge, bordure et ombre

Le service com.sun.star.style.PageProperties fournit les propriétés suivantes pour l'ajustement des marges, des bordures et des ombres :

• LeftMargin (long) : largeur de la marge gauche en centièmes de millimètre.

• RightMargin (long) : largeur de la marge droite en centièmes de millimètre

• TopMargin (long) : largeur de la marge supérieure en centièmes de millimètre.

• BottomMargin (long) : largeur de la marge inférieure en centièmes de millimètre.

• LeftBorder (struct) : spécifications de la bordure de page gauche (structure com.sun.star.table.BorderLine).

• RightBorder (struct) : spécifications de la bordure de page droite (structure com.sun.star.table.BorderLine).

• TopBorder (struct) : spécifications de la bordure de page supérieure (structure com.sun.star.table.BorderLine).

• BottomBorder (struct) : spécifications de la bordure de page inférieure (structure com.sun.star.table.BorderLine).

• LeftBorderDistance (long) : distance entre la bordure gauche de la page et le contenu de la page, exprimée en centièmes de millimètre.

• RightBorderDistance (long) : distance entre la bordure droite de la page et le contenu de la page, exprimée en centièmes de millimètre.

• TopBorderDistance (long) : distance entre la bordure supérieure de la page et le contenu de la page, exprimée en centièmes de millimètre.

• BottomBorderDistance (long) : distance entre la bordure inférieure de la page et le contenu de la page, exprimée en centièmes de millimètre.

• ShadowFormat (struct) : spécifications de l'ombre de la zone de contenu de la page (structure com.sun.star.table.ShadowFormat).

L'exemple suivant définit les bordures gauche et droite du style de page par défaut (Default) à 1 centimètre.

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object
Dim PageStyles As Object
Dim DefPage As Object

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
PageStyles = StyleFamilies.getByName("PageStyles")
DefPage = PageStyles.getByName("Default")

DefPage.LeftMargin = 1000
DefPage.RightMargin = 1000

En-têtes et pieds de page

Les en-têtes et pieds de page d'un document font partie des propriétés de la page et sont définis à l'aide du service com.sun.star.style.PageProperties. Les propriétés de formatage des en-têtes sont les suivantes :

• HeaderIsOn (Boolean) : l'en-tête est activé.

• HeaderLeftMargin (long) : distance entre l'en-tête et la marge gauche en centièmes de millimètre.

• HeaderRightMargin (long) : distance entre l'en-tête et la marge droite en centièmes de millimètre.

• HeaderBodyDistance (long) : distance entre l'en-tête et le corps du document en centièmes de millimètre.

• HeaderHeight (long) : hauteur de l'en-tête en centièmes de millimètre.

• HeaderIsDynamicHeight (Boolean) : la hauteur de l'en-tête s'adapte automatiquement au contenu.

• HeaderLeftBorder (struct) : détails de la bordure gauche du cadre entourant l'en-tête (structure com.sun.star.table.BorderLine).

• HeaderRightBorder (struct) : détails de la bordure droite du cadre entourant l'en-tête (structure com.sun.star.table.BorderLine).

• HeaderTopBorder (struct) : détails de la bordure supérieure entourant l'en-tête (structure com.sun.star.table.BorderLine).

• HeaderBottomBorder (struct) : détails de la bordure inférieure entourant l'en-tête (structure com.sun.star.table.BorderLine).

• HeaderLeftBorderDistance (long) : distance entre la bordure gauche et le contenu de l'en-tête en centièmes de millimètre.

• HeaderRightBorderDistance (long) : distance entre la bordure droite et le contenu de l'en-tête en centièmes de millimètre.

• HeaderTopBorderDistance (long) : distance entre la bordure supérieure et le contenu de l'en-tête en centièmes de millimètre.

• HeaderBottomBorderDistance (long) : distance entre la bordure inférieure et le contenu de l'en-tête en centièmes de millimètre.

• HeaderIsShared (Boolean) : le contenu des en-têtes de pages paires et impaires est identique (voir HeaderText, HeaderTextLeft et HeaderTextRight).

• HeaderBackColor (long) : couleur d'arrière-plan de l'en-tête.

• HeaderBackGraphicURL (String) : URL de l'image d'arrière-plan à utiliser.

• HeaderBackGraphicFilter (String) : nom du filtre d'interprétation de l'image d'arrière-plan pour l'en-tête.

• HeaderBackGraphicLocation (Enum) : position de l'image d'arrière-plan pour l'en-tête (valeur correspondant à l'énumération com.sun.star.style.GraphicLocation).

• HeaderBackTransparent (Boolean) : l'arrière-plan de l'en-tête est transparent.

• HeaderShadowFormat (struct) : détails de l'ombre de l'en-tête (structure com.sun.star.table.ShadowFormat).

Les propriétés de formatage des pieds de page sont les suivantes :

• FooterIsOn (Boolean) : indique que le pied de page est activé.

• FooterLeftMargin (long) : distance entre le pied de page et la marge gauche en centièmes de millimètre.

• FooterRightMargin (long) : distance entre le pied de page et la marge droite en centièmes de millimètre.

• FooterBodyDistance (long) : distance entre le pied de page et le corps du document en centièmes de millimètre.

• FooterHeight (long) : hauteur du pied de page en centièmes de millimètre.

• FooterIsDynamicHeight (Boolean) : la hauteur du pied de page s'adapte automatiquement au contenu.

• FooterLeftBorder (struct) : détails de la bordure gauche entourant le pied de page (structure com.sun.star.table.BorderLine).

• FooterRightBorder (struct) : détails de la bordure droite entourant le pied de page (structure com.sun.star.table.BorderLine).

• FooterTopBorder (struct) : détails de la bordure supérieure entourant le pied de page (structure com.sun.star.table.BorderLine).

• FooterBottomBorder (struct) : détails de la bordure inférieure entourant le pied de page (structure com.sun.star.table.BorderLine).

• FooterLeftBorderDistance (long) : distance entre la bordure gauche et le contenu du pied de page en centièmes de millimètre.

• FooterRightBorderDistance (long) : distance entre la bordure droite et le contenu du pied de page, exprimée en centièmes de millimètre.

• FooterTopBorderDistance (long) : distance entre la bordure supérieure et le contenu du pied de page, exprimée en centièmes de millimètre.

• FooterBottomBorderDistance (long) : distance entre la bordure inférieure et le contenu du pied de page, exprimée en centièmes de millimètre.

• FooterIsShared (Boolean) : le contenu des pieds de page des pages paires et impaires est identique (voir FooterText, FooterTextLeft et FooterTextRight).

• FooterBackColor (long) : couleur d'arrière-plan du pied de page.

• FooterBackGraphicURL (String) : URL de l'image d'arrière-plan à utiliser.

• FooterBackGraphicFilter (String) : nom du filtre d'interprétation de l'image d'arrière-plan pour le pied de page.

• FooterBackGraphicLocation (Enum) : position de l'image d'arrière-plan pour le pied de page (valeur correspondant à l'énumération com.sun.star.style.GraphicLocation).

• FooterBackTransparent (Boolean)  : l'arrière-plan du pied de page est transparent.

• FooterShadowFormat (struct) : détails de l'ombre du pied de page (structure com.sun.star.table.ShadowFormat).

Modification du texte des en-têtes et pieds de pages

Le contenu des en-têtes et pieds de pages d'un classeur est accessible via les propriétés suivantes :

• LeftPageHeaderContent (Object) : contenu des en-têtes des pages paires (service com.sun.star.sheet.HeaderFooterContent).

• RightPageHeaderContent (Object) : contenu des en-têtes des pages impaires (service com.sun.star.sheet.HeaderFooterContent).

• LeftPageFooterContent (Object) : contenu des pieds des pages paires (service com.sun.star.sheet.HeaderFooterContent).

• RightPageFooterContent (Object) : contenu des pieds des pages impaires (service com.sun.star.sheet.HeaderFooterContent).

Si vous n'avez pas besoin de faire la distinction entre pages paires et impaires dans les en-têtes ou les pieds de page (la valeur de la propriété FooterIsShared est False), définissez les propriétés des en-têtes et des pieds de page sur les pages impaires.

Tous les objets nommés renvoient un objet prenant en charge le service com.sun.star.sheet.HeaderFooterContent. À l'aide des propriétés non authentiques LeftText, CenterText et RightText, ce service fournit trois éléments de texte aux en-têtes et pieds de page de StarOffice Calc.

L'exemple ci-dessous écrit la valeur "Just a Test" (ceci est un test) dans le champ texte situé à gauche de l'en-tête à partir du modèle Default.

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object
Dim PageStyles As Object
Dim DefPage As Object
Dim HText As Object
Dim HContent As Object
Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
PageStyles = StyleFamilies.getByName("PageStyles")
DefPage = PageStyles.getByName("Default")

DefPage.HeaderIsOn = True
HContent = DefPage.RightPageHeaderContent
HText = HContent.LeftText
HText.String = "Just a Test."
DefPage.RightPageHeaderContent = HContent

Notez bien la dernière ligne de l'exemple : une fois le texte modifié, l'objet TextContent doit être de nouveau assigné à l'en-tête pour que la modification prenne effet.

Un autre mécanisme de modification du texte des en-têtes et pieds de page existe pour les documents texte (StarOffice Writer), car ceux-ci sont constitués d'un bloc de texte unique. Les propriétés suivantes sont définies dans le service com.sun.star.style.PageProperties :

• HeaderText (Object) : objet Text comprenant le contenu de l'en-tête (service com.sun.star.text.XText).

• HeaderTextLeft (Object) : objet Text comprenant le contenu des en-têtes des pages de gauche (service com.sun.star.text.XText).

• HeaderTextRight (Object) : objet Text comprenant le contenu des en-têtes des pages de droite (service com.sun.star.text.XText).

• FooterText (Object) : objet Text comprenant le contenu du pied de page (service com.sun.star.text.XText).

• FooterTextLeft (Object) : objet Text comprenant le contenu des pieds des pages de gauche (service com.sun.star.text.XText).

• FooterTextRight (Object) : objet Text comprenant le contenu des pieds des pages de droite (servicecom.sun.star.text.XText).

L'exemple suivant crée un en-tête dans le style de page par défaut (Default) des documents texte et ajoute le texte "Just a Test" (ceci est un test) à cet en-tête.

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object
Dim PageStyles As Object
Dim DefPage As Object
Dim HText As Object

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
PageStyles = StyleFamilies.getByName("PageStyles")
DefPage = PageStyles.getByName("Default")

DefPage.HeaderIsOn = True
HText = DefPage.HeaderText

HText.String = "Just a Test."

Dans cet exemple, l'accès est fourni directement par la propriété HeaderText du style de page, plutôt que par l'objet HeaderFooterContent.

Centrage (feuilles de calcul uniquement)

Le service com.sun.star.sheet.TablePageStyle, utilisé uniquement dans les styles de page de StarOffice Calc, permet de centrer sur la page les plages de cellules que vous souhaitez imprimer. Ce service fournit les propriétés suivantes :

• CenterHorizontally (Boolean) : le contenu du tableau est centré horizontalement.

• CenterVertically (Boolean) : le contenu du tableau est centré verticalement.

Définition des éléments à imprimer (feuilles de calcul uniquement)

Lorsque vous formatez des feuilles, vous pouvez définir si les éléments de la page doivent être visibles ou non. Pour cela, le service com.sun.star.sheet.TablePageStyle propose les propriétés suivantes :

• PrintAnnotations (Boolean) : imprime les commentaires des cellules.

• PrintGrid (Boolean) : imprime les lignes de la grille.

• PrintHeaders (Boolean) : imprime les en-têtes de ligne et de colonne.

• PrintCharts (Boolean) : imprime les diagrammes contenus dans une feuille.

• PrintObjects (Boolean) : imprime les objets incorporés.

• PrintDrawing (Boolean) : imprime les objets de dessin.

• PrintDownFirst (Boolean) : si le contenu d'une feuille s'étend sur plusieurs pages, les cellules sont d'abord imprimées verticalement du haut vers le bas, puis de gauche à droite.

• PrintFormulas (Boolean) : imprime les formules à la place des valeurs calculées.

• PrintZeroValues (Boolean) : imprime les valeurs zéro.

Édition efficace des classeurs

Alors que la section précédente décrivait la structure principale des classeurs, la présente section est consacrée aux services permettant d'accéder facilement à des cellules individuelles ou à des plages de cellules.

Plages de cellules

En plus de l'objet destiné aux cellules individuelles (voir le service com.sun.star.table.Cell), StarOffice propose également des objets représentant des plages de cellules. Les objets tels que CellRange sont créés avec l'appel getCellRangeByName de l'objet Spreadsheet :

Dim Doc As Object
Dim Sheet As Object
Dim CellRange As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets.getByName("Sheet 1")
CellRange = Sheet.getCellRangeByName("A1:C15")

Le signe deux-points (:) sert à spécifier une plage de cellules dans une feuille de calcul. Par exemple, A1:C15 représente toutes les cellules des lignes 1 à 15 et des colonnes A, B et C.

L'emplacement des cellules individuelles dans une plage de cellules peut être déterminé avec la méthode getCellByPosition, où les coordonnées de la cellule supérieure gauche de la plage sont (0, 0). L'exemple suivant utilise cette méthode pour créer un objet à partir de la cellule C3.

Dim Doc As Object
Dim Sheet As Object
Dim CellRange As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets.getByName("Sheet 1")
CellRange = Sheet.getCellRangeByName("B2:D4")
Cell = CellRange.GetCellByPosition(1, 1)

Formatage de plages de cellules

Tout comme pour les cellules individuelles, vous pouvez appliquer un formatage à des plages de cellules en utilisant le service com.sun.star.table.CellProperties. Pour plus d'informations et d'autres exemples de ce service, reportez-vous à la section Formatage.

Calculs avec des plages de cellules

Vous pouvez utiliser la méthode computeFunction pour effectuer des opérations mathématiques sur des plages de cellules. La méthode computeFunction attend une constante comme paramètre de description de la fonction mathématique à utiliser. Les constantes associées sont définies dans l'énumération com.sun.star.sheet.GeneralFunction. Les valeurs disponibles sont les suivantes :

• SUM : somme de toutes les valeurs numériques.

• COUNT : nombre total de valeurs (y compris les valeurs non numériques).

• COUNTNUMS : nombre total de valeurs numériques.

• AVERAGE : moyenne de toutes les valeurs numériques.

• MAX : valeur numérique la plus élevée.

• MIN : valeur numérique la plus basse.

• PRODUCT : produit de toutes les valeurs numériques.

• STDEV : écart type.

• VAR : variance.

• STDEVP : écart type calculé sur la base de la population totale.

• VARP : variance calculée sur la base de la population totale.

L'exemple suivant calcule la valeur moyenne de la plage A1:C3 et affiche le résultat dans une boîte de message :

Dim Doc As Object
Dim Sheet As Object
Dim CellRange As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets.getByName("Sheet 1")
CellRange = Sheet.getCellRangeByName("A1:C3")

MsgBox CellRange.computeFunction(com.sun.star.sheet.GeneralFunction.AVERAGE)

Suppression du contenu des cellules

La méthode clearContents simplifie le processus de suppression du contenu des cellules ou des plages de cellules, car elle permet de supprimer un type de contenu particulier d'une plage de cellules.

L'exemple suivant supprime toutes les chaînes et les informations de formatage direct de la plage B2:C3.

Dim Doc As Object
Dim Sheet As Object
Dim CellRange As Object
Dim Flags As Long

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
CellRange = Sheet.getCellRangeByName("B2:C3")

Flags = com.sun.star.sheet.CellFlags.STRING + _
      com.sun.star.sheet.CellFlags.HARDATTR

CellRange.clearContents(Flags)

Les drapeaux spécifiés dans clearContents proviennent de la liste de constantes com.sun.star.sheet.CellFlags. Cette liste fournit les éléments suivants :

• VALUE : valeurs numériques qui ne sont pas formatées sous forme de date ou d'heure.

• DATETIME : valeurs numériques formatées sous forme de date ou d'heure.

• STRING : chaînes.

• ANNOTATION : commentaires liés aux cellules.

• FORMULA : formules.

• HARDATTR : formatage direct des cellules.

• STYLES : formatage indirect.

• OBJECTS : objets de dessin liés aux cellules.

• EDITATTR : formatage des caractères ne s'appliquant qu'à certaines parties des cellules.

Vous pouvez également ajouter un ensemble de constantes pour supprimer différentes informations avec un appel de clearContents.

Recherche et remplacement du contenu des cellules

Les classeurs, comme les documents texte, proposent une fonction de recherche et remplacement.

Les objets Descriptor pour la recherche et le remplacement dans les classeurs ne sont pas créés directement au moyen de l'objet Document, mais plutôt avec la liste Sheets. L'exemple suivant illustre un processus de recherche et de remplacement :

Dim Doc As Object
Dim Sheet As Object
Dim ReplaceDescriptor As Object
Dim I As Integer

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

ReplaceDescriptor = Sheet.createReplaceDescriptor()
ReplaceDescriptor.SearchString = "is"
ReplaceDescriptor.ReplaceString = "was"
For I = 0 to Doc.Sheets.Count - 1
   Sheet = Doc.Sheets(I)
   Sheet.ReplaceAll(ReplaceDescriptor)
Next I

Cet exemple utilise la première page du document pour créer un objet ReplaceDescriptor, puis l'applique à toutes les pages dans une boucle.