xmlDrawing.go

   1 // Copyright 2016 - 2023 The excelize Authors. All rights reserved. Use of
   2 // this source code is governed by a BSD-style license that can be found in
   3 // the LICENSE file.
   4 //
   5 // Package excelize providing a set of functions that allow you to write to and
   6 // read from XLAM / XLSM / XLSX / XLTM / XLTX files. Supports reading and
   7 // writing spreadsheet documents generated by Microsoft Excel™ 2007 and later.
   8 // Supports complex components by high compatibility, and provided streaming
   9 // API for generating or reading data from a worksheet with huge amounts of
  10 // data. This library needs Go version 1.16 or later.
  11
  12 package excelize
  13
  14 import (
  15         "encoding/xml"
  16         "sync"
  17 )
  18
  19 // xlsxCNvPr directly maps the cNvPr (Non-Visual Drawing Properties). This
  20 // element specifies non-visual canvas properties. This allows for additional
  21 // information that does not affect the appearance of the picture to be stored.
  22 type xlsxCNvPr struct {
  23         ID         int             `xml:"id,attr"`
  24         Name       string          `xml:"name,attr"`
  25         Descr      string          `xml:"descr,attr"`
  26         Title      string          `xml:"title,attr,omitempty"`
  27         HlinkClick *xlsxHlinkClick `xml:"a:hlinkClick"`
  28 }
  29
  30 // xlsxHlinkClick (Click Hyperlink) Specifies the on-click hyperlink
  31 // information to be applied to a run of text. When the hyperlink text is
  32 // clicked the link is fetched.
  33 type xlsxHlinkClick struct {
  34         R              string `xml:"xmlns:r,attr,omitempty"`
  35         RID            string `xml:"r:id,attr,omitempty"`
  36         InvalidURL     string `xml:"invalidUrl,attr,omitempty"`
  37         Action         string `xml:"action,attr,omitempty"`
  38         TgtFrame       string `xml:"tgtFrame,attr,omitempty"`
  39         Tooltip        string `xml:"tooltip,attr,omitempty"`
  40         History        bool   `xml:"history,attr,omitempty"`
  41         HighlightClick bool   `xml:"highlightClick,attr,omitempty"`
  42         EndSnd         bool   `xml:"endSnd,attr,omitempty"`
  43 }
  44
  45 // xlsxPicLocks directly maps the picLocks (Picture Locks). This element
  46 // specifies all locking properties for a graphic frame. These properties inform
  47 // the generating application about specific properties that have been
  48 // previously locked and thus should not be changed.
  49 type xlsxPicLocks struct {
  50         NoAdjustHandles    bool `xml:"noAdjustHandles,attr,omitempty"`
  51         NoChangeArrowheads bool `xml:"noChangeArrowheads,attr,omitempty"`
  52         NoChangeAspect     bool `xml:"noChangeAspect,attr"`
  53         NoChangeShapeType  bool `xml:"noChangeShapeType,attr,omitempty"`
  54         NoCrop             bool `xml:"noCrop,attr,omitempty"`
  55         NoEditPoints       bool `xml:"noEditPoints,attr,omitempty"`
  56         NoGrp              bool `xml:"noGrp,attr,omitempty"`
  57         NoMove             bool `xml:"noMove,attr,omitempty"`
  58         NoResize           bool `xml:"noResize,attr,omitempty"`
  59         NoRot              bool `xml:"noRot,attr,omitempty"`
  60         NoSelect           bool `xml:"noSelect,attr,omitempty"`
  61 }
  62
  63 // xlsxBlip element specifies the existence of an image (binary large image or
  64 // picture) and contains a reference to the image data.
  65 type xlsxBlip struct {
  66         Embed   string                        `xml:"r:embed,attr"`
  67         Cstate  string                        `xml:"cstate,attr,omitempty"`
  68         R       string                        `xml:"xmlns:r,attr"`
  69         ExtList *xlsxEGOfficeArtExtensionList `xml:"a:extLst"`
  70 }
  71
  72 // xlsxStretch directly maps the stretch element. This element specifies that a
  73 // BLIP should be stretched to fill the target rectangle. The other option is a
  74 // tile where a BLIP is tiled to fill the available area.
  75 type xlsxStretch struct {
  76         FillRect string `xml:"a:fillRect"`
  77 }
  78
  79 // xlsxOff directly maps the colOff and rowOff element. This element is used to
  80 // specify the column offset within a cell.
  81 type xlsxOff struct {
  82         X int `xml:"x,attr"`
  83         Y int `xml:"y,attr"`
  84 }
  85
  86 // aExt directly maps the a:ext element.
  87 type aExt struct {
  88         Cx int `xml:"cx,attr"`
  89         Cy int `xml:"cy,attr"`
  90 }
  91
  92 // xlsxPrstGeom directly maps the prstGeom (Preset geometry). This element
  93 // specifies when a preset geometric shape should be used instead of a custom
  94 // geometric shape. The generating application should be able to render all
  95 // preset geometries enumerated in the ST_ShapeType list.
  96 type xlsxPrstGeom struct {
  97         Prst string `xml:"prst,attr"`
  98 }
  99
 100 // xlsxXfrm directly maps the xfrm (2D Transform for Graphic Frame). This
 101 // element specifies the transform to be applied to the corresponding graphic
 102 // frame. This transformation is applied to the graphic frame just as it would
 103 // be for a shape or group shape.
 104 type xlsxXfrm struct {
 105         Off xlsxOff `xml:"a:off"`
 106         Ext aExt    `xml:"a:ext"`
 107 }
 108
 109 // xlsxCNvPicPr directly maps the cNvPicPr (Non-Visual Picture Drawing
 110 // Properties). This element specifies the non-visual properties for the picture
 111 // canvas. These properties are to be used by the generating application to
 112 // determine how certain properties are to be changed for the picture object in
 113 // question.
 114 type xlsxCNvPicPr struct {
 115         PicLocks xlsxPicLocks `xml:"a:picLocks"`
 116 }
 117
 118 // directly maps the nvPicPr (Non-Visual Properties for a Picture). This element
 119 // specifies all non-visual properties for a picture. This element is a
 120 // container for the non-visual identification properties, shape properties and
 121 // application properties that are to be associated with a picture. This allows
 122 // for additional information that does not affect the appearance of the picture
 123 // to be stored.
 124 type xlsxNvPicPr struct {
 125         CNvPr    xlsxCNvPr    `xml:"xdr:cNvPr"`
 126         CNvPicPr xlsxCNvPicPr `xml:"xdr:cNvPicPr"`
 127 }
 128
 129 // xlsxCTSVGBlip specifies a graphic element in Scalable Vector Graphics (SVG)
 130 // format.
 131 type xlsxCTSVGBlip struct {
 132         XMLNSaAVG string `xml:"xmlns:asvg,attr"`
 133         Embed     string `xml:"r:embed,attr"`
 134         Link      string `xml:"r:link,attr,omitempty"`
 135 }
 136
 137 // xlsxCTOfficeArtExtension used for future extensibility and is seen elsewhere
 138 // throughout the drawing area.
 139 type xlsxCTOfficeArtExtension struct {
 140         XMLName xml.Name      `xml:"a:ext"`
 141         URI     string        `xml:"uri,attr"`
 142         SVGBlip xlsxCTSVGBlip `xml:"asvg:svgBlip"`
 143 }
 144
 145 // xlsxEGOfficeArtExtensionList used for future extensibility and is seen
 146 // elsewhere throughout the drawing area.
 147 type xlsxEGOfficeArtExtensionList struct {
 148         Ext []xlsxCTOfficeArtExtension `xml:"ext"`
 149 }
 150
 151 // xlsxBlipFill directly maps the blipFill (Picture Fill). This element
 152 // specifies the kind of picture fill that the picture object has. Because a
 153 // picture has a picture fill already by default, it is possible to have two
 154 // fills specified for a picture object.
 155 type xlsxBlipFill struct {
 156         Blip    xlsxBlip    `xml:"a:blip"`
 157         Stretch xlsxStretch `xml:"a:stretch"`
 158 }
 159
 160 // xlsxLineProperties specifies the width of a line in EMUs. This simple type
 161 // has a minimum value of greater than or equal to 0. This simple type has a
 162 // maximum value of less than or equal to 20116800.
 163 type xlsxLineProperties struct {
 164         W         int           `xml:"w,attr,omitempty"`
 165         SolidFill *xlsxInnerXML `xml:"a:solidFill"`
 166 }
 167
 168 // xlsxSpPr directly maps the spPr (Shape Properties). This element specifies
 169 // the visual shape properties that can be applied to a picture. These are the
 170 // same properties that are allowed to describe the visual properties of a shape
 171 // but are used here to describe the visual appearance of a picture within a
 172 // document.
 173 type xlsxSpPr struct {
 174         Xfrm      xlsxXfrm           `xml:"a:xfrm"`
 175         PrstGeom  xlsxPrstGeom       `xml:"a:prstGeom"`
 176         SolidFill *xlsxInnerXML      `xml:"a:solidFill"`
 177         Ln        xlsxLineProperties `xml:"a:ln"`
 178 }
 179
 180 // xlsxPic elements encompass the definition of pictures within the DrawingML
 181 // framework. While pictures are in many ways very similar to shapes they have
 182 // specific properties that are unique in order to optimize for picture-
 183 // specific scenarios.
 184 type xlsxPic struct {
 185         NvPicPr  xlsxNvPicPr  `xml:"xdr:nvPicPr"`
 186         BlipFill xlsxBlipFill `xml:"xdr:blipFill"`
 187         SpPr     xlsxSpPr     `xml:"xdr:spPr"`
 188 }
 189
 190 // xlsxFrom specifies the starting anchor.
 191 type xlsxFrom struct {
 192         Col    int `xml:"xdr:col"`
 193         ColOff int `xml:"xdr:colOff"`
 194         Row    int `xml:"xdr:row"`
 195         RowOff int `xml:"xdr:rowOff"`
 196 }
 197
 198 // xlsxTo directly specifies the ending anchor.
 199 type xlsxTo struct {
 200         Col    int `xml:"xdr:col"`
 201         ColOff int `xml:"xdr:colOff"`
 202         Row    int `xml:"xdr:row"`
 203         RowOff int `xml:"xdr:rowOff"`
 204 }
 205
 206 // xdrClientData directly maps the clientData element. An empty element which
 207 // specifies (via attributes) certain properties related to printing and
 208 // selection of the drawing object. The fLocksWithSheet attribute (either true
 209 // or false) determines whether to disable selection when the sheet is
 210 // protected, and fPrintsWithSheet attribute (either true or false) determines
 211 // whether the object is printed when the sheet is printed.
 212 type xdrClientData struct {
 213         FLocksWithSheet  bool `xml:"fLocksWithSheet,attr"`
 214         FPrintsWithSheet bool `xml:"fPrintsWithSheet,attr"`
 215 }
 216
 217 // xdrCellAnchor specifies a oneCellAnchor (One Cell Anchor Shape Size) and
 218 // twoCellAnchor (Two Cell Anchor Shape Size) placeholder for a group, a shape,
 219 // or a drawing element. It moves with cells and its extents are in EMU units.
 220 type xdrCellAnchor struct {
 221         EditAs           string                  `xml:"editAs,attr,omitempty"`
 222         Pos              *xlsxPoint2D            `xml:"xdr:pos"`
 223         From             *xlsxFrom               `xml:"xdr:from"`
 224         To               *xlsxTo                 `xml:"xdr:to"`
 225         Ext              *aExt                   `xml:"xdr:ext"`
 226         Sp               *xdrSp                  `xml:"xdr:sp"`
 227         Pic              *xlsxPic                `xml:"xdr:pic,omitempty"`
 228         GraphicFrame     string                  `xml:",innerxml"`
 229         AlternateContent []*xlsxAlternateContent `xml:"mc:AlternateContent"`
 230         ClientData       *xdrClientData          `xml:"xdr:clientData"`
 231 }
 232
 233 // xlsxCellAnchorPos defines the structure used to serialize the cell anchor for
 234 // adjust drawing object on inserting/deleting column/rows.
 235 type xlsxCellAnchorPos struct {
 236         EditAs           string                  `xml:"editAs,attr,omitempty"`
 237         From             *xlsxFrom               `xml:"xdr:from"`
 238         To               *xlsxTo                 `xml:"xdr:to"`
 239         Pos              *xlsxInnerXML           `xml:"xdr:pos"`
 240         Ext              *xlsxInnerXML           `xml:"xdr:ext"`
 241         Sp               *xlsxInnerXML           `xml:"xdr:sp"`
 242         GrpSp            *xlsxInnerXML           `xml:"xdr:grpSp"`
 243         GraphicFrame     *xlsxInnerXML           `xml:"xdr:graphicFrame"`
 244         CxnSp            *xlsxInnerXML           `xml:"xdr:cxnSp"`
 245         Pic              *xlsxInnerXML           `xml:"xdr:pic"`
 246         ContentPart      *xlsxInnerXML           `xml:"xdr:contentPart"`
 247         AlternateContent []*xlsxAlternateContent `xml:"mc:AlternateContent"`
 248         ClientData       *xlsxInnerXML           `xml:"xdr:clientData"`
 249 }
 250
 251 // xlsxPoint2D describes the position of a drawing element within a spreadsheet.
 252 type xlsxPoint2D struct {
 253         XMLName xml.Name `xml:"xdr:pos"`
 254         X       int      `xml:"x,attr"`
 255         Y       int      `xml:"y,attr"`
 256 }
 257
 258 // xlsxWsDr directly maps the root element for a part of this content type shall
 259 // wsDr.
 260 type xlsxWsDr struct {
 261         mu               sync.Mutex
 262         XMLName          xml.Name                `xml:"xdr:wsDr"`
 263         NS               string                  `xml:"xmlns,attr,omitempty"`
 264         A                string                  `xml:"xmlns:a,attr,omitempty"`
 265         Xdr              string                  `xml:"xmlns:xdr,attr,omitempty"`
 266         R                string                  `xml:"xmlns:r,attr,omitempty"`
 267         AlternateContent []*xlsxAlternateContent `xml:"mc:AlternateContent"`
 268         AbsoluteAnchor   []*xdrCellAnchor        `xml:"xdr:absoluteAnchor"`
 269         OneCellAnchor    []*xdrCellAnchor        `xml:"xdr:oneCellAnchor"`
 270         TwoCellAnchor    []*xdrCellAnchor        `xml:"xdr:twoCellAnchor"`
 271 }
 272
 273 // xlsxGraphicFrame (Graphic Frame) directly maps the xdr:graphicFrame element.
 274 // This element specifies the existence of a graphics frame. This frame contains
 275 // a graphic that was generated by an external source and needs a container in
 276 // which to be displayed on the slide surface.
 277 type xlsxGraphicFrame struct {
 278         XMLName          xml.Name             `xml:"xdr:graphicFrame"`
 279         Macro            string               `xml:"macro,attr"`
 280         NvGraphicFramePr xlsxNvGraphicFramePr `xml:"xdr:nvGraphicFramePr"`
 281         Xfrm             xlsxXfrm             `xml:"xdr:xfrm"`
 282         Graphic          *xlsxGraphic         `xml:"a:graphic"`
 283 }
 284
 285 // xlsxNvGraphicFramePr (Non-Visual Properties for a Graphic Frame) directly
 286 // maps the xdr:nvGraphicFramePr element. This element specifies all non-visual
 287 // properties for a graphic frame. This element is a container for the non-
 288 // visual identification properties, shape properties and application properties
 289 // that are to be associated with a graphic frame. This allows for additional
 290 // information that does not affect the appearance of the graphic frame to be
 291 // stored.
 292 type xlsxNvGraphicFramePr struct {
 293         CNvPr                *xlsxCNvPr `xml:"xdr:cNvPr"`
 294         ChicNvGraphicFramePr string     `xml:"xdr:cNvGraphicFramePr"`
 295 }
 296
 297 // xlsxGraphic (Graphic Object) directly maps the a:graphic element. This
 298 // element specifies the existence of a single graphic object. Document authors
 299 // should refer to this element when they wish to persist a graphical object of
 300 // some kind. The specification for this graphical object is provided entirely
 301 // by the document author and referenced within the graphicData child element.
 302 type xlsxGraphic struct {
 303         GraphicData *xlsxGraphicData `xml:"a:graphicData"`
 304 }
 305
 306 // xlsxGraphicData (Graphic Object Data) directly maps the a:graphicData
 307 // element. This element specifies the reference to a graphic object within the
 308 // document. This graphic object is provided entirely by the document authors
 309 // who choose to persist this data within the document.
 310 type xlsxGraphicData struct {
 311         URI   string     `xml:"uri,attr"`
 312         Chart *xlsxChart `xml:"c:chart,omitempty"`
 313         Sle   *xlsxSle   `xml:"sle:slicer"`
 314 }
 315
 316 type xlsxSle struct {
 317         XMLNS string `xml:"xmlns:sle,attr"`
 318         Name  string `xml:"name,attr"`
 319 }
 320
 321 // xlsxChart (Chart) directly maps the c:chart element.
 322 type xlsxChart struct {
 323         C   string `xml:"xmlns:c,attr"`
 324         RID string `xml:"r:id,attr"`
 325         R   string `xml:"xmlns:r,attr"`
 326 }
 327
 328 // xdrSp (Shape) directly maps the xdr:sp element. This element specifies the
 329 // existence of a single shape. A shape can either be a preset or a custom
 330 // geometry, defined using the SpreadsheetDrawingML framework. In addition to a
 331 // geometry each shape can have both visual and non-visual properties attached.
 332 // Text and corresponding styling information can also be attached to a shape.
 333 // This shape is specified along with all other shapes within either the shape
 334 // tree or group shape elements.
 335 type xdrSp struct {
 336         XMLName  xml.Name   `xml:"xdr:sp"`
 337         Macro    string     `xml:"macro,attr"`
 338         Textlink string     `xml:"textlink,attr"`
 339         NvSpPr   *xdrNvSpPr `xml:"xdr:nvSpPr"`
 340         SpPr     *xlsxSpPr  `xml:"xdr:spPr"`
 341         Style    *xdrStyle  `xml:"xdr:style"`
 342         TxBody   *xdrTxBody `xml:"xdr:txBody"`
 343 }
 344
 345 // xdrNvSpPr (Non-Visual Properties for a Shape) directly maps the xdr:nvSpPr
 346 // element. This element specifies all non-visual properties for a shape. This
 347 // element is a container for the non-visual identification properties, shape
 348 // properties and application properties that are to be associated with a shape.
 349 // This allows for additional information that does not affect the appearance of
 350 // the shape to be stored.
 351 type xdrNvSpPr struct {
 352         CNvPr   *xlsxCNvPr  `xml:"xdr:cNvPr"`
 353         CNvSpPr *xdrCNvSpPr `xml:"xdr:cNvSpPr"`
 354 }
 355
 356 // xdrCNvSpPr (Connection Non-Visual Shape Properties) directly maps the
 357 // xdr:cNvSpPr element. This element specifies the set of non-visual properties
 358 // for a connection shape. These properties specify all data about the
 359 // connection shape which do not affect its display within a spreadsheet.
 360 type xdrCNvSpPr struct {
 361         TxBox bool `xml:"txBox,attr"`
 362 }
 363
 364 // xdrStyle (Shape Style) directly maps the xdr:style element. The element
 365 // specifies the style that is applied to a shape and the corresponding
 366 // references for each of the style components such as lines and fills.
 367 type xdrStyle struct {
 368         LnRef     *aRef     `xml:"a:lnRef"`
 369         FillRef   *aRef     `xml:"a:fillRef"`
 370         EffectRef *aRef     `xml:"a:effectRef"`
 371         FontRef   *aFontRef `xml:"a:fontRef"`
 372 }
 373
 374 // aRef directly maps the a:lnRef, a:fillRef and a:effectRef element.
 375 type aRef struct {
 376         Idx       int            `xml:"idx,attr"`
 377         ScrgbClr  *aScrgbClr     `xml:"a:scrgbClr"`
 378         SchemeClr *attrValString `xml:"a:schemeClr"`
 379         SrgbClr   *attrValString `xml:"a:srgbClr"`
 380 }
 381
 382 // aScrgbClr (RGB Color Model - Percentage Variant) directly maps the a:scrgbClr
 383 // element. This element specifies a color using the red, green, blue RGB color
 384 // model. Each component, red, green, and blue is expressed as a percentage from
 385 // 0% to 100%. A linear gamma of 1.0 is assumed.
 386 type aScrgbClr struct {
 387         R float64 `xml:"r,attr"`
 388         G float64 `xml:"g,attr"`
 389         B float64 `xml:"b,attr"`
 390 }
 391
 392 // aFontRef (Font Reference) directly maps the a:fontRef element. This element
 393 // represents a reference to a themed font. When used it specifies which themed
 394 // font to use along with a choice of color.
 395 type aFontRef struct {
 396         Idx       string         `xml:"idx,attr"`
 397         SchemeClr *attrValString `xml:"a:schemeClr"`
 398 }
 399
 400 // xdrTxBody (Shape Text Body) directly maps the xdr:txBody element. This
 401 // element specifies the existence of text to be contained within the
 402 // corresponding shape. All visible text and visible text related properties are
 403 // contained within this element. There can be multiple paragraphs and within
 404 // paragraphs multiple runs of text.
 405 type xdrTxBody struct {
 406         BodyPr *aBodyPr `xml:"a:bodyPr"`
 407         P      []*aP    `xml:"a:p"`
 408 }
 409
 410 // Picture maps the format settings of the picture.
 411 type Picture struct {
 412         Extension string
 413         File      []byte
 414         Format    *GraphicOptions
 415 }
 416
 417 // GraphicOptions directly maps the format settings of the picture.
 418 type GraphicOptions struct {
 419         AltText         string
 420         PrintObject     *bool
 421         Locked          *bool
 422         LockAspectRatio bool
 423         AutoFit         bool
 424         OffsetX         int
 425         OffsetY         int
 426         ScaleX          float64
 427         ScaleY          float64
 428         Hyperlink       string
 429         HyperlinkType   string
 430         Positioning     string
 431 }
 432
 433 // Shape directly maps the format settings of the shape.
 434 type Shape struct {
 435         Cell      string
 436         Type      string
 437         Macro     string
 438         Width     uint
 439         Height    uint
 440         Format    GraphicOptions
 441         Fill      Fill
 442         Line      ShapeLine
 443         Paragraph []RichTextRun
 444 }
 445
 446 // ShapeColor directly maps the color settings of the shape.
 447 type ShapeColor struct {
 448         Line   string
 449         Fill   string
 450         Effect string
 451 }
 452
 453 // ShapeLine directly maps the line settings of the shape.
 454 type ShapeLine struct {
 455         Color string
 456         Width *float64
 457 }