Chapitre 9 Diagrammes

StarOffice peut afficher les données dans un diagramme : des liaisons graphiques sont alors créées entre les données sous forme de barres, de diagrammes à secteurs, de lignes et autres éléments. Les données peuvent être affichées sous forme d'images 2D ou 3D, et l'apparence des éléments du diagramme peut être adaptée individuellement de la même manière que pour les éléments de dessin.

Si les données sont disponibles dans une feuille de calcul, elles peuvent être liées au diagramme de façon dynamique. Toute modification apportée aux données de base peut, dans le cas présent, être immédiatement visualisée dans le diagramme assigné. Ce chapitre présente l'interface de programmation des modules de diagramme de StarOffice et s'intéresse à l'utilisation des diagrammes au sein des classeurs.

Utilisation de diagrammes dans les classeurs

Les diagrammes ne sont pas traités comme des documents indépendants dans StarOffice, mais comme les objets incorporés d'un document existant.

Les diagrammes des documents texte et de dessin restent isolés du contenu du document ; en revanche, lorsqu'ils sont utilisés dans les classeurs, un mécanisme permet d'établir une liaison entre les données du document et les diagrammes incorporés. L'exemple suivant explique l'interaction entre un classeur et un diagramme :

Dim Doc As Object
Dim Charts As Object
Dim Chart as Object

Dim Rect As New com.sun.star.awt.Rectangle
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress

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

Rect.X = 8000
Rect.Y = 1000
Rect.Width = 10000
Rect.Height = 7000

RangeAddress(0).Sheet = 0
RangeAddress(0).StartColumn = 0
RangeAddress(0).StartRow = 0
RangeAddress(0).EndColumn = 2
RangeAddress(0).EndRow = 12

Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)

Bien que le code utilisé dans cet exemple puisse paraître complexe, les processus centraux sont limités à trois lignes : la première ligne centrale crée la variable de document Doc, qui fait référence au classeur actif (ligne Doc = StarDesktop.CurrentComponent). Le code utilisé dans l'exemple crée ensuite une liste contenant tous les diagrammes de la première feuille de calcul (ligne Charts = Doc.Sheets(0).Charts). Enfin, un nouveau diagramme est ajouté à la dernière ligne de cette liste à l'aide de la méthode addNewByName. L'utilisateur peut ensuite visualiser ce nouveau diagramme.

La dernière ligne initialise les structures auxiliaires Rect et RangeAddress, que la méthode addNewByName fournit également comme paramètre. Rect détermine la position du diagramme dans la feuille de calcul. RangeAddress détermine la plage de données à lier au diagramme.

L'exemple précédent crée un diagramme à barres. Si vous souhaitez créer un autre type d'image, vous devez remplacer le diagramme à barres de façon explicite :

Chart = Charts.getByName("MyChart").embeddedObject
Chart.Diagram = Chart.createInstance("com.sun.star.chart.LineDiagram")

La première ligne définit l'objet Chart correspondant. La seconde remplace le diagramme actif par un nouveau : dans cet exemple, un diagramme linéaire.

---

Remarque –

Dans Excel, une distinction est faite entre les diagrammes ayant été insérés comme une page séparée dans un document Excel et ceux qui sont incorporés dans une page de table. Par conséquent, deux méthodes d'accès différentes sont définies ici pour les diagrammes. Cette distinction n'existe pas dans StarOffice Basic, car les diagrammes de StarOffice Calc sont toujours créés en tant qu'objets incorporés d'une page de table. L'accès aux diagrammes s'effectue toujours à l'aide de la liste Charts de l'objet Sheet associé.

---

Structure des diagrammes

La structure d'un diagramme, et donc de la liste des services et interfaces qu'il prend en charge, dépend de son type. Les méthodes et propriétés de l'axe Z, par exemple, sont uniquement disponibles dans les diagrammes 3D, mais pas dans les diagrammes 2D. Dans les diagrammes à secteurs, il n'existe aucune interface permettant d'utiliser des axes.

Éléments individuels d'un diagramme

Titre, sous-titre et légende

Les titre, sous-titre et légende constituent les éléments de base de chaque diagramme. Les diagrammes possèdent leurs propres objets pour chacun de ces éléments. L'objet Chart offre les propriétés suivantes de gestion de ces éléments :

