'\" t
.\" Automatically generated by Pandoc 3.10
.\"
.TH "ooxml" "n" "" "" "ooxml user documentation"
.SH NAME
::ooxml::xl_sheets, ::ooxml::xl_read, ::ooxml::xl_write,
::ooxml::tablelist_to_xl \- Read and create ECMA\-376 Office Open XML
Spreadsheets (the .xlsx format)
.SH SYNOPSIS
.IP
.EX
package require ooxml
::ooxml::xl_sheets file
::ooxml::xl_read file ?\-option value ...?
::ooxml::xl_write new ?\-option value ...?
::ooxml::tablelist_to_xl tablelist ?\-option value ...?
.EE
.SH DESCRIPTION
The commands of this package read or create ECMA\-376 Office Open XML
Spreadsheets (LibreOffice and Excel \(lq.xlsx\(rq files).
The three most important are:
.IP
.EX
::ooxml::xl_read \- imports a .xlsx spreadsheet file into a Tcl array
::ooxml::xl_write \- creates a spreadsheet object command
::ooxml::tablelist_to_xl \- exports a Tcl tablelist to a .xlsx spreadsheet
.EE
.PP
In this documentation the term workbook means a whole spreadsheet with
all its tables.
The term worksheet means a specific table of the workbook it belongs to.
.PP
All row, column and sheet indices used by this package are zero\-based.
Cell positions may be given numerically as \f[I]row,column\f[R] or in
Excel notation; see CELL INDEX.
.PP
The package provides the following commands:
.TP
\f[B]::ooxml::arrayDeleteSheet\f[R] \f[I]arrayName\f[R] \f[I]sheetId\f[R] \f[I]?\-sheetname?\f[R]
Deletes one worksheet from an array read with \f[I]::ooxml::xl_read\f[R]
and renumbers the remaining sheets.
The array is passed by name (without \f[CR]$\f[R]).
By default \f[I]sheetId\f[R] is the zero\-based sheet index; with the
\f[B]\-sheetname\f[R] option it is the worksheet name.
.RS
.IP
.EX
  ::ooxml::arrayDeleteSheet workbook 0
  ::ooxml::arrayDeleteSheet workbook \(dqSheet1\(dq \-sheetname
.EE
.RE
.TP
\f[B]::ooxml::CalcColumnWidth\f[R] \f[I]numberOfCharacters\f[R] \f[I]?maximumDigitWidth?\f[R] \f[I]?pixelPadding?\f[R]
Returns the column width value (for the \f[B]column\f[R] method
\f[B]\-width\f[R] option) that fits the given number of characters.
The optional arguments \f[I]maximumDigitWidth\f[R] (default 7) and
\f[I]pixelPadding\f[R] (default 5) describe the metrics of the standard
font.
.RS
.IP
.EX
  ::ooxml::CalcColumnWidth 16   ;# \-> 16.7109375
.EE
.RE
.TP
\f[B]::ooxml::Column\f[R] \f[I]column\f[R]
Converts the zero\-based \f[I]column\f[R] number into the column name in
Excel notation (0 \-> A, 1 \-> B, 26 \-> AA, \&...).
.TP
\f[B]::ooxml::Default\f[R] \f[I]name\f[R] \f[I]value\f[R]
Sets a package wide default.
The only currently supported \f[I]name\f[R] is \f[I]path\f[R]: the
default directory of written files (used e.g.\ by
\f[I]::ooxml::tablelist_to_xl\f[R] if no \f[B]\-path\f[R] is given).
An empty \f[I]value\f[R] resets it to the current directory.
.TP
\f[B]::ooxml::RowColumnToString\f[R] \f[I]rowcol\f[R]
Converts a numerical cell index (\f[I]row,column\f[R], zero\-based) into
Excel notation (0,0 \-> A1).
.TP
\f[B]::ooxml::StringToRowColumn\f[R] \f[I]name\f[R]
Converts a cell position in Excel notation into the numerical form (A1
\-> 0,0).
.TP
\f[B]::ooxml::tablelist_to_xl\f[R] \f[I]tablelist\f[R] \f[I]?\-option value \&...?\f[R]
Exports the content of the Tk tablelist widget \f[I]tablelist\f[R] to a
\&.xlsx file.
The recognized options are:
.RS
.IP
.EX
  \-callback command: Command to be called once per workbook and
  once per column, to customize styles and column properties.
  See below for the arguments. Default is the built\-in callback
  ::ooxml::tablelist_to_xl_callback.

  \-path path: Directory of the output file.

  \-file filename: Name of the output file (a .xlsx suffix is
  appended if missing).

  \-creator name: Creator property of the spreadsheet.

  \-name name: Name of the (single) worksheet.

  \-rootonly: Export only the root level of the tablelist (no
  child items).

  \-addtimestamp: Add a timestamp to the output file name.

  \-globalstyle: Write the cells with the column styles set by
  the callback.
.EE
.PP
The callback is called with the arguments
.IP
.EX
  spreadsheet sheet maxcol column title width align sortmode hide
.EE
.PP
where \f[I]spreadsheet\f[R] is the spreadsheet object, \f[I]sheet\f[R]
the worksheet handle and \f[I]maxcol\f[R] the number of columns.
It is called once with \f[I]column\f[R] = \-1 for the whole workbook
(for example to set the default date style) and then once per column
with the tablelist column properties \f[I]title\f[R], \f[I]width\f[R],
\f[I]align\f[R], \f[I]sortmode\f[R] and \f[I]hide\f[R].
.IP
.EX
  proc myCallback {spreadsheet sheet maxcol column title width align sortmode hide} {
      if {$column == \-1} {
          set datestyle [$spreadsheet style \-numfmt [$spreadsheet numberformat \-datetime]]
          $spreadsheet defaultdatestyle $datestyle
      } elseif {$align eq \(dqright\(dq} {
          $spreadsheet column $sheet \-index $column \-style [$spreadsheet style \-horizontal right]
      }
  }
.EE
.RE
.TP
\f[B]::ooxml::xl_read\f[R] \f[I]file\f[R] \f[I]?\-option value \&...?\f[R]
Reads the given .xlsx \f[I]file\f[R] and returns its contents as a flat
Tcl array (to be caught with \f[CR]array set\f[R]).
See RESULT ARRAY for the keys of the returned array.
The recognized options are:
.RS
.IP
.EX
  \-valuesonly: Read only the cell values, no formatting,
  formulas or sheet properties.

  \-keylist: Additionally build the S,k key (see
  RESULT ARRAY), a dictionary of the non\-empty columns per row.

  \-sheets pattern: Read only the worksheets whose zero\-based
  sheet index matches the glob pattern.

  \-sheetnames pattern: Read only the worksheets whose name
  matches the glob pattern.

  If neither \-sheets nor \-sheetnames is given all worksheets
  are read.

  \-datefmt format: [clock format] string used to convert date
  cells into the value keys (default \(dq%Y\-%m\-%d %H:%M:%S\(dq).

  \-as array: Format of the return value. Currently array is
  the only supported value.
.EE
.PP
A simple example:
.IP
.EX
  array set workbook [::ooxml::xl_read file.xlsx]
  foreach key [lsort \-dictionary [array names workbook 0,v,*]] {
      lassign [split $key ,] sheet tag row col
      puts \(dq$row,$col = $workbook($key)\(dq
  }
.EE
.RE
.TP
\f[B]::ooxml::xl_sheets\f[R] \f[I]file\f[R]
Returns information about the worksheets of the given .xlsx
\f[I]file\f[R] without reading any cell data.
The result is a Tcl list with two elements per worksheet: the
zero\-based sheet index and a dictionary with the keys \f[I]sheetId\f[R]
(the internal sheet id), \f[I]name\f[R] (the display name of the
worksheet) and \f[I]rId\f[R] (the internal relationship id).
.RS
.IP
.EX
  foreach {index info} [::ooxml::xl_sheets file.xlsx] {
      puts \(dq$index: [dict get $info name]\(dq
  }
.EE
.RE
.TP
\f[B]::ooxml::xl_write\f[R] \f[B]new\f[R] \f[I]?\-option value \&...?\f[R]
Creates a spreadsheet object command to build a workbook from scratch:
.RS
.IP
.EX
  set spreadsheet [::ooxml::xl_write new ?\-option value ...?]
.EE
.PP
The recognized options are:
.IP
.EX
  \-creator name: The creator property of the spreadsheet.

  \-created timestamp: The creation time property of the
  spreadsheet. The value is either an integer (seconds, as
  returned by [clock seconds]) or a date string in local time.

  \-modifiedby name: The modified\-by property of the
  spreadsheet.

  \-modified timestamp: The modification time property of the
  spreadsheet. For the value see \-created.

  \-application name: The application property of the
  spreadsheet.
.EE
.RE
.PP
The created spreadsheet object commands currently support the following
methods:
.TP
\f[B]autofilter\f[R] \f[I]sheet\f[R] \f[I]indexFrom\f[R] \f[I]indexTo\f[R]
Adds an autofilter (filter and sort controls on the header row) to the
worksheet, spanning from cell \f[I]indexFrom\f[R] to cell
\f[I]indexTo\f[R] (see CELL INDEX).
.RS
.IP
.EX
  $spreadsheet autofilter $sheet 0,0 0,5
.EE
.RE
.TP
\f[B]border\f[R] \f[I]?\-option value \&...?\f[R]
Defines a border style for the current workbook and returns an ID
(BORDERID) to refer to that style.
The recognized options are:
.RS
.IP
.EX
  \-list: Returns the list of currently defined border styles
  instead of a BORDERID.

  \-leftstyle BORDERLINESTYLE
  \-rightstyle BORDERLINESTYLE
  \-topstyle BORDERLINESTYLE
  \-bottomstyle BORDERLINESTYLE
  \-diagonalstyle BORDERLINESTYLE

  See BORDERLINESTYLE for the valid values.

  \-leftcolor COLOR
  \-rightcolor COLOR
  \-topcolor COLOR
  \-bottomcolor COLOR
  \-diagonalcolor COLOR

  See COLOR for the valid values.

  \-diagonaldirection (up|down)

  \-tag tagname: Gives the border style a name. This name may be
  used instead of the returned BORDERID.
.EE
.PP
See BORDERLINESTYLE and COLOR for the valid option values.
.RE
.TP
\f[B]cell\f[R] \f[I]sheet\f[R] \f[I]?data?\f[R] \f[I]?\-option value \&...?\f[R]
Writes the value \f[I]data\f[R] into a cell of the worksheet
\f[I]sheet\f[R] and returns the position of the written cell as
\f[I]row,column\f[R].
Without the \f[B]\-index\f[R] option the cell is placed in the current
row at the next column (see CELL INDEX for the autoincrement behaviour).
The recognized options are:
.RS
.IP
.EX
  \-index index: Position of the cell, either as row,column or
  in Excel notation. Also accepts a bare column number to place
  the cell in the current row with columns skipped.

  \-style STYLEID: Style of the cell, from the method style.

  \-formula formula: Enter an Excel formula (e.g. \(dqA1+B1\(dq). The
  data argument is usually empty then, the application
  computes the value.

  \-formulaidx integer: Shared formula index. A cell defining a
  shared formula gives \-formula, \-formularef and \-formulaidx;
  the dependent cells give only \-formulaidx.

  \-formularef range: The range the shared formula spans, either
  in Excel notation (C3:C5) or numerically (2,2:4,2).

  \-string: Store the value as string in any case.

  \-nostring: Override a column\-level \-string setting for this
  cell.

  \-nozero: Do not output the value if it is zero.

  \-zero: Override a column\-level \-nozero setting for this cell.

  \-globalstyle: Apply the column style to this cell.

  \-height height: Sets the row height of the current row.

  \-hyperlink url: Makes the cell a hyperlink to url.

  \-tooltip text: Tooltip for the hyperlink (only used together
  with \-hyperlink).
.EE
.RE
.TP
\f[B]column\f[R] \f[I]sheet\f[R] \f[I]?\-option value \&...?\f[R]
Defines the properties of a column of the worksheet \f[I]sheet\f[R] and
returns the column number.
Without the \f[B]\-index\f[R] option the next column is used.
The recognized options are:
.RS
.IP
.EX
  \-index index: Column number.

  \-to index: Last column number, if the definition should span
  a range of columns.

  \-width width: Column width in characters of the standard font
  (may be fractional, see also ::ooxml::CalcColumnWidth).

  \-style STYLEID: Default style for the cells of the column.
  Note that a cell only uses it if written with \-globalstyle.

  \-bestfit: Sets the bestFit flag of the column.

  \-customwidth: Sets the customWidth flag of the column.

  \-string: Store the values of the cells of this column as
  string in any case (a cell may override this with \-nostring).

  \-nozero: Do not output zero values in this column (a cell may
  override this with \-zero).

  \-calcfit: Calculates the column width from the length of the
  longest value written to the column (via
  ::ooxml::CalcColumnWidth) if that is wider than a given
  \-width.
.EE
.RE
.TP
\f[B]defaultdatestyle\f[R] \f[I]STYLEID\f[R]
Sets the default style for date cells.
Values recognized as dates are formatted with this style if the cell
does not have an explicit \f[B]\-style\f[R].
.RS
.IP
.EX
  set datestyle [$spreadsheet style \-numfmt [$spreadsheet numberformat \-datetime]]
  $spreadsheet defaultdatestyle $datestyle
.EE
.RE
.TP
\f[B]fill\f[R] \f[I]?\-option value \&...?\f[R]
Defines a fill style for the current workbook and returns an ID (FILLID)
to refer to that style.
The recognized options are:
.RS
.IP
.EX
  \-list: Returns the list of currently defined fills instead of
  a FILLID.

  \-patterntype PATTERNTYPE: See PATTERNTYPE for the usual
  values (default \(dqnone\(dq).

  \-fgcolor COLOR: Foreground (pattern) color. See COLOR for the
  valid values.

  \-bgcolor COLOR: Background color. See COLOR for the valid
  values.

  \-tag tagname: Gives the fill a name. This name may be used
  instead of the returned FILLID.
.EE
.PP
See PATTERNTYPE and COLOR for the valid option values.
.RE
.TP
\f[B]font\f[R] \f[I]?\-option value \&...?\f[R]
Defines a font for the current workbook and returns an ID (FONTID) to
refer to that font.
The recognized options are:
.RS
.IP
.EX
  \-list: Returns the list of currently defined fonts instead of
  a FONTID.

  \-name name: Font name (default \(dqCalibri\(dq).

  \-family family: Font family number (default 2).

  \-size size: Font size in points (default 12).

  \-color COLOR: See COLOR for the valid values.

  \-scheme scheme: Font scheme (default \(dqminor\(dq).

  \-bold: Bold text.

  \-italic: Italic text.

  \-underline: Underlined text.

  \-tag tagname: Gives the font a name. This name may be used
  instead of the returned FONTID.
.EE
.PP
See COLOR for the valid \f[B]\-color\f[R] values.
.RE
.TP
\f[B]freeze\f[R] \f[I]sheet\f[R] \f[I]index\f[R]
Freezes the panes above and left of the given cell \f[I]index\f[R] (see
CELL INDEX), so they stay visible while scrolling.
.RS
.IP
.EX
  $spreadsheet freeze $sheet 1,0   ;# freeze the first row
.EE
.RE
.TP
\f[B]merge\f[R] \f[I]sheet\f[R] \f[I]indexFrom\f[R] \f[I]indexTo\f[R]
Merges the cell range with the corners \f[I]indexFrom\f[R] and
\f[I]indexTo\f[R] (see CELL INDEX) into one cell.
.RS
.IP
.EX
  $spreadsheet merge $sheet 40,0 40,2
  $spreadsheet merge $sheet A42 A44
.EE
.RE
.TP
\f[B]numberformat\f[R] \f[I]?\-option value \&...?\f[R]
Defines a number format for the current workbook and returns an ID
(NUMFMTID) to refer to that format.
The recognized options are:
.RS
.IP
.EX
  \-format format: Any Excel format string (e.g. {#,##0.00 \(dq€\(dq}).

  \-general: Excel general format.

  \-date: Date format.

  \-time: Time format.

  \-datetime: Date/time format.

  \-iso8601: Date/time in ISO 8601 notation.

  \-number: Integer.

  \-decimal: Decimal number with 2 decimal places.

  \-red: Color negative values red (may be combined with \-number
  and \-decimal).

  \-separator: Thousands separators (may be combined with
  \-number and \-decimal).

  \-fraction: Fractions.

  \-scientific: Scientific notation.

  \-percent: Percentage.

  \-text, \-string: Text format.

  \-tag tagname: Gives the format a name. This name may be used
  instead of the returned NUMFMTID.
.EE
.RE
.TP
\f[B]pageMargins\f[R] \f[I]sheet\f[R] \f[I]?\-option value \&...?\f[R]
Sets the page margins of the worksheet \f[I]sheet\f[R].
The recognized options are:
.RS
.IP
.EX
  \-left \-right \-top \-bottom \-header \-footer

  All options expect a floating point value in inch.
.EE
.PP
If some page margins of a worksheet are set with this method then all
margins of that worksheet are set, either from the options given in the
method call or from the current \f[B]pageMarginsDefault\f[R] values, if
a margin was not in the method call.
.RE
.TP
\f[B]pageMarginsDefault\f[R] \f[I]?\-option value \&...?\f[R]
Sets the page margins of all worksheets which do not have individual
margin settings.
The options are the same as for \f[B]pageMargins\f[R].
The default margins are:
.RS
.PP
.TS
tab(@);
l l.
T{
Margin
T}@T{
Inch
T}
_
T{
left
T}@T{
0.75
T}
T{
right
T}@T{
0.75
T}
T{
top
T}@T{
1
T}
T{
bottom
T}@T{
1
T}
T{
header
T}@T{
0.5
T}
T{
footer
T}@T{
0.5
T}
.TE
.RE
.TP
\f[B]pageSetup\f[R] \f[I]sheet\f[R] \f[I]?\-option value \&...?\f[R]
Sets the page setup of the worksheet \f[I]sheet\f[R].
.RS
.PP
\f[B]Caveat\f[R]: If no page setup properties at all are set for a
sheet, applications use defaults derived from other sources.
But if at least one page setup property is explicitly set with this
method, the other properties not set will get the default value from the
specification, which may be another value than without any page setup at
all.
For example if you only set the \f[B]\-orientation\f[R] of a sheet then
this may also result in another page size (because the application page
size default may differ from the default recommended by the
specification, which is Letter paper).
.PP
The recognized options are:
.IP
.EX
  \-blackAndWhite boolean: Print black and white. Default:
  false.

  \-cellComments (none|asDisplayed|atEnd): How to print cell
  comments. Default: none.

  \-copies integer: Number of copies to print. Default: 1.

  \-draft boolean: Print without graphics. Default: false.

  \-errors (displayed|blank|dash|NA): How to print cell values
  of cells with errors. Default: displayed.

  \-firstPageNumber integer: Page number of the first printed
  page; see \-useFirstPageNumber. Default: 1.

  \-fitToHeight integer: Number of vertical pages to fit on.
  Default: 1.

  \-fitToWidth integer: Number of horizontal pages to fit on.
  Default: 1.

  \-horizontalDpi integer: Horizontal print resolution of the
  device. Default: 600.

  \-orientation (default|portrait|landscape): Orientation of the
  page. Default: default.

  \-pageOrder (downThenOver|overThenDown): Order of the printed
  pages. Default: downThenOver.

  \-paperHeight height: Height of custom paper as a number
  immediately followed by a unit identifier (as 297mm or 11in).
  No default.

  \-paperWidth width: Width of custom paper as a number
  immediately followed by a unit identifier (as 210mm or
  8.5in). No default.

  The specification says that when \-paperHeight and \-paperWidth
  are specified, the rendering application shall ignore
  \-paperSize.

  \-paperSize paperSizeID: Specifies the paper size. Default: 1
  (Letter). See PAPER SIZE IDS for the defined values; the
  behaviour for other values is implementation\-defined.

  \-scale integer: Print scaling in percent. The rendering
  application may respect only values ranging from 10 to 400.
  Overridden when \-fitToWidth and/or \-fitToHeight are in use.
  Default: 100.

  \-useFirstPageNumber boolean: Use the \-firstPageNumber value
  for the first page number and do not auto number the pages.
  Default: false.

  \-usePrinterDefaults boolean: Use the printer defaults (or the
  defaults of the print job).

  \-verticalDpi integer: Vertical print resolution of the
  device. Default: 600.
.EE
.PP
See PAPER SIZE IDS for the possible \f[B]\-paperSize\f[R] values.
.RE
.TP
\f[B]presetsheets\f[R] \f[I]arrayName\f[R]
Creates worksheets from an array previously read with
\f[I]::ooxml::xl_read\f[R], including their data.
The array is passed by name (without \f[CR]$\f[R]).
The sheets are created in their original order.
The method adds the key \f[I]sheetmap\f[R] to the array: a dict mapping
the original sheet index to the newly created worksheet handle.
Usually combined with \f[B]presetstyles\f[R]:
.RS
.IP
.EX
  array set workbook [::ooxml::xl_read original.xlsx]
  set spreadsheet [::ooxml::xl_write new]
  $spreadsheet presetstyles workbook
  $spreadsheet presetsheets workbook
.EE
.RE
.TP
\f[B]presetstyles\f[R] \f[I]arrayName\f[R]
Takes over the style definitions (number formats, fonts, fills, borders
and cell styles) from an array previously read with
\f[I]::ooxml::xl_read\f[R].
The array is passed by name (without \f[CR]$\f[R]).
.TP
\f[B]printarea\f[R] \f[I]sheet\f[R] \f[I]indexFrom\f[R] \f[I]indexTo\f[R]
Sets the print area of the worksheet \f[I]sheet\f[R], spanning from cell
\f[I]indexFrom\f[R] to cell \f[I]indexTo\f[R] (see CELL INDEX).
.RS
.IP
.EX
  $spreadsheet printarea $sheet A1 C3
  $spreadsheet printarea $sheet 1,1 2,2
.EE
.RE
.TP
\f[B]row\f[R] \f[I]sheet\f[R] \f[I]?\-option value \&...?\f[R]
Starts a new row in the worksheet \f[I]sheet\f[R] and returns the row
number.
Without the \f[B]\-index\f[R] option the next row is used; the column
autoincrement is reset (see CELL INDEX).
The recognized options are:
.RS
.IP
.EX
  \-index index: Row number to jump to.

  \-height height: Row height in points.
.EE
.RE
.TP
\f[B]rowheight\f[R] \f[I]sheet\f[R] \f[I]row\f[R] \f[I]height\f[R]
Sets the height of the given \f[I]row\f[R] (zero\-based) of the
worksheet \f[I]sheet\f[R] to \f[I]height\f[R] points, independently of
writing cells.
.RS
.IP
.EX
  $spreadsheet rowheight $sheet 33 20
.EE
.RE
.TP
\f[B]style\f[R] \f[I]?\-option value \&...?\f[R]
Defines a cell style for the current workbook and returns an ID
(STYLEID) to refer to that style.
The recognized options are:
.RS
.IP
.EX
  \-list: Returns the list of currently defined styles instead
  of a STYLEID.

  \-numfmt NUMFMTID: From the method numberformat.

  \-font FONTID: From the method font.

  \-fill FILLID: From the method fill.

  \-border BORDERID: From the method border.

  \-xf XFID: Base cell format record to derive from.

  \-horizontal alignment: Horizontal alignment of the cell
  content (e.g. left, center, right).

  \-vertical alignment: Vertical alignment of the cell content
  (e.g. top, center, bottom).

  \-rotate degree: Rotation of the cell content in degrees.

  \-wrap: Enables text wrapping within the cell.

  \-tag tagname: Gives the style a name. This name may be used
  instead of the returned STYLEID.
.EE
.RE
.TP
\f[B]view\f[R] \f[I]?\-option value \&...?\f[R]
Sets the workbook view properties.
The recognized options are:
.RS
.IP
.EX
  \-activetab tab: Zero\-based index of the worksheet shown when
  the file is opened.

  \-x twips \-y twips: Position of the workbook window.

  \-width twips \-height twips: Size of the workbook window.

  \-list: Returns the current view settings instead of setting
  them.
.EE
.RE
.TP
\f[B]worksheet\f[R] \f[I]name\f[R]
Creates a new worksheet with the given \f[I]name\f[R] and returns the
sheet handle (SHEETID) used as first argument by the cell related
methods.
The characters \f[CR]: \(rs / ? *\f[R] in the name are replaced and the
name is truncated to the 31 characters allowed by the format.
.TP
\f[B]write\f[R] \f[I]filename\f[R]
Writes the spreadsheet to the file \f[I]filename\f[R].
If the filename does not have the suffix .xlsx then it is appended.
If \f[I]filename\f[R] is empty, spreadsheetml.xlsx is used.
.SH RESULT ARRAY
\f[I]::ooxml::xl_read\f[R] returns a flat array.
In the following key table \f[I]S\f[R] stands for the zero\-based sheet
index and \f[I]R\f[R],\f[I]C\f[R] for the zero\-based row and column
index:
.PP
.TS
tab(@);
l l.
T{
Key
T}@T{
Content
T}
_
T{
sheets
T}@T{
List of the sheet indices that have been read
T}
T{
S,n
T}@T{
Worksheet name
T}
T{
S,max_row
T}@T{
Largest used row index of the worksheet
T}
T{
S,max_column
T}@T{
Largest used column index of the worksheet
T}
T{
S,v,R,C
T}@T{
Cell value (present for every non\-empty cell)
T}
T{
S,d,R,C
T}@T{
Raw date/time serial if the cell is a date cell
T}
T{
S,s,R,C
T}@T{
Style id of the cell
T}
T{
S,t,R,C
T}@T{
Cell type (\f[I]s\f[R] = shared string)
T}
T{
S,c,R,C
T}@T{
Cell position in Excel notation (e.g.\ B7)
T}
T{
S,f,R,C
T}@T{
Formula dict: keys \f[I]f\f[R] (formula), \f[I]i\f[R] (shared formula
index), \f[I]r\f[R] (shared formula range)
T}
T{
S,l,IDX
T}@T{
Hyperlink dict: keys \f[I]l\f[R] (target), \f[I]t\f[R] (tooltip)
T}
T{
S,k
T}@T{
Dict row \-> list of non\-empty columns (only with the \-keylist option)
T}
T{
S,filter
T}@T{
Autofilter ranges
T}
T{
S,freeze
T}@T{
Freeze pane position
T}
T{
S,merge
T}@T{
List of merged cell ranges
T}
T{
S,printarea
T}@T{
Print area range
T}
T{
S,rowheight
T}@T{
Row height settings
T}
T{
S,cols
T}@T{
Number of column definitions
T}
T{
S,col,N
T}@T{
Dict with the properties of column definition \f[I]N\f[R]
T}
T{
S,pageMargins
T}@T{
Page margin settings
T}
T{
S,pageSetup
T}@T{
Page setup settings
T}
T{
view
T}@T{
Workbook view settings
T}
T{
s,\&...
T}@T{
Style metadata (s,\(at s,styles,N s,fonts,N s,fills,N s,borders,N
s,numFmts,N s,numFmtsIds), consumed by \f[B]presetstyles\f[R] and
\f[B]presetsheets\f[R]
T}
.TE
.PP
With the \f[B]\-valuesonly\f[R] option only the \f[I]sheets\f[R],
\f[I]S,n\f[R], \f[I]S,max_row\f[R], \f[I]S,max_column\f[R] and
\f[I]S,v,R,C\f[R] keys are present.
.SH CELL INDEX
Methods and options expecting a cell position accept it in two
equivalent forms: numerically as \f[I]row,column\f[R] with zero\-based
row and column numbers, or in Excel notation (column letters followed by
the one\-based row number).
0,0 and A1 describe the same cell, 3,2 and C4 also.
.PP
The methods \f[B]row\f[R], \f[B]column\f[R] and \f[B]cell\f[R] work with
an autoincrement mechanism: without an explicit \f[B]\-index\f[R] option
\f[B]row\f[R] starts the next row, \f[B]cell\f[R] writes to the next
column of the current row and \f[B]column\f[R] defines the next column.
An explicit \f[B]\-index\f[R] repositions; the autoincrement continues
from there.
.IP
.EX
$spreadsheet row $sheet
$spreadsheet cell $sheet A           ;# 0,0
$spreadsheet cell $sheet B \-index 4  ;# 0,4 (columns 1\-3 stay empty)
$spreadsheet cell $sheet C           ;# 0,5
$spreadsheet row $sheet \-index 3     ;# jump to row 3
$spreadsheet cell $sheet D           ;# 3,0
.EE
.PP
For writing prefer the autoincrement wherever possible: call
\f[CR]$spreadsheet row $sheet\f[R] once per row and write the cells in
order without \f[B]\-index\f[R].
This avoids off\-by\-one and index bookkeeping errors.
.SH OPTION VALUE TYPES
Several option values share the same value types.
These types are:
.SS COLOR
There are several kinds of valid values:
.PP
The value may be \f[I]auto\f[R] or \f[I]none\f[R].
.PP
If not, the value may be the index number of a predefined color (an
integer between 0 and 65 including).
See the list below.
.PP
If not, the value may be the name of a predefined color.
Case is ignored.
See the list below.
.PP
If not, the value may be a 6 digit hexadecimal number, which is then
used as RGB value.
.PP
The list of predefined colors is:
.PP
.TS
tab(@);
l l l.
T{
Color ID
T}@T{
Name
T}@T{
(A)RGB
T}
_
T{
0
T}@T{
Black
T}@T{
00000000
T}
T{
1
T}@T{
White
T}@T{
00FFFFFF
T}
T{
2
T}@T{
Red
T}@T{
00FF0000
T}
T{
3
T}@T{
Lime
T}@T{
0000FF00
T}
T{
4
T}@T{
Blue
T}@T{
000000FF
T}
T{
5
T}@T{
Yellow
T}@T{
00FFFF00
T}
T{
6
T}@T{
Fuchsia
T}@T{
00FF00FF
T}
T{
7
T}@T{
Aqua
T}@T{
0000FFFF
T}
T{
8
T}@T{
Black
T}@T{
00000000
T}
T{
9
T}@T{
White
T}@T{
00FFFFFF
T}
T{
10
T}@T{
Red
T}@T{
00FF0000
T}
T{
11
T}@T{
Lime
T}@T{
0000FF00
T}
T{
12
T}@T{
Blue
T}@T{
000000FF
T}
T{
13
T}@T{
Yellow
T}@T{
00FFFF00
T}
T{
14
T}@T{
Fuchsia
T}@T{
00FF00FF
T}
T{
15
T}@T{
Aqua
T}@T{
0000FFFF
T}
T{
16
T}@T{
Maroon
T}@T{
00800000
T}
T{
17
T}@T{
Green
T}@T{
00008000
T}
T{
18
T}@T{
Navy
T}@T{
00000080
T}
T{
19
T}@T{
Olive
T}@T{
00808000
T}
T{
20
T}@T{
Purple
T}@T{
00800080
T}
T{
21
T}@T{
Teal
T}@T{
00008080
T}
T{
22
T}@T{
Silver
T}@T{
00C0C0C0
T}
T{
23
T}@T{
Gray
T}@T{
00808080
T}
T{
24
T}@T{
Portage
T}@T{
009999FF
T}
T{
25
T}@T{
Lipstick
T}@T{
00993366
T}
T{
26
T}@T{
Cream
T}@T{
00FFFFCC
T}
T{
27
T}@T{
LightCyan
T}@T{
00CCFFFF
T}
T{
28
T}@T{
Purple
T}@T{
00660066
T}
T{
29
T}@T{
LightCoral
T}@T{
00FF8080
T}
T{
30
T}@T{
NavyBlue
T}@T{
000066CC
T}
T{
31
T}@T{
LavenderBlue
T}@T{
00CCCCFF
T}
T{
32
T}@T{
Navy
T}@T{
00000080
T}
T{
33
T}@T{
Fuchsia
T}@T{
00FF00FF
T}
T{
34
T}@T{
Yellow
T}@T{
00FFFF00
T}
T{
35
T}@T{
Aqua
T}@T{
0000FFFF
T}
T{
36
T}@T{
Purple
T}@T{
00800080
T}
T{
37
T}@T{
Maroon
T}@T{
00800000
T}
T{
38
T}@T{
Teal
T}@T{
00008080
T}
T{
39
T}@T{
Blue
T}@T{
000000FF
T}
T{
40
T}@T{
DeepSkyBlue
T}@T{
0000CCFF
T}
T{
41
T}@T{
LightCyan
T}@T{
00CCFFFF
T}
T{
42
T}@T{
BlueRomance
T}@T{
00CCFFCC
T}
T{
43
T}@T{
Canary
T}@T{
00FFFF99
T}
T{
44
T}@T{
LightSkyBlue
T}@T{
0099CCFF
T}
T{
45
T}@T{
CarnationPink
T}@T{
00FF99CC
T}
T{
46
T}@T{
Mauve
T}@T{
00CC99FF
T}
T{
47
T}@T{
PeachOrange
T}@T{
00FFCC99
T}
T{
48
T}@T{
RoyalBlue
T}@T{
003366FF
T}
T{
49
T}@T{
MediumTurquoise
T}@T{
0033CCCC
T}
T{
50
T}@T{
Citrus
T}@T{
0099CC00
T}
T{
51
T}@T{
TangerineYellow
T}@T{
00FFCC00
T}
T{
52
T}@T{
OrangePeel
T}@T{
00FF9900
T}
T{
53
T}@T{
SafetyOrange
T}@T{
00FF6600
T}
T{
54
T}@T{
Scampi
T}@T{
00666699
T}
T{
55
T}@T{
Nobel
T}@T{
00969696
T}
T{
56
T}@T{
PrussianBlue
T}@T{
00003366
T}
T{
57
T}@T{
Eucalyptus
T}@T{
00339966
T}
T{
58
T}@T{
Myrtle
T}@T{
00003300
T}
T{
59
T}@T{
Karaka
T}@T{
00333300
T}
T{
60
T}@T{
SaddleBrown
T}@T{
00993300
T}
T{
61
T}@T{
Lipstick
T}@T{
00993366
T}
T{
62
T}@T{
DarkSlateBlue
T}@T{
00333399
T}
T{
63
T}@T{
NightRider
T}@T{
00333333
T}
T{
64
T}@T{
SystemForeground
T}@T{
n/a
T}
T{
65
T}@T{
SystemBackground
T}@T{
n/a
T}
.TE
.SS BORDERLINESTYLE
The list of possible values is:
.IP
.EX
dashDot
dashDotDot
dashed
dotted
double
hair
medium
mediumDashDot
mediumDashDotDot
none
slantDashDot
thick
thin
.EE
.SS PATTERNTYPE
An ECMA\-376 fill pattern type.
The usual values are:
.IP
.EX
none
solid
darkDown
darkGray
darkGrid
darkHorizontal
darkTrellis
darkUp
darkVertical
gray0625
gray125
lightDown
lightGray
lightGrid
lightHorizontal
lightTrellis
lightUp
lightVertical
mediumGray
.EE
.SS PAPER SIZE IDS
The possible \f[B]\-paperSize\f[R] values and their meaning are:
.PP
.TS
tab(@);
l l.
T{
Paper Size ID
T}@T{
Paper Size
T}
_
T{
1
T}@T{
Letter paper (8.5 in.
by 11 in.)
T}
T{
2
T}@T{
Letter small paper (8.5 in.
by 11 in.)
T}
T{
3
T}@T{
Tabloid paper (11 in.
by 17 in.)
T}
T{
4
T}@T{
Ledger paper (17 in.
by 11 in.)
T}
T{
5
T}@T{
Legal paper (8.5 in.
by 14 in.)
T}
T{
6
T}@T{
Statement paper (5.5 in.
by 8.5 in.)
T}
T{
7
T}@T{
Executive paper (7.25 in.
by 10.5 in.)
T}
T{
8
T}@T{
A3 paper (297 mm by 420 mm)
T}
T{
9
T}@T{
A4 paper (210 mm by 297 mm)
T}
T{
10
T}@T{
A4 small paper (210 mm by 297 mm)
T}
T{
11
T}@T{
A5 paper (148 mm by 210 mm)
T}
T{
12
T}@T{
B4 paper (250 mm by 353 mm)
T}
T{
13
T}@T{
B5 paper (176 mm by 250 mm)
T}
T{
14
T}@T{
Folio paper (8.5 in.
by 13 in.)
T}
T{
15
T}@T{
Quarto paper (215 mm by 275 mm)
T}
T{
16
T}@T{
Standard paper (10 in.
by 14 in.)
T}
T{
17
T}@T{
Standard paper (11 in.
by 17 in.)
T}
T{
18
T}@T{
Note paper (8.5 in.
by 11 in.)
T}
T{
19
T}@T{
#9 envelope (3.875 in.
by 8.875 in.)
T}
T{
20
T}@T{
#10 envelope (4.125 in.
by 9.5 in.)
T}
T{
21
T}@T{
#11 envelope (4.5 in.
by 10.375 in.)
T}
T{
22
T}@T{
#12 envelope (4.75 in.
by 11 in.)
T}
T{
23
T}@T{
#14 envelope (5 in.
by 11.5 in.)
T}
T{
24
T}@T{
C paper (17 in.
by 22 in.)
T}
T{
25
T}@T{
D paper (22 in.
by 34 in.)
T}
T{
26
T}@T{
E paper (34 in.
by 44 in.)
T}
T{
27
T}@T{
DL envelope (110 mm by 220 mm)
T}
T{
28
T}@T{
C5 envelope (162 mm by 229 mm)
T}
T{
29
T}@T{
C3 envelope (324 mm by 458 mm)
T}
T{
30
T}@T{
C4 envelope (229 mm by 324 mm)
T}
T{
31
T}@T{
C6 envelope (114 mm by 162 mm)
T}
T{
32
T}@T{
C65 envelope (114 mm by 229 mm)
T}
T{
33
T}@T{
B4 envelope (250 mm by 353 mm)
T}
T{
34
T}@T{
B5 envelope (176 mm by 250 mm)
T}
T{
35
T}@T{
B6 envelope (176 mm by 125 mm)
T}
T{
36
T}@T{
Italy envelope (110 mm by 230 mm)
T}
T{
37
T}@T{
Monarch envelope (3.875 in.
by 7.5 in.).
T}
T{
38
T}@T{
6 3/4 envelope (3.625 in.
by 6.5 in.)
T}
T{
39
T}@T{
US standard fanfold (14.875 in.
by 11 in.)
T}
T{
40
T}@T{
German standard fanfold (8.5 in.
by 12 in.)
T}
T{
41
T}@T{
German legal fanfold (8.5 in.
by 13 in.)
T}
T{
42
T}@T{
ISO B4 (250 mm by 353 mm)
T}
T{
43
T}@T{
Japanese double postcard (200 mm by 148 mm)
T}
T{
44
T}@T{
Standard paper (9 in.
by 11 in.)
T}
T{
45
T}@T{
Standard paper (10 in.
by 11 in.)
T}
T{
46
T}@T{
Standard paper (15 in.
by 11 in.)
T}
T{
47
T}@T{
Invite envelope (220 mm by 220 mm)
T}
T{
50
T}@T{
Letter extra paper (9.275 in.
by 12 in.)
T}
T{
51
T}@T{
Legal extra paper (9.275 in.
by 15 in.)
T}
T{
52
T}@T{
Tabloid extra paper (11.69 in.
by 18 in.)
T}
T{
53
T}@T{
A4 extra paper (236 mm by 322 mm)
T}
T{
54
T}@T{
Letter transverse paper (8.275 in.
by 11 in.)
T}
T{
55
T}@T{
A4 transverse paper (210 mm by 297 mm)
T}
T{
56
T}@T{
Letter extra transverse paper (9.275 in.
by 12 in.)
T}
T{
57
T}@T{
SuperA/SuperA/A4 paper (227 mm by 356 mm)
T}
T{
58
T}@T{
SuperB/SuperB/A3 paper (305 mm by 487 mm)
T}
T{
59
T}@T{
Letter plus paper (8.5 in.
by 12.69 in.)
T}
T{
60
T}@T{
A4 plus paper (210 mm by 330 mm)
T}
T{
61
T}@T{
A5 transverse paper (148 mm by 210 mm)
T}
T{
62
T}@T{
JIS B5 transverse paper (182 mm by 257 mm)
T}
T{
63
T}@T{
A3 extra paper (322 mm by 445 mm)
T}
T{
64
T}@T{
A5 extra paper (174 mm by 235 mm)
T}
T{
65
T}@T{
ISO B5 extra paper (201 mm by 276 mm)
T}
T{
66
T}@T{
A2 paper (420 mm by 594 mm)
T}
T{
67
T}@T{
A3 transverse paper (297 mm by 420 mm)
T}
T{
68
T}@T{
A3 extra transverse paper (322 mm by 445 mm)
T}
T{
69
T}@T{
Japanese Double Postcard (200 mm x 148 mm)
T}
T{
70
T}@T{
A6 (105 mm x 148 mm)
T}
T{
71
T}@T{
Japanese Envelope Kaku #2
T}
T{
72
T}@T{
Japanese Envelope Kaku #3
T}
T{
73
T}@T{
Japanese Envelope Chou #3
T}
T{
74
T}@T{
Japanese Envelope Chou #4
T}
T{
75
T}@T{
Letter Rotated (11 in x 8.5 in)
T}
T{
76
T}@T{
A3 Rotated (420 mm x 297 mm)
T}
T{
77
T}@T{
A4 Rotated (297 mm x 210 mm)
T}
T{
78
T}@T{
A5 Rotated (210 mm x 148 mm)
T}
T{
79
T}@T{
B4 (JIS) Rotated (364 mm x 257 mm)
T}
T{
80
T}@T{
B5 (JIS) Rotated (257 mm x 182 mm)
T}
T{
81
T}@T{
Japanese Postcard Rotated (148 mm x 100 mm)
T}
T{
82
T}@T{
Double Japanese Postcard Rotated (148 mm x 200 mm)
T}
T{
83
T}@T{
A6 Rotated (148 mm x 105 mm)
T}
T{
84
T}@T{
Japanese Envelope Kaku #2 Rotated
T}
T{
85
T}@T{
Japanese Envelope Kaku #3 Rotated
T}
T{
86
T}@T{
Japanese Envelope Chou #3 Rotated
T}
T{
87
T}@T{
Japanese Envelope Chou #4 Rotated
T}
T{
88
T}@T{
B6 (JIS) (128 mm x 182 mm)
T}
T{
89
T}@T{
B6 (JIS) Rotated (182 mm x 128 mm)
T}
T{
90
T}@T{
(12 in x 11 in)
T}
T{
91
T}@T{
Japanese Envelope You #4
T}
T{
92
T}@T{
Japanese Envelope You #4 Rotated
T}
T{
93
T}@T{
PRC 16K (146 mm x 215 mm)
T}
T{
94
T}@T{
PRC 32K (97 mm x 151 mm)
T}
T{
95
T}@T{
PRC 32K(Big) (97 mm x 151 mm)
T}
T{
96
T}@T{
PRC Envelope #1 (102 mm x 165 mm)
T}
T{
97
T}@T{
PRC Envelope #2 (102 mm x 176 mm)
T}
T{
98
T}@T{
PRC Envelope #3 (125 mm x 176 mm)
T}
T{
99
T}@T{
PRC Envelope #4 (110 mm x 208 mm)
T}
T{
100
T}@T{
PRC Envelope #5 (110 mm x 220 mm)
T}
T{
101
T}@T{
PRC Envelope #6 (120 mm x 230 mm)
T}
T{
102
T}@T{
PRC Envelope #7 (160 mm x 230 mm)
T}
T{
103
T}@T{
PRC Envelope #8 (120 mm x 309 mm)
T}
T{
104
T}@T{
PRC Envelope #9 (229 mm x 324 mm)
T}
T{
105
T}@T{
PRC Envelope #10 (324 mm x 458 mm)
T}
T{
106
T}@T{
PRC 16K Rotated
T}
T{
107
T}@T{
PRC 32K Rotated
T}
T{
108
T}@T{
PRC 32K(Big) Rotated
T}
T{
109
T}@T{
PRC Envelope #1 Rotated (165 mm x 102 mm)
T}
T{
110
T}@T{
PRC Envelope #2 Rotated (176 mm x 102 mm)
T}
T{
111
T}@T{
PRC Envelope #3 Rotated (176 mm x 125 mm)
T}
T{
112
T}@T{
PRC Envelope #4 Rotated (208 mm x 110 mm)
T}
T{
113
T}@T{
PRC Envelope #5 Rotated (220 mm x 110 mm)
T}
T{
114
T}@T{
PRC Envelope #6 Rotated (230 mm x 120 mm)
T}
T{
115
T}@T{
PRC Envelope #7 Rotated (230 mm x 160 mm)
T}
T{
116
T}@T{
PRC Envelope #8 Rotated (309 mm x 120 mm)
T}
T{
117
T}@T{
PRC Envelope #9 Rotated (324 mm x 229 mm)
T}
T{
118
T}@T{
PRC Envelope #10 Rotated (458 mm x 324 mm)
T}
.TE
.SH DEPENDENCIES
.IP
.EX
Tcl >= 8.6.7
tdom >= 0.9.0
.EE
.PP
Reading .xlsx files uses the zlib command built into Tcl and needs no
additional package.
Only if an archive cannot be handled by the built\-in reader
(e.g.\ ZIP64), one of the optional fallback backends is used: the Tcl 9
zipfs, tcllib\(cqs zipfile::decode or tclvfs vfs::zip >= 1.0.4.