• HasMainTitle (Boolean) : active le titre.

• Title (Object) : objet contenant des informations détaillées sur le titre du diagramme (prend en charge le service com.sun.star.chart.ChartTitle).

• HasSubTitle(Boolean) : active le sous-titre.

• Subtitle (Object) : objet contenant des informations détaillées sur le sous-titre du diagramme (prend en charge le service com.sun.star.chart.ChartTitle).

• HasLegend (Boolean) : active la légende.

• Legend (Object) : objet contenant des informations détaillées sur la légende du diagramme (prend en charge le service com.sun.star.chart.ChartLegendPosition).

À de nombreux égards, les éléments spécifiés correspondent à un élément de dessin. Cela est dû au fait que les services com.sun.star.chart.ChartTitle et com.sun.star.chart.ChartLegendPosition prennent en charge le service com.sun.star.drawing.Shape, qui constitue la base technique du programme des éléments de dessin.

Les utilisateurs ont donc la possibilité de déterminer la position et la taille de l'élément à l'aide des propriétés Size et Position.

Les propriétés de remplissage et de ligne (services com.sun.star.drawing.FillProperties et com.sun.star.drawing.LineStyle), ainsi que les propriétés de caractère (service com.sun.star.style.CharacterProperties), sont fournies pour le formatage des éléments.

com.sun.star.chart.ChartTitle contient non seulement les propriétés de format nommées, mais également deux autres propriétés :

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

• String (String) : texte à afficher comme titre ou sous-titre.

La légende du diagramme (service com.sun.star.chart.ChartLegend) contient la propriété supplémentaire suivante :

• Alignment (Enum) : position de la légende (valeur par défaut correspondant à com.sun.star.chart.ChartLegendPosition).

L'exemple suivant crée un diagramme et lui assigne le titre "Test", le sous-titre "Test 2" et une légende. La légende, dont la couleur d'arrière-plan est grise, se trouve au bas du diagramme et a une taille de caractère de 7 points.

Dim Doc As Object
Dim Charts As Object
Dim Chart as Object

Dim Rect As New com.sun.star.awt.Rectangle
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress

Rect.X = 8000
Rect.Y = 1000
Rect.Width = 10000
Rect.Height = 7000

RangeAddress(0).Sheet = 0
RangeAddress(0).StartColumn = 0
RangeAddress(0).StartRow = 0
RangeAddress(0).EndColumn = 2
RangeAddress(0).EndRow = 12

Doc = StarDesktop.CurrentComponent
Charts = Doc.Sheets(0).Charts
Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)
Chart = Charts.getByName("MyChart").EmbeddedObject

Chart.HasMainTitle = True
Chart.Title.String = "Test"

Chart.HasSubTitle = True
Chart.Subtitle.String = "Test 2"

Chart.HasLegend = True
Chart.Legend.Alignment = com.sun.star.chart.ChartLegendPosition.BOTTOM
Chart.Legend.FillStyle = com.sun.star.drawing.FillStyle.SOLID
Chart.Legend.FillColor = RGB(210, 210, 210)
Chart.Legend.CharHeight = 7

Arrière-plan

Chaque diagramme présente une zone d'arrière-plan. Chaque zone possède un objet, accessible en utilisant les propriétés suivantes de l'objet Diagram :

• Area (Object) : zone d'arrière-plan du diagramme (prend en charge le service com.sun.star.chart.ChartArea).

L'arrière-plan d'un diagramme recouvre l'ensemble de sa zone, y compris la zone située sous le titre, le sous-titre et la légende du diagramme. Le service com.sun.star.chart.ChartArea associé prend en charge les propriétés de ligne et de remplissage, et n'offre aucune autre propriété extensive.

Parois et planchers du diagramme

Bien que l'arrière-plan du diagramme recouvre la zone complète du diagramme, la paroi arrière du diagramme se limite à la zone se trouvant directement derrière la plage de données.

Il existe généralement deux parois dans les diagrammes 3D : l'une se situe derrière la plage de données et l'autre sert de démarcation à gauche de l'axe Y. De plus, les diagrammes 3D ont généralement un plancher.

• Floor (Object) : plancher du diagramme (uniquement pour les diagrammes 3D, prend en charge le service com.sun.star.chart.ChartArea).

• Wall (Object) : parois du diagramme (uniquement pour les diagrammes 3D, prend en charge le service com.sun.star.chart.ChartArea).

Les objets spécifiés prennent en charge le service com.sun.star.chart.ChartArea, qui offre à son tour les propriétés habituelles de remplissage et de ligne via les services com.sun.star.drawing.FillProperties et com.sun.star.drawing.LineStyle. Pour plus d'informations, reportez-vous au Chapitre 8, Dessins et présentations.

L'accès aux parois et au plancher du diagramme s'effectue par l'intermédiaire de l'objet Chart, qui fait également partie de l'objet Chart :

Charte.Area.FillBitmapName = "Sky"

L'exemple suivant montre comment une image (nommée Sky) déjà contenue dans StarOffice peut servir d'arrière-plan à un diagramme.

Dim Doc As Object
Dim Charts As Object 
Dim Chart as Object

Dim Rect As New com.sun.star.awt.Rectangle 
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress

Rect.X = 8000 
Rect.Y = 1000 
Rect.Width = 10000 
Rect.Height = 7000

RangeAddress(0).Sheet = 0 
RangeAddress(0).StartColumn = 0 
RangeAddress(0).StartRow = 0 
RangeAddress(0).EndColumn = 2 
RangeAddress(0).EndRow = 12

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

Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True) 
Chart = Charts.getByName("MyChart").EmbeddedObject

Charte.Area.FillStyle = com.sun.star.drawing.FillStyle.BITMAP 
Chart.Area.FillBitmapName = "Sky" 
Chart.Area.FillBitmapMode = com.sun.star.drawing.BitmapMode.REPEAT

Axes

StarOffice reconnaît cinq axes différents pouvant être utilisés dans un diagramme. Dans le scénario le plus simple, il s'agit des axes X et Y. Lorsque vous utilisez des diagrammes 3D, un axe Z est parfois ajouté. Pour les diagrammes dans lesquels les valeurs des différentes lignes dévient de façon significative l'une de l'autre, StarOffice fournit des X et Y supplémentaires pour des opérations de mises à l'échelle secondaires.

Axes X, Y et Z primaires

Outre l'axe réel, il peut également y avoir, pour chacun des axes X, Y et Z primaires, un titre, une description, une grille principale et une grille secondaire. Il existe une option permettant d'afficher et de masquer tous ces éléments. L'objet Diagram offre les propriétés de gestion suivantes pour ces fonctionnalités (en prenant l'exemple d'un axe X, les propriétés des axes Y et Z étant structurées de la même manière) :

• HasXAxis (Boolean) : active l'axe X.

• XAxis (Object) : objet contenant des informations détaillées sur l'axe X (prend en charge le service com.sun.star.chart.ChartAxis).

• HasXAxisDescription (Boolean) : active la description de l'axe X.

• HasXAxisGrid (Boolean) : active la grille principale de l'axe X.

• XMainGrid (Object) : objet contenant des informations détaillées sur la grille principale de l'axe X (prend en charge le service com.sun.star.chart.ChartGrid).

• HasXAxisHelpGrid (Boolean) : active la grille secondaire de l'axe X.

• XHelpGrid (Object) : objet contenant des informations détaillées sur la grille secondaire de l'axe X (prend en charge le service com.sun.star.chart.ChartGrid).

• HasXAxisTitle (Boolean) : active le titre de l'axe X.

• XAxisTitle (Object) : objet contenant des informations détaillées sur le titre de l'axe X (prend en charge le service com.sun.star.chart.ChartTitle).

Axes X et Y secondaires

Les propriétés suivantes sont disponibles pour les axes X et Y secondaires (propriétés prenant exemple sur l'axe secondaire X) :

• HasSecondaryXAxis (Boolean) : active l'axe secondaire X.

• SecondaryXAxis (Object) : objet contenant des informations détaillées sur l'axe secondaire X (prend en charge le service com.sun.star.chart.ChartAxis).

• HasSecondaryXAxisDescription (Boolean) : active la description du titre de l'axe X.

Propriétés des axes

Les objets Axis d'un diagramme StarOffice prennent en charge le service com.sun.star.chart.ChartAxis. Outre les propriétés de caractère (service com.sun.star.style.CharacterProperties : reportez-vous au Chapitre 6, Documents texte) et de ligne (service com.sun.star.drawing.LineStyle : reportez-vous au chapitre 8, Chapitre 8, Dessins et présentations), il offre les propriétés suivantes :

• Max (Double) : valeur maximale de l'axe.

• Min (Double) : valeur minimale de l'axe.

• Origin (Double) : point d'intersection des axes.

• StepMain (Double) : distance entre deux lignes principales de l'axe.

• StepHelp (Double) : distance entre deux lignes secondaires de l'axe.

• AutoMax (Boolean) : détermine automatiquement la valeur maximale de l'axe.

• AutoMax (Boolean) : détermine automatiquement la valeur minimale de l'axe.

• AutoOrigin (Boolean) : détermine automatiquement le point d'intersection des axes.

• AutoStepMain (Boolean) : détermine automatiquement la distance entre deux lignes principales d'un axe.

• AutoStepHelp (Boolean) : détermine automatiquement la distance entre deux lignes secondaires d'un axe.

• Logarithmic (Boolean) : ajuste les axes de manière logarithmique (et non de manière linéaire).

• DisplayLabels (Boolean) : active l'étiquette de texte des axes.

• TextRotation (Long) : angle de rotation de l'étiquette de texte des axes en centièmes de degré.

• Marks (Const) : constante spécifiant si les lignes principales de l'axe doivent se trouver à l'intérieur ou à l'extérieur de la zone du diagramme (les valeurs par défaut correspondent à com.sun.star.chart.ChartAxisMarks).

• HelpMarks (Const) : constante qui spécifiant si les lignes secondaires de l'axe doivent se trouver à l'intérieur ou à l'extérieur de la zone du diagramme (les valeurs par défaut correspondent à com.sun.star.chart.ChartHelpMarks).

• Overlap (Long) : pourcentage spécifiant l'étendue de superposition des barres des différents jeux de données. À 100 %, les barres s'affichent en superposition complète, à - 100 %, une distance égale à la largeur d'une barre les sépare.

• GapWidth (long) : pourcentage spécifiant la distance possible entre les différents groupes de barres d'un diagramme. À 100 %, la distance correspond à la largeur d'une barre.

• ArrangeOrder (enum) : détails de la position de l'inscription ; outre le positionnement sur une ligne, il est également possible de scinder l'étiquette sur deux lignes (valeur par défaut correspondant à com.sun.star.chart.ChartAxisArrangeOrderType).

• TextBreak (Boolean) : autorise les retours à la ligne.

• TextCanOverlap (Boolean) : autorise les chevauchements de texte.

• NumberFormat (Long) : format numérique (voir la section Formats de nombre, de date et de texte).

Propriétés de la grille de l'axe

L'objet de la grille de l'axe est basé sur le service com.sun.star.chart.ChartGrid, qui prend en charge les propriétés de ligne du service de support com.sun.star.drawing.LineStyle. Pour plus d'informations, reportez-vous au Chapitre 8, Dessins et présentations.

Propriétés du titre de l'axe

Les objets de formatage du titre de l'axe sont basés sur le service com.sun.star.chart.ChartTitle, également utilisé pour les titres des diagrammes.

Exemple

L'exemple suivant crée un diagramme linéaire. La couleur blanche est définie pour la paroi arrière du diagramme. Les axes X et Y possèdent une grille secondaire grise pour un meilleur repérage visuel. La valeur minimale de l'axe Y est fixée à 0 et sa valeur maximale à 100, de manière à conserver la résolution du diagramme même en cas de modification des valeurs.

Dim Doc As Object Dim Charts As Object Dim Chart as Object

Dim Rect As New com.sun.star.awt.Rectangle 
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress

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

Rect.X = 8000 Rect.Y = 1000 Rect.Width = 10000 Rect.Height = 7000

RangeAddress(0).Sheet = 0 
RangeAddress(0).StartColumn = 0 
RangeAddress(0).StartRow = 0 
RangeAddress(0).EndColumn = 2 
RangeAddress(0).EndRow = 12

Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)

Chart = Charts.getByName("MyChart").embeddedObject 
Chart.Diagram = Chart.createInstance("com.sun.star.chart.LineDiagram")

Chart.Diagram.Wall.FillColor = RGB(255, 255, 255)

Chart.Diagram.HasXAxisGrid = True 
Chart.Diagram.XMainGrid.LineColor = RGB(192, 192, 192)

Chart.Diagram.HasYAxisGrid = True 
Chart.Diagram.YMainGrid.LineColor = RGB(192, 192, 192)

Chart.Diagram.YAxis.Min = 0 
Chart.Diagram.YAxis.Max = 100

Diagrammes 3D

La plupart des diagrammes de StarOffice peuvent également s'afficher avec des images 3D. Tous les types de diagrammes offrant cette option prennent en charge le service com.sun.star.chart.Dim3DDiagram. Ce service n'offre qu'une propriété :

• Dim3D (Boolean) : active l'affichage en 3D.

Diagrammes empilés

Les diagrammes empilés sont des diagrammes organisés avec plusieurs valeurs individuelles empilées pour produire une valeur totale. Cette vue montre non seulement les valeurs individuelles, mais également une présentation de toutes les valeurs.

Dans StarOffice, il est possible d'afficher plusieurs types de diagrammes sous forme empilée. Tous ces diagrammes prennent en charge le service com.sun.star.chart.StackableDiagram, qui fournit quant à lui les propriétés suivantes :

• Stacked (Boolean) : active le mode de visualisation des éléments empilés.

• Percent (Boolean) : affiche la répartition en pourcentage plutôt qu'en valeurs absolues.

Types de diagrammes

Diagrammes linéaires

Les diagrammes linéaires (service com.sun.star.chart.LineDiagram) prennent en charge un axe X, deux axes Y et un axe Z. Ils peuvent s'afficher sous forme d'images 2D ou 3D (service com.sun.star.chart.Dim3Ddiagram). Les lignes peuvent être empilées (com.sun.star.chart.StackableDiagram).

Les diagrammes linéaires offrent les propriétés suivantes :

• SymbolType (const) : symbole pour l'affichage des points de données (constante correspondant à com.sun.star.chart.ChartSymbolType).

• SymbolSize (Long) : taille du symbole d'affichage des points de données, exprimée en centièmes de millimètre.

• SymbolBitmapURL (String) : nom des fichiers d'images utilisées pour afficher les points de données.

• Lines (Boolean) : relie les points de données à l'aide de lignes.

• SplineType (Long) : fonction spline de lissage des lignes (0 : pas de fonction spline, 1 : splines cubiques, 2 : splines B).

• SplineOrder (Long) : poids polynomial des splines (pour les splines B uniquement).

• SplineResolution (Long) : nombre de points de support pour le calcul des splines.

Diagrammes de surface

Les diagrammes de surface (service com.sun.star.chart.AreaDiagram) prennent en charge un axe X, deux axes Y et un axe Z. Ils peuvent s'afficher sous forme d'images 2D ou 3D (service com.sun.star.chart.Dim3Ddiagram). Les surfaces peuvent être empilées (com.sun.star.chart.StackableDiagram).

Diagrammes à barres

Les diagrammes à barres (service com.sun.star.chart.BarDiagram) prennent en charge un axe X, deux axes Y et un axe Z. Ils peuvent s'afficher sous forme d'images 2D ou 3D (service com.sun.star.chart.Dim3Ddiagram). Les barres peuvent être empilées (com.sun.star.chart.StackableDiagram).

Ils offrent les propriétés suivantes :

• Vertical (Boolean) : affiche les barres verticalement.

• Deep (Boolean) : en mode visualisation 3D, positionne les barres les unes derrière les autres plutôt que les unes à côté des autres.

• StackedBarsConnected (Boolean) : relie les barres associées dans un diagramme empilé à l'aide de lignes (uniquement dans les diagrammes horizontaux).

• NumberOfLines (Long) : nombre de lignes à afficher dans un diagramme empilé sous forme de lignes plutôt que sous forme de barres.

Diagrammes à secteurs

Les diagrammes à secteurs (service com.sun.star.chart.PieDiagram) ne contiennent pas d'axes et ne peuvent pas être empilés. Ils peuvent s'afficher sous forme d'images 2D ou 3D (service com.sun.star.chart.Dim3Ddiagram).