::ExcelTop, Main, Index

proc ::Excel::AddColumnChartSimple {worksheetId numRows numCols {title {}}} {

    # Add a clustered column chart to a worksheet. Simple case.
    #
    # worksheetId - Identifier of the worksheet.
    # numRows     - Number of rows beeing used for the chart.
    # numCols     - Number of columns beeing used for the chart.
    # title       - String used as title of the chart.
    #
    # Data for the x-axis is taken from column 1, starting at row 2.
    # Names for the lines are taken from row 1, starting at column 2.
    # The data range for the $numCols plots starts at (2, 2) and goes
    # to ($numRows+1, $numCols+1).
    #
    # Returns the identifier of the added chart.
    #
    # See also: CreateChart AddLineChart AddLineChartSimple AddPointChartSimple

    set chartId [Excel CreateChart $worksheetId $::Excel::xlColumnClustered]

    # Select the range of cells to be used as data.
    Excel SetChartSourceByIndex $chartId $worksheetId 2 2 [expr {$numRows+1}] [expr {$numCols+1}]

    set xrangeId [Excel SelectRangeByIndex $worksheetId 2 1 [expr {$numRows+1}] 1]
    for { set i 1 } { $i <= $numCols } { incr i } {
        set series [GetChartSeries $chartId $i]
        set name [Excel GetCellValue $worksheetId 1 [expr {$i +1}]]
        $series Name    $name
        $series XValues $xrangeId
        Cawt Destroy $series
    }
    Cawt Destroy $xrangeId

    # Set chart specific properties.
    # Switch on legend display.
    $chartId HasLegend True

    # Set the chart title string.
    Excel SetChartTitle $chartId $title

    # Do not fill the chart interior area. Better for printing.
    $chartId -with { PlotArea Interior } ColorIndex [expr $::Excel::xlColorIndexNone]

    # Set axis specific properties.
    set axis [$chartId -with { Axes } Item $::Excel::xlPrimary]
    # Set the display of major and minor gridlines.
    $axis HasMajorGridlines False
    $axis HasMinorGridlines False
    Cawt Destroy $axis

    set axis [$chartId -with { Axes } Item $::Excel::xlSecondary]
    # Set the display of major and minor gridlines.
    $axis HasMajorGridlines True
    $axis HasMinorGridlines False
    Cawt Destroy $axis

    return $chartId
}

proc ::Excel::AddLineChart {worksheetId headerRow xaxisCol startRow numRows startCol numCols {title {}} {yaxisName Values} {markerSize 5}} {

    # Add a line chart to a worksheet. Generic case.
    #
    # worksheetId - Identifier of the worksheet.
    # headerRow   - Row containing names for the lines.
    # xaxisCol    - Data for the x-axis is taken from this column.
    # startRow    - Starting row for data of x-axis.
    # numRows     - Number of rows used as data of x-axis.
    # startCol    - Column in header from which names start.
    # numCols     - Number of columns to use for the chart.
    # title       - String used as title of the chart.
    # yaxisName   - Name of y-axis.
    # markerSize  - Size of marker.
    #
    # The data range for the $numCols lines starts at ($startRow, $startCol)
    # and goes to ($startRow+$numRows-1, $startCol+$numCols-1).
    #
    # $markerSize must be between 2 and 72.
    #
    # Returns the identifier of the added chart.
    #
    # See also: CreateChart AddLineChartSimple AddPointChartSimple AddRadarChartSimple

    if { $markerSize < 2 || $markerSize > 72 } {
        error "AddLineChart: Valid marker size is between 2 and 72."
    }

    set chartId [Excel CreateChart $worksheetId $::Excel::xlLineMarkers]

    # Select the range of data.
    Excel SetChartSourceByIndex $chartId $worksheetId $startRow $startCol  [expr {$startRow+$numRows-1}] [expr {$startCol+$numCols-1}]

    # Select the column containing the data for the x-axis.
    set xrangeId [Excel SelectRangeByIndex $worksheetId $startRow $xaxisCol  [expr {$startRow+$numRows-1}] $xaxisCol]

    # Set the x-axis, name and marker size for each line.
    for { set i 1 } { $i <= $numCols } { incr i } {
        set series [GetChartSeries $chartId $i]
        set name   [Excel GetCellValue $worksheetId $headerRow [expr {$startCol+$i-1}]]
        $series Name       $name
        $series XValues    $xrangeId
        $series MarkerSize $markerSize
        Cawt Destroy $series
    }
    Cawt Destroy $xrangeId

    # Set the names for the x-axis and the y-axis.
    set axis [$chartId -with { Axes } Item $::Excel::xlPrimary]
    $axis HasTitle True
    $axis -with { AxisTitle Characters } Text  [Excel GetCellValue $worksheetId $headerRow $xaxisCol]
    Cawt Destroy $axis

    set axis [$chartId -with { Axes } Item $::Excel::xlSecondary]
    $axis HasTitle True
    $axis -with { AxisTitle Characters } Text $yaxisName
    Cawt Destroy $axis

    # Set the chart title.
    Excel SetChartTitle $chartId $title

    # Do not fill the chart interior area. Better for printing.
    $chartId -with { PlotArea Interior } ColorIndex [expr $::Excel::xlColorIndexNone]

    return $chartId
}

proc ::Excel::AddLineChartSimple {worksheetId numRows numCols {title {}} {yaxisName Values} {markerSize 5}} {

    # Add a line chart to a worksheet. Simple case.
    #
    # worksheetId - Identifier of the worksheet.
    # numRows     - Number of rows used as data of x-axis.
    # numCols     - Number of columns used as data of y-axis.
    # title       - String used as title of the chart.
    # yaxisName   - Name of y-axis.
    # markerSize  - Size of marker.
    #
    # Data for the x-axis is taken from column 1, starting at row 2.
    # Names for the lines are taken from row 1, starting at column 2.
    # The data range for the $numCols lines starts at (2, 2)
    # and goes to ($numRows+1, $numCols+1).
    #
    # Returns the identifier of the added chart.
    #
    # See also: CreateChart AddLineChart AddPointChartSimple AddRadarChartSimple

    return [Excel AddLineChart $worksheetId 1 1  2 $numRows  2 $numCols  $title $yaxisName $markerSize]
}

proc ::Excel::AddPointChartSimple {worksheetId numRows col1 col2 {title {}} {markerSize 5}} {

    # Add a point chart to a worksheet. Simple case.
    #
    # worksheetId - Identifier of the worksheet.
    # numRows     - Number of rows beeing used for the chart.
    # col1        - Start column of the chart data.
    # col2        - End column of the chart data.
    # title       - String used as title of the chart.
    # markerSize  - Size of the point marker.
    #
    # Data for the x-axis is taken from column $col1, starting at row 2.
    # Data for the y-axis is taken from column $col2, starting at row 2.
    # Names for the axes are taken from row 1, columns $col1 and $col2.
    #
    # Returns the identifier of the added chart.
    #
    # See also: CreateChart AddLineChart AddLineChartSimple AddRadarChartSimple

    set chartId [Excel CreateChart $worksheetId $::Excel::xlXYScatter]

    # Select the range of cells to be used as data.
    # Data of col1 is the X axis. Data of col2 is the Y axis.
    Excel SetChartSourceByIndex $chartId $worksheetId 2 $col2 [expr {$numRows+1}] $col2

    set series [GetChartSeries $chartId 1]
    set xrangeId [Excel SelectRangeByIndex $worksheetId 2 $col1 [expr {$numRows+1}] $col1]
    $series XValues    $xrangeId
    $series MarkerSize $markerSize
    Cawt Destroy $xrangeId
    Cawt Destroy $series

    # Set chart specific properties.
    # Switch of legend display.
    $chartId HasLegend False

    # Set the chart title string.
    Excel SetChartTitle $chartId $title

    # Do not fill the chart interior area. Better for printing.
    $chartId -with { PlotArea Interior } ColorIndex [expr $::Excel::xlColorIndexNone]

    # Set axis specific properties.
    # Set the X axis description to cell col1 in row 1.
    set axis [$chartId -with { Axes } Item $::Excel::xlPrimary]
    $axis HasTitle True
    $axis -with { AxisTitle Characters } Text [Excel GetCellValue $worksheetId 1 $col1]
    # Set the display of major and minor gridlines.
    $axis HasMajorGridlines True
    $axis HasMinorGridlines False
    Cawt Destroy $axis

    # Set the Y axis description to cell col2 in row 1.
    set axis [$chartId -with { Axes } Item $::Excel::xlSecondary]
    $axis HasTitle True
    $axis -with { AxisTitle Characters } Text [Excel GetCellValue $worksheetId 1 $col2]
    # Set the display of major and minor gridlines.
    $axis HasMajorGridlines True
    $axis HasMinorGridlines False
    Cawt Destroy $axis

    return $chartId
}

proc ::Excel::AddRadarChartSimple {worksheetId numRows numCols {title {}}} {

    # Add a radar chart to a worksheet. Simple case.
    #
    # worksheetId - Identifier of the worksheet.
    # numRows     - Number of rows beeing used for the chart.
    # numCols     - Number of columns beeing used for the chart.
    # title       - String used as title of the chart.
    #
    # Data for the x-axis is taken from column 1, starting at row 2.
    # Names for the lines are taken from row 1, starting at column 2.
    # The data range for the $numCols plots starts at (2, 2) and goes
    # to ($numRows+1, $numCols+1).
    #
    # Returns the identifier of the added chart.
    #
    # See also: CreateChart AddLineChart AddLineChartSimple AddPointChartSimple

    set chartId [Excel CreateChart $worksheetId $::Excel::xlRadarFilled]

    # Select the range of cells to be used as data.
    Excel SetChartSourceByIndex $chartId $worksheetId 2 2 [expr {$numRows+1}] [expr {$numCols+1}]

    set xrangeId [SelectRangeByIndex $worksheetId 2 1 [expr {$numRows+1}] 1]
    for { set i 1 } { $i <= $numCols } { incr i } {
        set series [GetChartSeries $chartId $i]
        set name [GetCellValue $worksheetId 1 [expr {$i +1}]]
        $series Name    $name
        $series XValues $xrangeId
        Cawt Destroy $series
    }
    Cawt Destroy $xrangeId

    # Set chart specific properties.
    # Switch on legend display.
    $chartId HasLegend True

    # Set the chart title string.
    Excel SetChartTitle $chartId $title

    # Do not fill the chart interior area. Better for printing.
    $chartId -with { PlotArea Interior } ColorIndex [expr $::Excel::xlColorIndexNone]

    # Set axis specific properties.
    set axis [$chartId -with { Axes } Item $::Excel::xlPrimary]
    # Set the display of major and minor gridlines.
    $axis HasMajorGridlines False
    $axis HasMinorGridlines False
    Cawt Destroy $axis

    set axis [$chartId -with { Axes } Item $::Excel::xlSecondary]
    # Set the display of major and minor gridlines.
    $axis HasMajorGridlines True
    $axis HasMinorGridlines False
    Cawt Destroy $axis

    return $chartId
}

proc ::Excel::AddSeriesTrendLine {seriesId args} {

    # Add a trend line to a series.
    #
    # seriesId - Identifier of the series.
    # args     - Options described below.
    #
    # -equation <bool>        - Set to true, if the equation for the trendline should be displayed
    #                           on the chart (in the same data label as the R-squared value).
    # -rsquared <bool>        - Set to true, if the R-squared for the trendline should be displayed
    #                           on the chart (in the same data label as the equation value).
    # -type <XlTrendlineType> - Set the trend line type. Typical values: `xlLinear`, `xlPolynomial`.
    # -order <int>            - Set the order ( > 1) of a polynomal trend line.
    #                           Only valid, if type is `xlPolynomal`.
    # -linewidth <size>       - Set the line width.
    # -linecolor <color>      - Set the line color.
    #
    # * Size values may be specified in a format acceptable by
    #   procedure [::Cawt::ValueToPoints], i.e. centimeters, inches or points.
    # * Color values may be specified in a format acceptable by procedure [::Cawt::GetColor],
    #   i.e. color name, hexadecimal string, Office color number.
    #
    # Returns the identifier of the trend line.
    #
    # See also: GetChartNumSeries GetChartSeries SetSeriesAttributes

    set trendId [$seriesId -with { Trendlines } Add]

    foreach { key value } $args {
        if { $value eq "" } {
            error "AddSeriesTrendLine: No value specified for key \"$key\""
        }
        switch -exact -nocase -- $key {
            "-equation"  { $trendId DisplayEquation [Cawt TclBool $value] }
            "-rsquared"  { $trendId DisplayRSquared [Cawt TclBool $value] }
            "-type"      { $trendId Type [Excel GetEnum $value] }
            "-order"     { $trendId Order [expr int($value)] }
            "-linewidth" { $trendId -with { Format Line } Weight [Cawt ValueToPoints $value] }
            "-linecolor" { $trendId -with { Format Line ForeColor } RGB [Cawt GetColor $value] }
            default      { error "AddSeriesTrendLine: Unknown key \"$key\" specified" }
        }

    }
    return $trendId
}

proc ::Excel::AddWorkbook {appId {type xlWBATWorksheet}} {

    # Add a new workbook with one worksheet.
    #
    # appId - Identifier of the Excel instance.
    # type  - Value of enumeration type [Enum::XlWBATemplate].
    #         Possible values: `xlWBATChart`, `xlWBATExcel4IntlMacroSheet`,
    #         `xlWBATExcel4MacroSheet`, `xlWBATWorksheet`.
    #
    # Returns the identifier of the new workbook.
    #
    # See also: OpenWorkbook Close SaveAs

    return [$appId -with { Workbooks } Add [Excel GetEnum $type]]
}

proc ::Excel::AddWorksheet {workbookId name args} {

    # Add a new worksheet to the end of a workbook.
    #
    # workbookId - Identifier of the workbook containing the new worksheet.
    # name       - Name of the new worksheet.
    # args       - Options described below.
    #
    # -visible <enum> - Value of enumeration type [Enum::XlSheetVisibility].
    #                   Possible values: `xlSheetVisible`, `xlSheetHidden`, `xlSheetVeryHidden`.
    #                   Default: `xlSheetVisible`.
    # -mapproc <proc> - Procedure for mapping worksheet names to Excel constraints.
    #                   Default: [MapWorksheetName]
    #                   See [MapWorksheetName] for mapping details.
    #
    # Returns the identifier of the new worksheet.
    #
    # See also: GetNumWorksheets DeleteWorksheet
    # SetWorksheetName MapWorksheetName

    set opts [dict create  -visible xlSheetVisible  -mapproc Excel::MapWorksheetName  ]
    if { [llength $args] == 1 } {
        # Old mode with optional parameter visibleType
        dict set opts -visible [lindex $args 0]
    } else {
        foreach { key value } $args {
            if { [dict exists $opts $key] } {
                if { $value eq "" } {
                    error "AddWorksheet: No value specified for key \"$key\"."
                }
                dict set opts $key $value
            } else {
                error "AddWorksheet: Unknown option \"$key\" specified."
            }
        }
    }

    set worksheets [$workbookId Worksheets]
    set lastWorksheetId [$worksheets Item [$worksheets Count]]
    set worksheetId [$worksheets -callnamedargs Add After $lastWorksheetId]
    Excel SetWorksheetName $worksheetId $name -mapproc [dict get $opts "-mapproc"]
    $worksheetId Visible [Excel GetEnum [dict get $opts "-visible"]]
    Cawt Destroy $lastWorksheetId
    Cawt Destroy $worksheets
    return $worksheetId
}

proc ::Excel::ArrangeWindows {appId {arrangeStyle xlArrangeStyleVertical}} {

    # Arrange the windows of an Excel application.
    #
    # appId        - Identifier of the Excel instance.
    # arrangeStyle - Value of enumeration type [Enum::XlArrangeStyle].
    #                Typical values are: `xlArrangeStyleHorizontal`,
    #                `xlArrangeStyleTiled`, `xlArrangeStyleVertical`.
    #
    # Returns no value.
    #
    # See also: Open Visible SetWindowState

    $appId -with { Windows } Arrange [Excel GetEnum $arrangeStyle]
}

proc ::Excel::ChartObjToClipboard {chartObjId} {

    # Copy a chart object to the clipboard.
    #
    # chartObjId - Identifier of the chart object.
    #
    # The chart object is stored in the clipboard as a Windows bitmap file (`CF_DIB`).
    #
    # Returns no value.
    #
    # See also: SaveChartObjAsImage CreateChart

    variable excelVersion

    # CopyPicture does not work with Excel 2007. It only copies
    # Metafiles into the clipboard.
    if { $excelVersion >= 12.0 } {
        set chartArea [$chartObjId ChartArea]
        $chartArea Copy
        Cawt Destroy $chartArea
    } else {
        $chartObjId CopyPicture $::Excel::xlScreen $::Excel::xlBitmap $::Excel::xlScreen
    }
}

proc ::Excel::ChartToClipboard {chartId} {

    # Obsolete: Replaced with [ChartObjToClipboard] in version 1.0.1

    Excel ChartObjToClipboard $chartId
}

proc ::Excel::ClipboardToMatrix {{sepChar {;}}} {

    # Return the matrix values contained in the clipboard.
    #
    # sepChar - The separation character of the clipboard matrix data.
    #
    # The clipboard data must be in `CSV` format with $sepChar as separation character.
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns the matrix values contained in the clipboard.
    #
    # See also: ClipboardToWorksheet MatrixToClipboard

    set csvFmt [twapi::register_clipboard_format "Csv"]
    while { ! [twapi::clipboard_format_available $csvFmt] } {
        after 10
    }
    twapi::open_clipboard
    set clipboardData [twapi::read_clipboard $csvFmt]
    twapi::close_clipboard

    Excel SetCsvSeparatorChar $sepChar
    set matrixList [Excel CsvStringToMatrix $clipboardData]
    return $matrixList
}

proc ::Excel::ClipboardToWorksheet {worksheetId {startRow 1} {startCol 1} {sepChar {;}}} {

    # Insert the matrix values contained in the clipboard into a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # startRow    - Row number. Row numbering starts with 1.
    # startCol    - Column number. Column numbering starts with 1.
    # sepChar     - The separation character of the clipboard matrix data.
    #
    # The insertion of the matrix data starts at cell "$startRow,$startCol".
    # The clipboard data must be in `CSV` format with $sepChar as separation character.
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns no value.
    #
    # See also: ClipboardToMatrix WorksheetToClipboard

    set matrixList [Excel ClipboardToMatrix $sepChar]
    Excel SetMatrixValues $worksheetId $matrixList $startRow $startCol
}

proc ::Excel::Close {workbookId} {

    # Close a workbook without saving changes.
    #
    # workbookId - Identifier of the workbook.
    #
    # Use the [SaveAs] method before closing, if you want to save changes.
    #
    # Returns no value.
    #
    # See also: SaveAs OpenWorkbook

    $workbookId Close [Cawt TclBool false]
}

proc ::Excel::ColumnCharToInt {colChar} {

    # Return an Excel column string as a column number.
    #
    # colChar - Column string.
    #
    # Example:
    #     [Excel ColumnCharToInt A] returns 1.
    #     [Excel ColumnCharToInt Z] returns 26.
    #
    # Returns the corresponding column number.
    #
    # See also: GetColumnNumber ColumnIntToChar

    set abc {- A B C D E F G H I J K L M N O P Q R S T U V W X Y Z}
    set int 0
    foreach char [split $colChar ""] {
        set int [expr {$int*26 + [lsearch $abc $char]}]
    }
    return $int
}

proc ::Excel::ColumnIntToChar {col} {

    # Return a column number as an Excel column string.
    #
    # col - Column number.
    #
    # Example:
    #     [Excel ColumnIntToChar 1]  returns "A".
    #     [Excel ColumnIntToChar 26] returns "Z".
    #
    # Returns the corresponding column string.
    #
    # See also: ColumnCharToInt

    if { $col <= 0 } {
        error "Column number $col is invalid."
    }
    set dividend $col
    set columnName ""
    while { $dividend > 0 } {
        set modulo [expr { ($dividend - 1) % 26 } ]
        set columnName [format "%c${columnName}" [expr { 65 + $modulo} ] ]
        set dividend [expr { ($dividend - $modulo) / 26 } ]
    }
    return $columnName
}

proc ::Excel::CopyColumn {fromWorksheetId fromCol toWorksheetId toCol {fromRow 1} {toRow 1} {pasteType xlPasteAll}} {

    # Copy the contents of a column into another column.
    #
    # fromWorksheetId - Identifier of the source worksheet.
    # fromCol         - Source column number. Column numbering starts with 1.
    # toWorksheetId   - Identifier of the destination worksheet.
    # toCol           - Destination column number. Column numbering starts with 1.
    # fromRow         - Start row of source column.
    # toRow           - Start row of destination column.
    # pasteType       - Value of enumeration type [Enum::XlPasteType].
    #                   Typical values are: `xlPasteAll`, `xlPasteAllExceptBorders`, `xlPasteValues`.
    #
    # Note, that the contents of the destination column are overwritten.
    #
    # Returns no value.
    #
    # See also: CopyRange CopyWorksheet

    set numRows     [Excel GetNumUsedRows $fromWorksheetId]
    set fromRangeId [Excel SelectRangeByIndex $fromWorksheetId  $fromRow $fromCol  [expr {$numRows + $fromRow -1}] $fromCol]
    set toRangeId   [Excel SelectRangeByIndex $toWorksheetId  $toRow $toCol  [expr {$numRows + $toRow -1}] $toCol]
    Excel CopyRange $fromRangeId $toRangeId
    Cawt Destroy $fromRangeId
    Cawt Destroy $toRangeId
}

proc ::Excel::CopyRange {fromRangeId toRangeId {pasteType xlPasteAll}} {

    # Copy the contents of a cell range into another cell range.
    #
    # fromRangeId - Identifier of the source range.
    # toRangeId   - Identifier of the destination range.
    # pasteType   - Value of enumeration type [Enum::XlPasteType].
    #               Typical values are: `xlPasteAll`, `xlPasteAllExceptBorders`, `xlPasteValues`.
    #
    # Note, that the contents of the destination range are overwritten.
    #
    # Returns no value.
    #
    # See also: SelectAll CopyWorksheet CopyColumn

    $fromRangeId Copy
    $toRangeId PasteSpecial [Excel GetEnum $pasteType]
}

proc ::Excel::CopyWorksheet {fromWorksheetId toWorksheetId} {

    # Copy the contents of a worksheet into another worksheet.
    #
    # fromWorksheetId - Identifier of the source worksheet.
    # toWorksheetId   - Identifier of the destination worksheet.
    #
    # Note, that the contents of worksheet $toWorksheetId are overwritten.
    #
    # Returns no value.
    #
    # See also: SelectAll CopyWorksheetBefore CopyWorksheetAfter AddWorksheet

    $fromWorksheetId Activate
    set rangeId [Excel SelectAll $fromWorksheetId]
    $rangeId Copy

    $toWorksheetId Activate
    $toWorksheetId Paste

    Cawt Destroy $rangeId
}

proc ::Excel::CopyWorksheetAfter {fromWorksheetId afterWorksheetId {worksheetName {}}} {

    # Copy the contents of a worksheet after another worksheet.
    #
    # fromWorksheetId  - Identifier of the source worksheet.
    # afterWorksheetId - Identifier of the destination worksheet.
    # worksheetName    - Name of the new worksheet. If no name is specified,
    #                    or an empty string, the naming is done by Excel.
    #
    # Instead of using the identifier of $afterWorksheetId, it is also possible
    # to use the numeric index or the special word `end` for specifying the
    # last worksheet.
    #
    # Note, that a new worksheet is generated after worksheet $afterWorksheetId,
    # while [CopyWorksheet] overwrites the contents of an existing worksheet.
    # The new worksheet is set as the active sheet.
    #
    # Returns the identifier of the new worksheet.
    #
    # See also: SelectAll CopyWorksheet CopyWorksheetBefore AddWorksheet

    set fromWorkbookId  [$fromWorksheetId  Parent]
    set afterWorkbookId [$afterWorksheetId Parent]

    if { $afterWorksheetId eq "end" } {
        set afterWorksheetId [Excel GetWorksheetIdByIndex $fromWorkbookId "end"]
    } elseif { [string is integer $afterWorksheetId] } {
        set index [expr int($afterWorksheetId)]
        set afterWorksheetId [Excel GetWorksheetIdByIndex $fromWorkbookId ]
    }

    $fromWorksheetId -callnamedargs Copy After $afterWorksheetId

    set afterName [Excel GetWorksheetName $afterWorksheetId]
    set afterWorksheetIndex [Excel GetWorksheetIndexByName $afterWorkbookId $afterName]
    set newWorksheetIndex [expr { $afterWorksheetIndex + 1 }]
    set newWorksheetId [Excel GetWorksheetIdByIndex $afterWorkbookId $newWorksheetIndex]

    if { $worksheetName ne "" } {
        Excel SetWorksheetName $newWorksheetId $worksheetName
    }
    $newWorksheetId Activate

    Cawt Destroy $afterWorkbookId
    Cawt Destroy $fromWorkbookId
    return $newWorksheetId
}

proc ::Excel::CopyWorksheetBefore {fromWorksheetId beforeWorksheetId {worksheetName {}}} {

    # Copy the contents of a worksheet before another worksheet.
    #
    # fromWorksheetId   - Identifier of the source worksheet.
    # beforeWorksheetId - Identifier of the destination worksheet.
    # worksheetName     - Name of the new worksheet. If no name is specified,
    #                     or an empty string, the naming is done by Excel.
    #
    # Instead of using the identifier of $beforeWorksheetId, it is also possible
    # to use the numeric index or the special word `end` for specifying the
    # last worksheet.
    #
    # Note, that a new worksheet is generated before worksheet $beforeWorksheetId,
    # while [CopyWorksheet] overwrites the contents of an existing worksheet.
    # The new worksheet is set as the active sheet.
    #
    # Returns the identifier of the new worksheet.
    #
    # See also: SelectAll CopyWorksheet CopyWorksheetAfter AddWorksheet

    set fromWorkbookId   [$fromWorksheetId   Parent]
    set beforeWorkbookId [$beforeWorksheetId Parent]

    if { $beforeWorksheetId eq "end" } {
        set beforeWorksheetId [Excel GetWorksheetIdByIndex $fromWorkbookId "end"]
    } elseif { [string is integer $beforeWorksheetId] } {
        set index [expr int($beforeWorksheetId)]
        set beforeWorksheetId [Excel GetWorksheetIdByIndex $fromWorkbookId ]
    }

    $fromWorksheetId -callnamedargs Copy Before $beforeWorksheetId

    set beforeName [Excel GetWorksheetName $beforeWorksheetId]
    set beforeWorksheetIndex [Excel GetWorksheetIndexByName $beforeWorkbookId $beforeName]
    set newWorksheetIndex [expr { $beforeWorksheetIndex - 1 }]
    set newWorksheetId [Excel GetWorksheetIdByIndex $beforeWorkbookId $newWorksheetIndex]

    if { $worksheetName ne "" } {
        Excel SetWorksheetName $newWorksheetId $worksheetName
    }
    $newWorksheetId Activate

    Cawt Destroy $beforeWorkbookId
    Cawt Destroy $fromWorkbookId
    return $newWorksheetId
}

proc ::Excel::CreateChart {worksheetId chartType} {

    # Create a new empty chart in a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # chartType   - Value of enumeration type [Enum::XlChartType].
    #
    # Returns the identifier of the new chart.
    #
    # See also: PlaceChart AddLineChart AddLineChartSimple AddPointChartSimple AddRadarChartSimple

    set cellsId [Excel GetCellsId $worksheetId]
    set appId [Office GetApplicationId $cellsId]

    switch [Excel GetVersion $appId] {
        "12.0" {
            set chartId [[[$worksheetId Shapes] AddChart [Excel GetEnum $chartType]] Chart]
        }
        default {
            set chartId [$appId -with { Charts } Add]
            $chartId ChartType $chartType
        }
    }
    Cawt Destroy $cellsId
    Cawt Destroy $appId
    return $chartId
}

proc ::Excel::CreateRangeString {args} {

    # Create a range string in A1 notation.
    #
    # args - List of quadruples specifying cell ranges.
    #
    # The first two elements of each quadruple represent the row and column indices of the top-left cell of each range.
    # The last two elements of each quadruple represent the row and column indices of the bottom-right cell of the range.
    #
    # Note, that the list item separator is taken from locale settings of Windows.
    # Using US English versions, this is typically `,`, in other countries `;`.
    #
    # Example:
    #      CreateRangeString 1 1 2 3  4 2 6 3 returns A1:C2;B4:C6
    #
    # Returns range string in A1 notation.
    #
    # See also: SelectRangeByIndex SelectRangeByString GetListItemSeparator SetListItemSeparator

    set numEntries [llength $args]
    if { $numEntries % 4 != 0 } {
        error "CreateRangeString: Number of parameters must be divisible by four."
    }
    set numRanges [expr { $numEntries / 4 }]
    set ind 0
    foreach { row1 col1 row2 col2 } $args {
        set rangeStr [Excel GetCellRange $row1 $col1 $row2 $col2]
        append extendedRangeStr $rangeStr
        if { $ind != $numRanges-1 } {
            append extendedRangeStr [Excel::GetListItemSeparator]
        }
        incr ind
    }
    return $extendedRangeStr
}

proc ::Excel::CsvRowToList {rowStr} {

    # Return a `CSV` encoded row as a list of column values.
    #
    # rowStr - `CSV` encoded row as string.
    #
    # Returns the `CSV` encoded row as a list of column values.
    #
    # See also: ListToCsvRow

    variable sSepChar

    set tmpList {}
    set wordCount 1
    set combine 0

    set wordList [split $rowStr $sSepChar]

    foreach word $wordList {
        set len [string length $word]
        if { [string index $word end] eq "\"" } {
            set endQuote 1
        } else {
            set endQuote 0
        }
        if { [string index $word 0] eq "\"" } {
            set begQuote 1
        } else {
            set begQuote 0
        }

        if { $begQuote && $endQuote && ($len % 2 == 1) } {
            set onlyQuotes [regexp {^[\"]+$} $word]
            if { $onlyQuotes } {
                if { $combine } {
                    set begQuote 0
                } else {
                    set endQuote 0
                }
            }
        }
        if { $begQuote && $endQuote && ($len == 2) } {
            set begQuote 0
            set endQuote 0
        }

        if { $begQuote && $endQuote } {
            lappend tmpList [string map {\"\" \"} [string range $word 1 end-1]]
            set combine 0
            incr wordCount
        } elseif { !$begQuote && $endQuote } {
            append tmpWord [string range $word 0 end-1]
            lappend tmpList [string map {\"\" \"} $tmpWord]
            set combine 0
            incr wordCount
        } elseif { $begQuote && !$endQuote } {
            set tmpWord [string range $word 1 end]
            append tmpWord $sSepChar
            set combine 1
        } else {
            if { $combine } {
                append tmpWord  [string map {\"\" \"} $word]
                append tmpWord $sSepChar
            } else {
               lappend tmpList [string map {\"\" \"} $word]
               set combine 0
               incr wordCount
            }
        }
    }
    return $tmpList
}

proc ::Excel::CsvStringToMatrix {csvString} {

    # Return a matrix from a `CSV` encoded table string.
    #
    # csvString - `CSV` encoded table as string.
    #
    # Returns the matrix from the `CSV` encoded table string.
    #
    # See also: MatrixToCsvString CsvRowToList

    set trimString [string trim $csvString '\0''\n']
    foreach row [lrange [split $trimString "\n"] 0 end] {
        set row [string trim $row "\r"]
        lappend matrixList [Excel CsvRowToList $row]
    }
    return $matrixList
}

proc ::Excel::DeleteColumn {worksheetId col} {

    # Delete a column.
    #
    # worksheetId - Identifier of the worksheet.
    # col         - Column number. Column numbering starts with 1.
    #
    # The specified column is deleted.
    #
    # Returns no value.
    #
    # See also: InsertColumn DuplicateColumn HideColumn DeleteRow DeleteWorksheet

    set cell [Excel SelectCellByIndex $worksheetId 1 $col]
    $cell -with { EntireColumn } Delete $::Excel::xlShiftToLeft
    Cawt Destroy $cell
}

proc ::Excel::DeleteRow {worksheetId row} {

    # Delete a row.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    #
    # The specified row is deleted.
    #
    # Returns no value.
    #
    # See also: InsertRow DuplicateRow HideRow DeleteColumn DeleteWorksheet

    set cell [Excel SelectCellByIndex $worksheetId $row 1]
    $cell -with { EntireRow } Delete $::Excel::xlShiftUp
    Cawt Destroy $cell
}

proc ::Excel::DeleteWorksheet {workbookId worksheetId} {

    # Delete a worksheet.
    #
    # workbookId  - Identifier of the workbook containing the worksheet.
    # worksheetId - Identifier of the worksheet to delete.
    #
    # If the number of worksheets before deletion is 1, an error is thrown.
    #
    # Returns no value.
    #
    # See also: DeleteWorksheetByIndex GetWorksheetIdByIndex AddWorksheet

    set count [$workbookId -with { Worksheets } Count]

    if { $count == 1 } {
        error "DeleteWorksheet: Cannot delete last worksheet."
    }

    # Delete the specified worksheet.
    # This will cause alert dialogs to be displayed unless
    # they are turned off.
    set appId [Office GetApplicationId $workbookId]
    Excel::ShowAlerts $appId false
    $worksheetId Delete
    # Turn the alerts back on.
    Excel::ShowAlerts $appId true
    Cawt Destroy $appId
}

proc ::Excel::DeleteWorksheetByIndex {workbookId index} {

    # Delete a worksheet identified by its index.
    #
    # workbookId - Identifier of the workbook containing the worksheet.
    # index      - Index of the worksheet to delete.
    #
    # Returns no value.
    #
    # The left-most worksheet has index 1.
    # If the index is out of bounds, or the number of worksheets before deletion is 1,
    # an error is thrown.
    #
    # See also: GetNumWorksheets GetWorksheetIdByIndex AddWorksheet

    set count [Excel GetNumWorksheets $workbookId]

    if { $count == 1 } {
        error "DeleteWorksheetByIndex: Cannot delete last worksheet."
    }
    if { $index < 1 || $index > $count } {
        error "DeleteWorksheetByIndex: Invalid index $index given."
    }
    # Delete the specified worksheet.
    # This will cause alert dialogs to be displayed unless
    # they are turned off.
    set appId [Office GetApplicationId $workbookId]
    Excel::ShowAlerts $appId false
    set worksheetId [$workbookId -with { Worksheets } Item [expr $index]]
    $worksheetId Delete
    # Turn the alerts back on.
    Excel::ShowAlerts $appId true
    Cawt Destroy $worksheetId
    Cawt Destroy $appId
}

proc ::Excel::DiffExcelFiles {excelBaseFile excelNewFile args} {

    # Compare two Excel files visually.
    #
    # excelBaseFile - Name of the base Excel file.
    # excelNewFile  - Name of the new Excel file.
    # args          - Mark color.
    #
    # The two Excel files are opened in read-only mode and the cells,
    # which are different in the two Excel files are set to the mark color.
    # As Excel does not allow to load two files with identical names (even
    # from different directories), in that case the $excelBaseFile is copied
    # into a temporary directory and renamed.
    #
    # The algorithm used is identical to the Excel diff script used in Tortoise SVN.
    #
    # Color value may be specified in a format acceptable by procedure [::Cawt::GetColor],
    # i.e. color name, hexadecimal string, Office color number or a list of 3 integer RGB values.
    # If no mark color is specified, it is set to red.
    #
    # Returns the identifier of the new Excel application instance.
    #
    # See also: OpenNew

    set fastMode false

    if { ! [file exists $excelBaseFile] } {
        error "DiffExcelFiles: Base file $excelBaseFile does not exists"
    }
    if { ! [file exists $excelNewFile] } {
        error "DiffExcelFiles: New file $excelNewFile does not exists"
    }
    if { [file normalize $excelBaseFile] eq [file normalize $excelNewFile] } {
        error "DiffExcelFiles: Base and new file are equal. Cannot compare."
    }
    if { [file tail $excelBaseFile] eq [file tail $excelNewFile] } {
        set tailName  [file tail $excelBaseFile]
        set rootName  [file rootname $tailName]
        set extension [file extension $tailName]
        set tmpName   [format "%s_BaseTmp%s" $rootName $extension]
        set tmpName   [file join [Cawt GetTmpDir] $tmpName]
        file copy -force $excelBaseFile $tmpName
        set excelBaseFile $tmpName
    }
    set appId [Excel OpenNew true]
    set baseWorkbookId [Excel OpenWorkbook $appId [file nativename $excelBaseFile] -readonly true]
    set newWorkbookId  [Excel OpenWorkbook $appId [file nativename $excelNewFile]  -readonly true]
    if { [Excel IsWorkbookProtected $baseWorkbookId] } {
        error "DiffExcelFiles: Unable to arrange windows, because $excelBaseFile is protected."
    }
    if { [Excel IsWorkbookProtected $newWorkbookId] } {
        error "DiffExcelFiles: Unable to arrange windows, because $excelNewFile is protected."
    }

    set winId [$appId -with { Windows } Item [expr 2]]
    set caption [$winId Caption]
    $appId -with { Windows } CompareSideBySideWith $caption
    Excel SetWindowState $appId $::Excel::xlMaximized
    Excel ArrangeWindows $appId $::Excel::xlArrangeStyleHorizontal
    if { ! $fastMode && [Excel IsWorkbookProtected $newWorkbookId] } {
        puts "Fall back to fast mode because [Excel GetWorkbookName $newWorkbookId] is protected."
        set fastMode true
    }
    Cawt Destroy $winId

    # Create a special workbook for formula convertion.
    set convWorkbookId [Excel AddWorkbook $appId]

    if { [llength $args] == 0 } {
        set markColor [Cawt GetColor "red"]
    } else {
        set markColor [Cawt GetColor {*}$args]
    }
    set numWorksheets [Excel GetNumWorksheets $newWorkbookId]
    for { set i 1 } { $i <= $numWorksheets } { incr i } {
        set baseWorksheetId [Excel GetWorksheetIdByIndex $baseWorkbookId $i]
        set newWorksheetId  [Excel GetWorksheetIdByIndex $newWorkbookId  $i]

        Excel UnhideWorksheet $baseWorksheetId
        Excel UnhideWorksheet $newWorksheetId
        Excel SetWorksheetTabColor $baseWorksheetId 0 128 0
        Excel SetWorksheetTabColor $newWorksheetId  0 128 0

        if { ! $fastMode } {
            set lastWorksheetId [Excel GetWorksheetIdByIndex $newWorkbookId [Excel GetNumWorksheets $newWorkbookId]]
            set dummyWorksheetId [Excel CopyWorksheetAfter $baseWorksheetId $lastWorksheetId "Dummy_for_Comparison_$i"]
            $dummyWorksheetId Visible [expr $::Excel::xlSheetVisible]
            Excel SetWorksheetTabColor $dummyWorksheetId 127 127 255
            Cawt Destroy $dummyWorksheetId
            Cawt Destroy $lastWorksheetId
        }

        if { [Excel IsWorksheetProtected $newWorksheetId] } {
            error "DiffExcelFiles: Unable to mark differences because the Worksheet is protected."
        } else {
            $newWorksheetId -with { Cells FormatConditions } Delete

            if { $fastMode } {
                set formula [format "=INDIRECT(\"%s!\"&ADDRESS(ROW(),COLUMN()))" [Excel::_ToAbsoluteReference $baseWorksheetId]]
            } else {
                set formula [format "=INDIRECT(\"Dummy_for_Comparison_%d!\"&ADDRESS(ROW(),COLUMN()))" $i]
            }
            set formula [Excel::_ConvertFormula $convWorkbookId $formula]
            $newWorksheetId -with { Cells FormatConditions } Add $::Excel::xlCellValue $::Excel::xlNotEqual $formula
            set formatCondition [$newWorksheetId -with { Cells FormatConditions } Item 1]
            $formatCondition -with { Interior } Color $markColor
            Cawt Destroy $formatCondition
        }
        Cawt Destroy $newWorksheetId
        Cawt Destroy $baseWorksheetId
    }

    # Close the special workbook quietly
    $convWorkbookId Saved [Cawt TclBool true]
    $convWorkbookId Close

    # Activate first Worksheet
    Excel GetWorksheetIdByIndex $baseWorkbookId 1 true
    Excel GetWorksheetIdByIndex $newWorkbookId  1 true

    # Suppress save dialog if nothing changed
    $baseWorkbookId Saved [Cawt TclBool true]
    $newWorkbookId  Saved [Cawt TclBool true]

    return $appId
}

proc ::Excel::DuplicateColumn {worksheetId col} {

    # Duplicate a column.
    #
    # worksheetId - Identifier of the worksheet.
    # col         - Column number. Column numbering starts with 1.
    #
    # The specified column is duplicated with formatting and formulas.
    #
    # Returns no value.
    #
    # See also: InsertColumn DeleteColumn HideColumn DuplicateRow

    set cell [Excel SelectCellByIndex $worksheetId 1 $col]
    $cell -with { EntireColumn } Copy
    Cawt Destroy $cell

    set cell [Excel SelectCellByIndex $worksheetId 1 [expr {$col + 1}]]
    $cell -with { EntireColumn } Insert $::Excel::xlToRight
    Cawt Destroy $cell
}

proc ::Excel::DuplicateRow {worksheetId row} {

    # Duplicate a row.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    #
    # The specified row is duplicated with formatting and formulas.
    #
    # Returns no value.
    #
    # See also: InsertRow DeleteRow HideRow DuplicateColumn

    set cell [Excel SelectCellByIndex $worksheetId $row 1]
    $cell -with { EntireRow } Copy
    Cawt Destroy $cell

    set cell [Excel SelectCellByIndex $worksheetId [expr {$row + 1}] 1]
    $cell -with { EntireRow } Insert $::Excel::xlUp
    Cawt Destroy $cell
}

proc ::Excel::ExcelFileToHtmlFile {excelFileName htmlFileName args} {

    # Convert an Excel file to a HTML table file.
    #
    # excelFileName - Name of the Excel input file.
    # htmlFileName  - Name of the HTML output file.
    # args          - Options described below.
    #
    # -worksheet <int> - Set the worksheet name or index to convert.
    #                    Default value: 0
    # -quit <bool>     - Set to true to quit the Excel instance after generation of output file.
    #                    Otherwise leave the Excel instance open after generation of output file.
    #                    Default value: true.
    # -target <bool>   - Set to true to generate a target attribute for hyperlinks.
    #                    Otherwise no target attribute for hyperlinks, i.e. link opens in same tab.
    #                    Default value: true.
    #
    # Note, that the Excel Workbook is opened in read-only mode.
    #
    # Returns the Excel application identifier, if `-quit` is false.
    # Otherwise no return value.
    #
    # See also: WorksheetToHtmlFile WriteHtmlFile MediaWikiFileToExcelFile WikitFileToExcelFile

    set opts [dict create  -worksheet 0  -quit      true  -target    true  ]
    foreach { key value } $args {
        if { $value eq "" } {
            error "ExcelFileToHtmlFile: No value specified for key \"$key\""
        }
        if { [dict exists $opts $key] } {
            dict set opts $key $value
        } else {
            error "ExcelFileToHtmlFile: Unknown option \"$key\" specified"
        }
    }

    set worksheetNameOrIndex [dict get $opts "-worksheet"]

    set appId [Excel OpenNew true]
    set workbookId [Excel OpenWorkbook $appId $excelFileName -readonly true]
    if { [string is integer $worksheetNameOrIndex] } {
        set worksheetId [Excel GetWorksheetIdByIndex $workbookId [expr int($worksheetNameOrIndex)]]
    } else {
        set worksheetId [Excel GetWorksheetIdByName $workbookId $worksheetNameOrIndex]
    }
    Excel WorksheetToHtmlFile $worksheetId $htmlFileName [dict get $opts "-target"]
    if { [dict get $opts "-quit"] } {
        Excel Quit $appId
    } else {
        return $appId
    }
}

proc ::Excel::ExcelFileToMatlabFile {excelFileName matFileName {worksheetNameOrIndex 0} {useHeader true} {quitExcel true}} {

    # Convert an Excel file to a Matlab table file.
    #
    # excelFileName        - Name of the Excel input file.
    # matFileName          - Name of the Matlab output file.
    # worksheetNameOrIndex - Worksheet name or index to convert.
    # useHeader            - If set to true, use the first row of the worksheet as the header
    #                        of the Matlab file.
    #                        Otherwise do not generate a Matlab file header. All worksheet
    #                        cells are interpreted as data.
    # quitExcel            - If set to true, quit the Excel instance after generation of output file.
    #                        Otherwise leave the Excel instance open after generation of output file.
    #
    # Note, that the Excel Workbook is opened in read-only mode.
    #
    # **Note:** Only Matlab Level 4 files are currently supported.
    #
    # Returns the Excel application identifier, if $quitExcel is false.
    # Otherwise no return value.
    #
    # See also: MatlabFileToWorksheet MatlabFileToExcelFile
    # ReadMatlabFile WriteMatlabFile

    set appId [Excel OpenNew true]
    set workbookId [Excel OpenWorkbook $appId $excelFileName -readonly true]
    if { [string is integer $worksheetNameOrIndex] } {
        set worksheetId [Excel GetWorksheetIdByIndex $workbookId [expr int($worksheetNameOrIndex)]]
    } else {
        set worksheetId [Excel GetWorksheetIdByName $workbookId $worksheetNameOrIndex]
    }
    Excel WorksheetToMatlabFile $worksheetId $matFileName $useHeader
    if { $quitExcel } {
        Excel Quit $appId
    } else {
        return $appId
    }
}

proc ::Excel::ExcelFileToMediaWikiFile {excelFileName wikiFileName {worksheetNameOrIndex 1} {useHeader true} {quitExcel true}} {

    # Convert an Excel file to a MediaWiki table file.
    #
    # excelFileName        - Name of the Excel input file.
    # wikiFileName         - Name of the MediaWiki output file.
    # worksheetNameOrIndex - Worksheet name or index to convert.
    # useHeader            - If set to true, use the first row of the worksheet as the header
    #                        of the MediaWiki table.
    #                        Otherwise do not generate a MediaWiki table header. All worksheet
    #                        cells are interpreted as data.
    # quitExcel            - If set to true, quit the Excel instance after generation of output file.
    #                        Otherwise leave the Excel instance open after generation of output file.
    #
    # Note, that the Excel Workbook is opened in read-only mode.
    #
    # Returns the Excel application identifier, if $quitExcel is false.
    # Otherwise no return value.
    #
    # See also: MediaWikiFileToWorksheet MediaWikiFileToExcelFile
    # ReadMediaWikiFile WriteMediaWikiFile WikitFileToExcelFile

    set appId [Excel OpenNew true]
    set workbookId [Excel OpenWorkbook $appId $excelFileName -readonly true]
    if { [string is integer $worksheetNameOrIndex] } {
        set worksheetId [Excel GetWorksheetIdByIndex $workbookId [expr int($worksheetNameOrIndex)]]
    } else {
        set worksheetId [Excel GetWorksheetIdByName $workbookId $worksheetNameOrIndex]
    }
    Excel WorksheetToMediaWikiFile $worksheetId $wikiFileName $useHeader
    if { $quitExcel } {
        Excel Quit $appId
    } else {
        return $appId
    }
}

proc ::Excel::ExcelFileToRawImageFile {excelFileName rawFileName {worksheetNameOrIndex 0} {useHeader true} {quitExcel true} {pixelType float}} {

    # Convert an Excel file to a raw photo image file.
    #
    # excelFileName        - Name of the Excel input file.
    # rawFileName          - Name of the image output file.
    # worksheetNameOrIndex - Worksheet name or index to convert.
    # useHeader            - If set to true, use the first row of the worksheet as the header
    #                        of the raw image file.
    #                        Otherwise do not generate a raw image file header. All worksheet
    #                        cells are interpreted as data.
    # quitExcel            - If set to true, quit the Excel instance after generation of output file.
    #                        Otherwise leave the Excel instance open after generation of output file.
    # pixelType            - Pixel type: `byte`, `short`, `float`.
    #
    # Note, that the Excel Workbook is opened in read-only mode.
    #
    # Returns the Excel application identifier, if $quitExcel is false.
    # Otherwise no return value.
    #
    # See also: RawImageFileToWorksheet RawImageFileToExcelFile ReadRawImageFile WriteRawImageFile

    set appId [Excel OpenNew true]
    set workbookId [Excel OpenWorkbook $appId $excelFileName -readonly true]
    if { [string is integer $worksheetNameOrIndex] } {
        set worksheetId [Excel GetWorksheetIdByIndex $workbookId [expr int($worksheetNameOrIndex)]]
    } else {
        set worksheetId [Excel GetWorksheetIdByName $workbookId $worksheetNameOrIndex]
    }
    Excel WorksheetToRawImageFile $worksheetId $rawFileName $useHeader $pixelType
    if { $quitExcel } {
        Excel Quit $appId
    } else {
        return $appId
    }
}

proc ::Excel::ExcelFileToWikitFile {excelFileName wikiFileName {worksheetNameOrIndex 1} {useHeader true} {quitExcel true}} {

    # Convert an Excel file to a Wikit table file.
    #
    # excelFileName        - Name of the Excel input file.
    # wikiFileName         - Name of the Wikit output file.
    # worksheetNameOrIndex - Worksheet name or index to convert.
    # useHeader            - If set to true, use the first row of the worksheet as the header
    #                        of the Wikit table.
    #                        Otherwise do not generate a Wikit table header. All worksheet
    #                        cells are interpreted as data.
    # quitExcel            - If set to true, quit the Excel instance after generation of output file.
    #                        Otherwise leave the Excel instance open after generation of output file.
    #
    # Note, that the Excel Workbook is opened in read-only mode.
    #
    # Returns the Excel application identifier, if $quitExcel is false.
    # Otherwise no return value.
    #
    # See also: WikitFileToWorksheet WikitFileToExcelFile
    # ReadWikitFile WriteWikitFile MediaWikiFileToExcelFile

    set appId [Excel OpenNew true]
    set workbookId [Excel OpenWorkbook $appId $excelFileName -readonly true]
    if { [string is integer $worksheetNameOrIndex] } {
        set worksheetId [Excel GetWorksheetIdByIndex $workbookId [expr int($worksheetNameOrIndex)]]
    } else {
        set worksheetId [Excel GetWorksheetIdByName $workbookId $worksheetNameOrIndex]
    }
    Excel WorksheetToWikitFile $worksheetId $wikiFileName $useHeader
    if { $quitExcel } {
        Excel Quit $appId
    } else {
        return $appId
    }
}

proc ::Excel::FormatHeaderRow {worksheetId row startCol endCol} {

    # Format a row as a header row.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # startCol    - Column number of formatting start. Column numbering starts with 1.
    # endCol      - Column number of formatting end. Column numbering starts with 1.
    #
    # The cell values of a header are formatted as bold text with both vertical and
    # horizontal centered alignment.
    #
    # Returns no value.
    #
    # See also: SetHeaderRow

    set header [Excel SelectRangeByIndex $worksheetId $row $startCol $row $endCol]
    Excel SetRangeHorizontalAlignment $header $::Excel::xlCenter
    Excel SetRangeVerticalAlignment   $header $::Excel::xlCenter
    Excel SetRangeFontBold $header
    Cawt Destroy $header
}

proc ::Excel::FreezePanes {worksheetId row col {onOff true}} {

    # Freeze a range in a worksheet identified by its row/column index.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # col         - Column number. Column numbering starts with 1.
    # onOff       - If set to true, freeze the range.
    #               Otherwise unfreeze the range.
    #
    # The rows and columns with indices lower than the specified values are freezed for scrolling.
    # If a row or a column should not be freezed, a value of zero for the corresponding parameter
    # should be given.
    #
    # See also: SelectCellByIndex

    $worksheetId Activate
    set appId [Office GetApplicationId $worksheetId]
    set actWin [$appId ActiveWindow]
    if { $onOff } {
        if { $col > 0 } {
            $actWin SplitColumn $col
        }
        if { $row > 0 } {
            $actWin SplitRow $row
        }
    }
    $actWin FreezePanes [Cawt TclBool $onOff]
    Cawt Destroy $actWin
    Cawt Destroy $appId
}

proc ::Excel::GetActiveWorkbook {appId} {

    # Return the active workbook of an application.
    #
    # appId - Identifier of the Excel instance.
    #
    # Returns the identifier of the active workbook.
    #
    # See also: OpenWorkbook

    return [$appId ActiveWorkbook]
}

proc ::Excel::GetCellComment {worksheetId row col} {

    # Return the comment text of a cell.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # col         - Column number. Column numbering starts with 1.
    #
    # If the cell does not contain a comment, an empty string is returned.
    #
    # Returns the comment text of a cell.
    #
    # See also: SetRangeComment SetCommentDisplayMode SetCommentSize GetCellValue

    set rangeId [Excel SelectCellByIndex $worksheetId $row $col]
    set commentId [$rangeId Comment]
    set commentText ""
    if { [Cawt IsComObject $commentId] } {
        set commentText [$commentId Text]
    }
    Cawt Destroy $commentId
    Cawt Destroy $rangeId
    return $commentText
}

proc ::Excel::GetCellIdByIndex {worksheetId row col} {

    # Return a cell of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # col         - Column number. Column numbering starts with 1.
    #
    # Returns the cell identifier of the cell with index (row, col).
    #
    # See also: SelectCellByIndex AddWorksheet

    set cellsId [Excel GetCellsId $worksheetId]
    set cell [$cellsId Item [expr {int($row)}] [expr {int($col)}]]
    Cawt Destroy $cellsId
    return $cell
}

proc ::Excel::GetCellRange {row1 col1 row2 col2} {

    # Return a numeric cell range as an Excel range string in A1 notation.
    #
    # row1 - Row number of upper-left corner of the cell range.
    # col1 - Column number of upper-left corner of the cell range.
    # row2 - Row number of lower-right corner of the cell range.
    # col2 - Column number of lower-right corner of the cell range.
    #
    # Example:
    #     [GetCellRange 1 2  5 7] returns string "B1:G5".
    #
    # Returns the numeric cell range as an Excel range string in A1 notation.
    #
    # See also: GetColumnRange

    set range [format "%s%d:%s%d"  [Excel ColumnIntToChar $col1] $row1  [Excel ColumnIntToChar $col2] $row2]
    return $range
}

proc ::Excel::GetCellsId {worksheetId} {

    # Return the cells identifier of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the range of all cells from the worksheet. This corresponds to the
    # method Cells() of the Worksheet object.

    set cellsId [$worksheetId Cells]
    return $cellsId
}

proc ::Excel::GetCellValue {worksheetId row col {fmt text}} {

    # Return the value of a cell.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # col         - Column number. Column numbering starts with 1.
    # fmt         - Format of the cell. Possible values: `text`, `int`, `real`.
    #
    # Depending on the format the value of the cell is returned as a string,
    # integer number or a floating-point number.
    # If the value could not be retrieved, an error is thrown.
    #
    # Returns the value of the cell.
    #
    # See also: GetCellValueA1 SetCellValue ColumnCharToInt

    set cellsId [Excel GetCellsId $worksheetId]
    set cell [$cellsId Item [expr {int($row)}] [expr {int($col)}]]
    set retVal [catch {$cell Value} val]
    if { $retVal != 0 } {
        error "GetCellValue: Unable to get value of cell ($row, $col)"
    }
    Cawt Destroy $cell
    Cawt Destroy $cellsId
    if { $fmt eq "text" } {
        return $val
    } elseif { $fmt eq "int" } {
        return [expr {int ($val)}]
    } elseif { $fmt eq "real" } {
        return [expr {double ($val)}]
    } else {
        error "GetCellValue: Unknown format $fmt"
    }
}

proc ::Excel::GetCellValueA1 {worksheetId cellA1 {fmt text}} {

    # Return the value of a cell.
    #
    # worksheetId - Identifier of the worksheet.
    # cellA1      - Cell identifier in A1 notation.
    # fmt         - Format of the cell. Possible values: `text`, `int`, `real`.
    #
    # Depending on the format the value of the cell is returned as a string,
    # integer number or a floating-point number.
    # If the value could not be retrieved, an error is thrown.
    #
    # Returns the value of the cell.
    #
    # See also: GetCellValue SetCellValue ColumnCharToInt

    regexp {([[:alpha:]]+)([[:digit:]]+)} $cellA1 -> colStr row
    set col [Excel ColumnCharToInt $colStr]
    return [Excel GetCellValue $worksheetId $row $col $fmt]
}

proc ::Excel::GetChartNumSeries {chartId} {

    # Return the number of series of a chart.
    #
    # chartId - Identifier of the chart.
    #
    # Returns the number of series of the chart.
    #
    # See also: GetChartSeries CreateChart

    return [$chartId -with { SeriesCollection } Count]
}

proc ::Excel::GetChartSeries {chartId index} {

    # Get a specific series of a chart.
    #
    # chartId - Identifier of the chart.
    # index   - Index of the series. Index numbering starts with 1.
    #
    # Returns the series identifier.
    #
    # See also: GetChartNumSeries CreateChart SetSeriesAttributes

    return [$chartId -with { SeriesCollection } Item [expr {int($index)}]]
}

proc ::Excel::GetColumnNumber {colStrOrInt} {

    # Return an Excel column string or number as a column number.
    #
    # colStrOrInt - Column string.
    #
    # Returns the corresponding column number.
    #
    # See also: ColumnCharToInt

    if { [string is integer $colStrOrInt] } {
        return [expr int($colStrOrInt)]
    } else {
        return [Excel ColumnCharToInt $colStrOrInt]
    }
}

proc ::Excel::GetColumnRange {col1 col2} {

    # Return a numeric column range as an Excel range string.
    #
    # col1 - Column number of the left-most column.
    # col2 - Column number of the right-most column.
    #
    # Example:
    #     [GetColumnRange 2 7] returns string "B:G".
    #
    # Returns the numeric column range as an Excel range string.
    #
    # See also: GetCellRange

    set range [format "%s:%s"  [Excel ColumnIntToChar $col1]  [Excel ColumnIntToChar $col2]]
    return $range
}

proc ::Excel::GetColumnValues {worksheetId col {startRow 0} {numVals 0}} {

    # Return column values as a Tcl list.
    #
    # worksheetId - Identifier of the worksheet.
    # col         - Column number. Column numbering starts with 1.
    # startRow    - Row number of start. Row numbering starts with 1.
    #               If negative or zero, start at first available row.
    # numVals     - If negative or zero, all available column values are returned.
    #               If positive, only numVals values of the column are returned.
    #
    # Note, that the functionality of this procedure has changed slightly with
    # CAWT versions greater than 1.0.5:
    # If $startRow is not specified, $startRow is not set to 1, but it is set to
    # the first available row.
    # Possible incompatibility.
    #
    # Returns the values of the specified column or column range as a Tcl list.
    #
    # See also: SetColumnValues GetRowValues GetCellValue ColumnCharToInt GetFirstUsedRow

    if { $startRow <= 0 } {
        set startRow [Excel GetFirstUsedRow $worksheetId]
    }
    if { $numVals <= 0 } {
        set numVals [expr { $startRow + [Excel GetLastUsedRow $worksheetId] - 1 }]
    }
    set valList [list]
    set row $startRow
    set ind 0
    while { $ind < $numVals } {
        lappend valList [Excel GetCellValue $worksheetId $row $col]
        incr ind
        incr row
    }

    # Remove empty cell values from the end of the values list.
    incr ind -1
    while { $ind >= 0 && [lindex $valList $ind] eq "" } {
        incr ind -1
    }
    return [lrange $valList 0 $ind]
}

proc ::Excel::GetCsvSeparatorChar {} {

    # Returns the column separator character.

    variable sSepChar

    return $sSepChar
}

proc ::Excel::GetCurrencyFormat {appId currency {pre 0} {post 00} {floatSep {}}} {

    # Return an Excel number format string for currencies.
    #
    # appId    - Identifier of the Excel instance.
    # currency - String identifying the currency symbol.
    # pre      - Number of digits before the decimal point.
    # post     - Number of digits after the decimal point.
    # floatSep - Specify the floating point separator character.
    #
    # The currency may be specified either by using one of the predefined names
    # (Dollar, Euro, Pound, Yen, DM) or by specifying an Unicode character.
    #
    # Example:
    #      [GetCurrencyFormat "\u20B0" "0" "00"] will return the Excel format string
    #      to show floating point values with 2 digits after the decimal point
    #      and a German Penny Sign as currency symbol.
    #
    # Returns the corresponding Excel number format string for currencies.
    #
    # See also: SetRangeFormat GetNumberFormat

    set numberFormat [Excel GetNumberFormat $appId $pre $post $floatSep]
    switch -exact -nocase -- $currency {
        "Dollar" { append numberFormat " \\\u0024" }
        "Euro"   { append numberFormat " \\\u20AC" }
        "Pound"  { append numberFormat " \\\u00A3" }
        "Yen"    { append numberFormat " \\\u00A5" }
        "DM"     { append numberFormat " \\D\\M" }
        default  { append numberFormat " \\$currency" }
    }
    return $numberFormat
}

proc ::Excel::GetDecimalSeparator {appId} {

    # Return the decimal separator used by Excel.
    #
    # appId - Identifier of the Excel instance.
    #
    # Returns the decimal separator used by Excel.
    #
    # See also: GetVersion GetThousandsSeparator GetListItemSeparator

    return [$appId DecimalSeparator]
}

proc ::Excel::GetEnum {enumOrString} {

    # Get numeric value of an enumeration.
    #
    # enumOrString - Enumeration name
    #
    # Returns the numeric value of an enumeration.
    #
    # See also: GetEnumName GetEnumTypes GetEnumVal GetEnumNames

    set retVal [catch { expr int($enumOrString) } enumInt]
    if { $retVal == 0 } {
        return $enumInt
    } else {
        return [GetEnumVal $enumOrString]
    }
}

proc ::Excel::GetEnumName {enumType enumVal} {

    # Get name of a given enumeration type and numeric value.
    #
    # enumType - Enumeration type
    # enumVal  - Enumeration numeric value.
    #
    # Returns the list of names of a given enumeration type.
    #
    # See also: GetEnumNames GetEnumTypes GetEnumVal GetEnum

    variable enums

    set enumName ""
    if { [info exists enums($enumType)] } {
        foreach { key val } $enums($enumType) {
            if { $val eq $enumVal } {
                set enumName $key
                break
            }
        }
    }
    return $enumName
}

proc ::Excel::GetEnumNames {enumType} {

    # Get names of a given enumeration type.
    #
    # enumType - Enumeration type
    #
    # Returns the list of names of a given enumeration type.
    #
    # See also: GetEnumName GetEnumTypes GetEnumVal GetEnum

    variable enums

    if { [info exists enums($enumType)] } {
        foreach { key val } $enums($enumType) {
            lappend nameList $key
        }
        return $nameList
    } else {
        return [list]
    }
}

proc ::Excel::GetEnumTypes {} {

    # Get available enumeration types.
    #
    # Returns the list of available enumeration types.
    #
    # See also: GetEnumName GetEnumNames GetEnumVal GetEnum

    variable enums

    return [lsort -dictionary [array names enums]]
}

proc ::Excel::GetEnumVal {enumName} {

    # Get numeric value of an enumeration name.
    #
    # enumName - Enumeration name
    #
    # Returns the numeric value of an enumeration name.
    #
    # See also: GetEnumName GetEnumTypes GetEnumNames GetEnum

    variable enums

    foreach enumType [GetEnumTypes] {
        set ind [lsearch -exact $enums($enumType) $enumName]
        if { $ind >= 0 } {
            return [lindex $enums($enumType) [expr { $ind + 1 }]]
        }
    }
    return ""
}

proc ::Excel::GetExtString {appId} {

    # Return the default extension of an Excel file.
    #
    # appId - Identifier of the Excel instance.
    #
    # Starting with Excel 12 (2007) this is the string `.xlsx`.
    # In previous versions it was `.xls`.
    #
    # Returns the default extension of an Excel file.
    #
    # See also: ::Office::GetOfficeType

    # appId is only needed, so we are sure, that excelVersion is initialized.

    variable excelVersion

    if { $excelVersion >= 12.0 } {
        return ".xlsx"
    } else {
        return ".xls"
    }
}

proc ::Excel::GetFirstUsedColumn {worksheetId} {

    # Return the index of the first used column of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the index of the first used column of a worksheet.
    #
    # See also: GetNumColumns GetNumUsedColumns GetLastUsedColumn GetNumUsedRows

    return [$worksheetId -with { UsedRange } Column]
}

proc ::Excel::GetFirstUsedRow {worksheetId} {

    # Return the index of the first used row of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the index of the first used row of a worksheet.
    #
    # See also: GetNumRows GetNumUsedRows GetLastUsedRow GetNumUsedColumns

    return [$worksheetId -with { UsedRange } Row]
}

proc ::Excel::GetFloatSeparator {} {

    # Obsolete: Replaced with [GetDecimalSeparator] in version 2.1.0
    #
    # Only valid, after a call of [Open] or [OpenNew].
    #
    # Note, that this procedure has been superseeded with [GetDecimalSeparator] in version 2.1.0.
    # Only use it, if using an Excel version older than 2007.
    #
    # See also: GetVersion GetDecimalSeparator GetThousandsSeparator

    variable decimalSeparator

    return $decimalSeparator
}

proc ::Excel::GetHiddenColumns {worksheetId} {

    # Return the hidden columns of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the hidden columns as a list of column numbers.
    # If no columns are hidden, an empty list is returned.
    # Column numbering starts with 1.
    #
    # See also: HideColumn GetHiddenRows ColumnCharToInt

    set numUsedCols [Excel GetNumUsedColumns $worksheetId]
    set hiddenList  [list]
    for { set c 1 } { $c <= $numUsedCols } { incr c } {
        set cell [Excel SelectCellByIndex $worksheetId 1 $c]
        set isHidden [$cell -with { EntireColumn } Hidden]
        if { $isHidden } {
            lappend hiddenList $c
        }
        Cawt Destroy $cell
    }
    return $hiddenList
}

proc ::Excel::GetHiddenRows {worksheetId} {

    # Return the hidden rows of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the hidden rows as a list of row numbers.
    # If no rows are hidden, an empty list is returned.
    # Row numbering starts with 1.
    #
    # See also: HideRow GetHiddenColumns ColumnCharToInt

    set numUsedRows [Excel GetNumUsedRows $worksheetId]
    set hiddenList  [list]
    for { set r 1 } { $r <= $numUsedRows } { incr r } {
        set cell [Excel SelectCellByIndex $worksheetId $r 1]
        set isHidden [$cell -with { EntireRow } Hidden]
        if { $isHidden } {
            lappend hiddenList $r
        }
        Cawt Destroy $cell
    }
    return $hiddenList
}

proc ::Excel::GetLangNumberFormat {pre post {floatSep {}}} {

    # Obsolete: Replaced with [GetNumberFormat] in version 2.1.0
    #
    # pre      - Number of digits before the decimal point.
    # post     - Number of digits after the decimal point.
    # floatSep - Specify the floating point separator character.
    #
    # The number of digits is specified as a string containing as
    # many zeros as wanted digits.
    # If no floating point separator is specified or the empty string, the
    # floating point separator of Excel is used.
    #
    # Example:
    #     [GetLangNumberFormat "0" "0000"] will return the Excel format string
    #     to show floating point values with 4 digits after the decimal point.
    #
    # See also: SetRangeFormat GetNumberFormat

    if { $floatSep eq "" } {
        set floatSep [Excel GetFloatSeparator]
    }
    return [format "%s%s%s" $pre $floatSep $post]
}

proc ::Excel::GetLastUsedColumn {worksheetId} {

    # Return the index of the last used column of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the index of the last used column of a worksheet.
    #
    # See also: GetNumColumns GetNumUsedColumns GetFirstUsedColumn GetNumUsedRows

    return [expr { [Excel GetFirstUsedColumn $worksheetId] +  [Excel GetNumUsedColumns $worksheetId] - 1 }]
}

proc ::Excel::GetLastUsedRow {worksheetId} {

    # Return the index of the last used row of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the index of the last used row of a worksheet.
    #
    # See also: GetNumRows GetNumUsedRows GetFirstUsedRow GetNumUsedColumns

    return [expr { [Excel GetFirstUsedRow $worksheetId] +  [Excel GetNumUsedRows $worksheetId] - 1 }]
}

proc ::Excel::GetListItemSeparator {} {

    # Return the list item separator used by Windows.
    #
    # Returns the list item separator used by Windows and Excel.
    # This is either the character returned by `twapi::get_locale_info 0 -slist` or
    # the character set by method [SetListItemSeparator].
    #
    # See also: GetVersion SetListItemSeparator CreateRangeString
    # GetDecimalSeparator GetThousandsSeparator

    variable listItemSeparator

    if { $listItemSeparator eq "" } {
        return [lindex [twapi::get_locale_info 0 -slist] 1]
    } else {
        return $listItemSeparator
    }
}

proc ::Excel::GetMatrixValues {worksheetId row1 col1 row2 col2} {

    # Return worksheet table values as a matrix.
    #
    # worksheetId - Identifier of the worksheet.
    # row1        - Row number of upper-left corner of the cell range.
    # col1        - Column number of upper-left corner of the cell range.
    # row2        - Row number of lower-right corner of the cell range.
    # col2        - Column number of lower-right corner of the cell range.
    #
    # Returns the worksheet table values as a matrix.
    #
    # See also: SetMatrixValues GetRowValues GetColumnValues

    set cellId [Excel SelectRangeByIndex $worksheetId $row1 $col1 $row2 $col2]
    set matrixList [Excel GetRangeValues $cellId]

    Cawt Destroy $cellId
    return $matrixList
}

proc ::Excel::GetMaxColumns {appId} {

    # Return the maximum number of columns of an Excel table.
    #
    # appId - Identifier of the Excel instance.
    #
    # Returns the maximum number of columns of an Excel table.
    #
    # See also: GetNumColumns

    # appId is only needed, so we are sure, that excelVersion is initialized.

    variable excelVersion

    if { $excelVersion < 12.0 } {
        return 256
    } else {
        return 16384
    }
}

proc ::Excel::GetMaxRows {appId} {

    # Return the maximum number of rows of an Excel table.
    #
    # appId - Identifier of the Excel instance.
    #
    # Returns the maximum number of rows of an Excel table.
    #
    # See also: GetNumRows

    # appId is only needed, so we are sure, that excelVersion is initialized.

    variable excelVersion

    if { $excelVersion < 12.0 } {
        return 65536
    } else {
        return 1048576
    }
}

proc ::Excel::GetNamedRange {objId rangeName} {

    # Get the identifier of a named range.
    #
    # objId     - Identifier of a workbook or worksheet.
    # rangeName - Name of range to get.
    #
    # Returns the range identifier of the named range.
    #
    # See also: SelectRangeByIndex GetNamedRangeNames SetNamedRange

    set names [$objId Names]
    $names -iterate name {
        if { [string match "*$rangeName" [$name Name]] } {
            set rangeId [$name RefersToRange]
            Cawt Destroy $name
            return $rangeId
        }
        Cawt Destroy $name
    }
    error "Range name $rangeName not found."
}

proc ::Excel::GetNamedRangeNames {objId} {

    # Get the names of named ranges.
    #
    # objId - Identifier of a workbook or worksheet.
    #
    # Returns a sorted list of all names.
    #
    # See also: GetNamedRange SetNamedRange

    set nameList [list]
    set names [$objId Names]
    $names -iterate name {
        lappend nameList [$name Name]
        Cawt Destroy $name
    }
    Cawt Destroy $names
    return [lsort -dictionary $nameList]
}

proc ::Excel::GetNumberFormat {appId pre post {floatSep {}}} {

    # Return an Excel number format string.
    #
    # appId    - Identifier of the Excel instance.
    # pre      - Number of digits before the decimal point.
    # post     - Number of digits after the decimal point.
    # floatSep - Specify the floating point separator character.
    #
    # The number of digits is specified as a string containing as
    # many zeros as wanted digits.
    # If no floating point separator is specified or the empty string, the
    # floating point separator of Excel is used.
    #
    # Example:
    #     [GetNumberFormat "0" "0000"] will return the Excel format string
    #     to show floating point values with 4 digits after the decimal point.
    #
    # Returns the corresponding Excel number format string.
    #
    # See also: SetRangeFormat GetCurrencyFormat

    if { $floatSep eq "" } {
        set floatSep [Excel GetDecimalSeparator $appId]
    }
    return [format "%s%s%s" $pre $floatSep $post]
}

proc ::Excel::GetNumColumns {rangeId} {

    # Return the number of columns of a cell range.
    #
    # rangeId - Identifier of a range, cells collection or a worksheet.
    #
    # If specifying a $worksheetId or $cellsId, the maximum number of columns
    # of a worksheet will be returned.
    # The maximum number of columns is 256 for Excel versions before 2007.
    # Since 2007 the maximum number of columns is 16.384.
    #
    # Returns the number of columns of a cell range.
    #
    # See also: GetMaxColumns GetNumUsedColumns GetFirstUsedColumn GetLastUsedColumn GetNumRows

    return [$rangeId -with { Columns } Count]
}

proc ::Excel::GetNumRows {rangeId} {

    # Return the number of rows of a cell range.
    #
    # rangeId - Identifier of a range, cells collection or a worksheet.
    #
    # If specifying a worksheetId or cellsId, the maximum number of rows
    # of a worksheet will be returned.
    # The maximum number of rows is 65.536 for Excel versions before 2007.
    # Since 2007 the maximum number of rows is 1.048.576.
    #
    # Returns the number of rows of a cell range.
    #
    # See also: GetMaxRows GetNumUsedRows GetFirstUsedRow GetLastUsedRow GetNumColumns

    return [$rangeId -with { Rows } Count]
}

proc ::Excel::GetNumStyles {workbookId} {

    # Return the number of styles in a workbook.
    #
    # workbookId - Identifier of the workbook.
    #
    # Returns the number of styles in the workbook.
    #
    # See also: GetStyleId

    return [$workbookId -with { Styles } Count]
}

proc ::Excel::GetNumUsedColumns {worksheetId} {

    # Return the number of used columns of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Note, that this procedure returns 1, even if the worksheet is empty.
    # Use [IsWorksheetEmpty] to determine, if a worksheet is totally empty.
    #
    # Returns the number of used columns of a worksheet.
    #
    # See also: GetNumColumns GetFirstUsedColumn GetLastUsedColumn GetNumUsedRows

    return [$worksheetId -with { UsedRange Columns } Count]
}

proc ::Excel::GetNumUsedRows {worksheetId} {

    # Return the number of used rows of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Note, that this procedure returns 1, even if the worksheet is empty.
    # Use IsWorksheetEmpty to determine, if a worksheet is totally empty.
    #
    # Returns the number of used rows of a worksheet.
    #
    # See also: GetNumRows GetFirstUsedRow GetLastUsedRow GetNumUsedColumns

    return [$worksheetId -with { UsedRange Rows } Count]
}

proc ::Excel::GetNumWorksheets {workbookId} {

    # Return the number of worksheets in a workbook.
    #
    # workbookId - Identifier of the workbook.
    #
    # Returns the number of worksheets in the workbook.
    #
    # See also: AddWorksheet OpenWorkbook

    return [$workbookId -with { Worksheets } Count]
}

proc ::Excel::GetRangeAsIndex {rangeId} {

    # Get address of a cell range as list of row/column indices.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns address of a cell range as a 2 or 4 element list of integers:
    #
    # If the range represents a single cell, the list consists of 2 elements,
    # representing the row and column index of the cell.
    #
    # If the range represents more than one cell, the list consists of 4 elements.
    # The first two elements represent the row and column indices of the top-left cell of the range.
    # The last two elements represent the row and column indices of the bottom-right cell of the range.
    #
    # See also: SelectRangeByIndex GetCellRange

    set rangeStr [Excel GetRangeAsString $rangeId]
    if { [string first ":" $rangeStr] > 0 } {
        regexp {([[:alpha:]]+)([[:digit:]]+):([[:alpha:]]+)([[:digit:]]+)} $rangeStr -> colStr1 row1 colStr2 row2
        set col1 [Excel ColumnCharToInt $colStr1]
        set col2 [Excel ColumnCharToInt $colStr2]
        return [list $row1 $col1 $row2 $col2]
    } else {
        regexp {([[:alpha:]]+)([[:digit:]]+)} $rangeStr -> colStr row
        set col [Excel ColumnCharToInt $colStr]
        return [list $row $col]
    }
}

proc ::Excel::GetRangeAsString {rangeId} {

    # Get address of a cell range as Excel range string in A1 notation.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns address of a cell range as Excel range string in A1 notation.
    #
    # See also: SelectRangeByString GetCellRange

    set rangeStr [string map { "$" "" } [$rangeId Address]]
    return $rangeStr
}

proc ::Excel::GetRangeCharacters {rangeId {start 1} {length -1}} {

    # Return characters of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # start   - Start of the character range.
    # length  - The number of characters after start.
    #
    # Returns all or a range of characters of a cell range.
    # If no optional parameters are specified, all characters of the cell range are
    # returned.
    #
    # See also: SelectRangeByIndex SelectRangeByString

    if { $length < 0 } {
        return [$rangeId Characters $start]
    } else {
        return [$rangeId Characters $start $length]
    }
}

proc ::Excel::GetRangeFillColor {rangeId} {

    # Get the fill color of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns the fill color as a list of r, b and b values.
    # The values are returned as integers in the range \[0, 255\].
    #
    # See also: SetRangeFillColor ::Cawt::OfficeColorToRgb SelectRangeByIndex SelectRangeByString

    set colorNum [$rangeId -with { Interior } Color]
    return [Cawt OfficeColorToRgb $colorNum]
}

proc ::Excel::GetRangeFontAttributes {rangeId args} {

    # Get the font attibutes of a cell or character range.
    #
    # rangeId - Identifier of the cell range.
    # args    - Options described below.
    #
    # -bold          - Boolean.
    # -fontstyle     - Font stye as string.
    # -italic        - Boolean.
    # -name          - Font name as string.
    # -outlinefont   - Boolean.
    # -size          - Font size in points.
    # -shadow        - Boolean.
    # -strikethrough - Boolean.
    # -subscript     - Boolean.
    # -superscript   - Boolean.
    # -underline     - Enumeration of type [Enum::XlUnderlineStyle]
    # -themecolor    - Enumeration of type [Enum::XlThemeColor].
    # -themefont     - Enumeration of type [Enum::XlThemeFont].
    # -tintandshade  - Floating point number from -1 (darkest) to 1 (lightest). Zero is neutral.
    #
    # Example:
    #     lassign [GetRangeFontAttributes $rangeId -name -size] name size
    #     returns the font name and the font size.
    #
    # Returns the specified font attributes as a list.
    #
    # See also: SetRangeFontAttributes SelectRangeByIndex
    # GetRangeFontBold GetRangeFontItalic GetRangeFontName GetRangeFontSize
    # GetRangeFontSubscript GetRangeFontSuperscript GetRangeFontUnderline

    set fontId [$rangeId Font]
    set valList [list]
    foreach key $args {
        switch -exact -nocase -- $key {
            "-bold"          { lappend valList [$fontId Bold] }
            "-fontstyle"     { lappend valList [$fontId FontStyle] }
            "-italic"        { lappend valList [$fontId Italic] }
            "-name"          { lappend valList [$fontId Name] }
            "-outlinefont"   { lappend valList [$fontId OutlineFont] }
            "-size"          { lappend valList [$fontId Size] }
            "-shadow"        { lappend valList [$fontId Shadow] }
            "-strikethrough" { lappend valList [$fontId Strikethrough] }
            "-subscript"     { lappend valList [$fontId Subscript] }
            "-superscript"   { lappend valList [$fontId Superscript] }
            "-underline"     { lappend valList [$fontId Underline] }
            "-themecolor"    { lappend valList [$fontId ThemeColor] }
            "-themefont"     { lappend valList [$fontId ThemeFont] }
            "-tintandshade"  { lappend valList [$fontId TintAndShade] }
            default          { error "GetRangeFontAttributes: Unknown key \"$key\" specified" }
        }
    }
    Cawt Destroy $fontId
    return $valList
}

proc ::Excel::GetRangeFontBold {rangeId} {

    # Get the bold font style of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns true, if the font in specified cell range has the bold flag set.
    #
    # See also: SetRangeFontBold SelectRangeByIndex GetRangeFontAttributes

    return [$rangeId -with { Font } Bold]
}

proc ::Excel::GetRangeFontItalic {rangeId} {

    # Get the italic font style of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns true, if the font in specified cell range has the italic flag set.
    #
    # See also: SetRangeFontItalic SelectRangeByIndex GetRangeFontAttributes

    return [$rangeId -with { Font } Italic]
}

proc ::Excel::GetRangeFontName {rangeId} {

    # Get the font name of a cell or character range.
    #
    # rangeId  - Identifier of the cell range.
    #
    # Returns the font name in specified cell range as a string.
    #
    # See also: SetRangeFontName SelectRangeByIndex GetRangeFontAttributes

    return [$rangeId -with { Font } Name]
}

proc ::Excel::GetRangeFontSize {rangeId} {

    # Get the font size of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns the size of the font in specified cell range measured in points.
    #
    # See also: SetRangeFontSize SelectRangeByIndex GetRangeFontAttributes

    return [$rangeId -with { Font } Size]
}

proc ::Excel::GetRangeFontSubscript {rangeId} {

    # Get the subscript font style of a cell or character range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns true, if the font in specified cell range has the subscript flag set.
    #
    # See also: SetRangeFontSubscript SelectRangeByIndex GetRangeFontAttributes

    return [$rangeId -with { Font } Subscript]
}

proc ::Excel::GetRangeFontSuperscript {rangeId} {

    # Get the superscript font style of a cell or character range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns true, if the font in specified cell range has the superscript flag set.
    #
    # See also: SetRangeFontSuperscript SelectRangeByIndex GetRangeFontAttributes

    return [$rangeId -with { Font } Superscript]
}

proc ::Excel::GetRangeFontUnderline {rangeId} {

    # Get the underline font style of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns the underline style of specified cell range.
    # The returned value is of enumeration type [Enum::XlUnderlineStyle].
    #
    # See also: SetRangeFontUnderline SelectRangeByIndex GetRangeFontAttributes

    return [$rangeId -with { Font } Underline]
}

proc ::Excel::GetRangeFormat {rangeId} {

    # Get the number format of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns the number format in Excel style.
    #
    # See also: SetRangeFormat SelectRangeByIndex SelectRangeByString

    return [$rangeId NumberFormat]
}

proc ::Excel::GetRangeHorizontalAlignment {rangeId} {

    # Get the horizontal alignment of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns the horizontal alignment as a value of enumeration type [Enum::XlHAlign].
    #
    # See also: SetRangeHorizontalAlignment SelectRangeByIndex SelectRangeByString

    return [$rangeId HorizontalAlignment]
}

proc ::Excel::GetRangeTextColor {rangeId} {

    # Get the text color of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # The r, g and b values are returned as integers in the
    # range \[0, 255\].
    #
    # Returns the text color as a list of r, b and b values.
    #
    # See also: SetRangeTextColor ::Cawt::OfficeColorToRgb SelectRangeByIndex SelectRangeByString

    set colorNum [$rangeId -with { Font } Color]
    return [Cawt OfficeColorToRgb $colorNum]
}

proc ::Excel::GetRangeValues {rangeId} {

    # Return range values as a matrix.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns the range values as a matrix.
    #
    # See also: SetRangeValues GetMatrixValues GetRowValues GetColumnValues GetCellValue

    return [$rangeId Value2]
}

proc ::Excel::GetRangeVerticalAlignment {rangeId} {

    # Get the vertical alignment of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns the vertical alignment as a value of enumeration type [Enum::XlVAlign].
    #
    # See also: SetRangeVerticalAlignment SelectRangeByIndex SelectRangeByString

    return [$rangeId VerticalAlignment]
}

proc ::Excel::GetRangeWrapText {rangeId} {

    # Get the wrap text mode of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns true, if the specified cell range has the wrap text flag set.
    #
    # See also: SetRangeWrapText GetRangeHorizontalAlignment GetRangeTextColor SelectRangeByIndex

    return [$rangeId WrapText]
}

proc ::Excel::GetRowValues {worksheetId row {startCol 0} {numVals 0}} {

    # Return row values as a Tcl list.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # startCol    - Column number of start. Column numbering starts with 1.
    #               If negative or zero, start at first available column.
    # numVals     - If negative or zero, all available row values are returned.
    #               If positive, only $numVals values of the row are returned.
    #
    # Note, that the functionality of this procedure has changed slightly with
    # CAWT versions greater than 1.0.5:
    # If $startCol is not specified, $startCol is not set to 1, but it is set to
    # the first available row.
    # Possible incompatibility.
    #
    # Returns the values of the specified row or row range as a Tcl list.
    #
    # See also: SetRowValues GetColumnValues GetCellValue ColumnCharToInt GetFirstUsedColumn

    if { $startCol <= 0 } {
        set startCol [Excel GetFirstUsedColumn $worksheetId]
    }
    if { $numVals <= 0 } {
        set numVals [expr { $startCol + [Excel GetLastUsedColumn $worksheetId] - 1 }]
    }
    set valList [list]
    set col $startCol
    set ind 0
    while { $ind < $numVals } {
        lappend valList [Excel GetCellValue $worksheetId $row $col]
        incr ind
        incr col
    }

    # Remove empty cell values from the end of the values list.
    incr ind -1
    while { $ind >= 0 && [lindex $valList $ind] eq "" } {
        incr ind -1
    }
    return [lrange $valList 0 $ind]
}

proc ::Excel::GetStyleId {workbookId indexOrName} {

    # Find a style by its index or name.
    #
    # workbookId  - Identifier of the workbook.
    # indexOrName - Index or name of the style to find.
    #
    # Indices start at 1.
    # If the index is out of bounds or a style with given name is
    # not available, an error is thrown.
    #
    # For details on style properties see the official [Microsoft documentation]
    # (https://docs.microsoft.com/en-us/office/vba/api/excel.style)
    #
    # Returns the identifier of the found style.
    #
    # See also: GetNumStyles

    if { [string is integer $indexOrName] } {
        set count [Excel GetNumStyles $workbookId]
        if { $indexOrName < 1 || $indexOrName > $count } {
            error "GetStyleId: Invalid style index $indexOrName given."
        }
        set styleId [$workbookId -with { Styles } Item [expr int($indexOrName)]]
    } else {
        set retVal [catch {$workbookId -with { Styles } Item [Cawt TclString $indexOrName]} styleId]
        if { $retVal != 0 } {
            error "GetStyleId: Invalid style name $indexOrName"
        }
    }
    return $styleId
}

proc ::Excel::GetTablelistHeader {tableId} {

    # Return the header line of a tablelist as a list.
    #
    # tableId - Identifier of the tablelist.
    #
    # Returns the header line of the tablelist as a list.
    #
    # See also: TablelistToWorksheet WorksheetToTablelist
    # SetTablelistHeader GetTablelistValues

    set numCols [$tableId columncount]
    for { set col 0 } { $col < $numCols } { incr col } {
        lappend headerList [$tableId columncget $col -title]
    }
    return $headerList
}

proc ::Excel::GetTablelistValues {tableId} {

    # Return the values of a tablelist as a matrix.
    #
    # tableId - Identifier of the tablelist.
    #
    # Returns the values of the tablelist as a matrix.
    #
    # See also: TablelistToWorksheet WorksheetToTablelist
    # SetTablelistValues GetTablelistHeader

    return [$tableId get 0 end]
}

proc ::Excel::GetThousandsSeparator {appId} {

    # Return the thousands separator used by Excel.
    #
    # appId - Identifier of the Excel instance.
    #
    # Returns the thousands separator used by Excel.
    #
    # See also: GetVersion GetDecimalSeparator GetListItemSeparator

    return [$appId ThousandsSeparator]
}

proc ::Excel::GetVersion {objId {useString false}} {

    # Return the version of an Excel application.
    #
    # objId     - Identifier of an Excel object instance.
    # useString - If set to true, return the version name (ex. `Excel 2000`).
    #             Otherwise return the version number (ex. `9.0`).
    #
    # Both version name and version number are returned as strings.
    # Version number is in a format, so that it can be evaluated as a
    # floating point number.
    #
    # Returns the version of an Excel application.
    #
    # See also: GetDecimalSeparator GetExtString

    array set map {
        "8.0"  "Excel 97"
        "9.0"  "Excel 2000"
        "10.0" "Excel 2002"
        "11.0" "Excel 2003"
        "12.0" "Excel 2007"
        "14.0" "Excel 2010"
        "15.0" "Excel 2013"
        "16.0" "Excel 2016/2019"
    }
    set version [Office GetApplicationVersion $objId]

    if { $useString } {
        if { [info exists map($version)] } {
            return $map($version)
        } else {
            return "Unknown Excel version"
        }
    } else {
        return $version
    }
    return $version
}

proc ::Excel::GetWorkbookIdByName {appId workbookName} {

    # Find an open workbook by its name.
    #
    # appId        - Identifier of the Excel instance.
    # workbookName - Name of the workbook to find.
    #
    # Returns the identifier of the found workbook.
    # If a workbook with given name does not exist an error is thrown.
    #
    # See also: OpenWorkbook GetActiveWorkbook GetWorkbookName GetWorksheetIdByName

    set workbooks [$appId Workbooks]
    set shortName [file tail $workbookName]
    $workbooks -iterate workbookId {
        if { [$workbookId Name] eq $shortName } {
            Cawt Destroy $workbooks
            return $workbookId
        }
    }
    Cawt Destroy $workbooks
    error "GetWorkbookIdByName: No open workbook with name $shortName"
}

proc ::Excel::GetWorkbookName {workbookId} {

    # Return the name of a workbook.
    #
    # workbookId - Identifier of the workbook.
    #
    # Returns the name of the workbook.
    #
    # See also: AddWorkbook

    return [$workbookId Name]
}

proc ::Excel::GetWorksheetAsMatrix {worksheetId} {

    # Return worksheet table as a matrix.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the range of the worksheet with valid data as
    # a matrix.
    #
    # See also: SetMatrixValues GetMatrixValues GetFirstUsedRow GetLastUsedRow

    return [Excel GetMatrixValues $worksheetId  [Excel GetFirstUsedRow $worksheetId]  [Excel GetFirstUsedColumn $worksheetId]  [Excel GetLastUsedRow $worksheetId]  [Excel GetLastUsedColumn $worksheetId]]
}

proc ::Excel::GetWorksheetIdByIndex {workbookId index {activate true}} {

    # Find a worksheet by its index.
    #
    # workbookId - Identifier of the workbook containing the worksheet.
    # index      - Index of the worksheet to find.
    # activate   - If set to true, activate the found worksheet.
    #              Otherwise just return the identifier.
    #
    # The left-most worksheet has index 1.
    # Instead of using the numeric index the special word `end` may
    # be used to specify the last worksheet.
    # If the index is out of bounds an error is thrown.
    #
    # Returns the identifier of the found worksheet.
    #
    # See also: GetNumWorksheets GetWorksheetIdByName AddWorksheet

    set count [Excel GetNumWorksheets $workbookId]
    if { $index eq "end" } {
        set index $count
    } else {
        if { $index < 1 || $index > $count } {
            error "GetWorksheetIdByIndex: Invalid index $index given."
        }
    }
    set worksheetId [$workbookId -with { Worksheets } Item [expr $index]]
    if { $activate } {
        $worksheetId Activate
    }
    return $worksheetId
}

proc ::Excel::GetWorksheetIdByName {workbookId worksheetName {activate true}} {

    # Find a worksheet by its name.
    #
    # workbookId    - Identifier of the workbook containing the worksheet.
    # worksheetName - Name of the worksheet to find.
    # activate      - If set to true, activate the found worksheet.
    #                 Otherwise just return the identifier.
    #
    # Returns the identifier of the found worksheet.
    # If a worksheet with given name does not exist an error is thrown.
    #
    # See also: GetNumWorksheets GetWorksheetIndexByName GetWorksheetIdByIndex AddWorksheet
    # GetWorkbookIdByName

    set worksheets [$workbookId Worksheets]
    set count [$worksheets Count]

    for { set i 1 } { $i <= $count } { incr i } {
        set worksheetId [$worksheets Item [expr $i]]
        if { $worksheetName eq [$worksheetId Name] } {
            Cawt Destroy $worksheets
            if { $activate } {
                $worksheetId Activate
            }
            return $worksheetId
        }
        Cawt Destroy $worksheetId
    }
    error "GetWorksheetIdByName: No worksheet with name $worksheetName"
}

proc ::Excel::GetWorksheetIndexByName {workbookId worksheetName {activate true}} {

    # Find a worksheet index by its name.
    #
    # workbookId    - Identifier of the workbook containing the worksheet.
    # worksheetName - Name of the worksheet to find.
    # activate      - If set to true, activate the found worksheet.
    #                 Otherwise just return the index.
    #
    # The left-most worksheet has index 1.
    # If a worksheet with given name does not exist an error is thrown.
    #
    # Returns the index of the found worksheet.
    #
    # See also: GetNumWorksheets GetWorksheetIdByIndex GetWorksheetIdByName AddWorksheet

    set worksheets [$workbookId Worksheets]
    set count [$worksheets Count]

    for { set i 1 } { $i <= $count } { incr i } {
        set worksheetId [$worksheets Item [expr $i]]
        if { $worksheetName eq [$worksheetId Name] } {
            Cawt Destroy $worksheets
            if { $activate } {
                $worksheetId Activate
            }
            return $i
        }
        Cawt Destroy $worksheetId
    }
    error "GetWorksheetIdByName: No worksheet with name $worksheetName"
}

proc ::Excel::GetWorksheetName {worksheetId} {

    # Return the name of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the name of the worksheet.
    #
    # See also: SetWorksheetName AddWorksheet

    return [$worksheetId Name]
}

proc ::Excel::HideColumn {worksheetId col {hide true}} {

    # Hide or unhide a column.
    #
    # worksheetId - Identifier of the worksheet.
    # col         - Column number. Column numbering starts with 1.
    # hide        - If set to true, the specified column is hidden,
    #               otherwise it is shown.
    #
    # Returns no value.
    #
    # See also: InsertColumn DeleteColumn DuplicateColumn GetHiddenColumns HideRow

    set cell [Excel SelectCellByIndex $worksheetId 1 $col]
    $cell -with { EntireColumn } Hidden [Cawt TclBool $hide]
    Cawt Destroy $cell
}

proc ::Excel::HideRow {worksheetId row {hide true}} {

    # Hide or unhide a row.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # hide        - If set to true, the specified row is hidden,
    #               otherwise it is shown.
    #
    # Returns no value.
    #
    # See also: InsertRow DeleteRow DuplicateRow GetHiddenRows HideColumn

    set cell [Excel SelectCellByIndex $worksheetId $row 1]
    $cell -with { EntireRow } Hidden [Cawt TclBool $hide]
    Cawt Destroy $cell
}

proc ::Excel::ImgToWorksheet {phImg worksheetId {row 1} {col 1} {rowHeight 9} {colWidth 1}} {

    # Put a photo image into a worksheet.
    #
    # phImg       - The photo image identifier.
    # worksheetId - Identifier of the worksheet.
    # row         - Row number of the top-left corner of the image. Row numbering starts with 1.
    # col         - Column number of the top-left corner of the image. Column numbering starts with 1.
    # rowHeight   - Row height.
    # colWidth    - Column width in average-size characters of the widget's font.
    #
    # The height value may be specified in a format acceptable by
    # procedure [::Cawt::ValueToPoints], i.e. centimeters, inches or points.
    #
    # **Note:** Use only with small images.
    #
    # Returns no value.
    #
    # See also: WorksheetToImg UseImgTransparency ::Cawt::ImgToClipboard
    # RawImageFileToWorksheet SetRowHeight SetColumnWidth

    variable sUseTransparency

    set w [image width $phImg]
    set h [image height $phImg]

    Excel SetRowsHeight   $worksheetId $row [expr {$row + $h -1}] $rowHeight
    Excel SetColumnsWidth $worksheetId $col [expr {$col + $w -1}] $colWidth

    set curRow $row
    for { set y 0 } { $y < $h } { incr y } {
        set curCol $col
        for { set x 0 } { $x < $w } { incr x } {
            set rangeId [Excel SelectCellByIndex $worksheetId $curRow $curCol]
            if { $sUseTransparency } {
                if { [$phImg transparency get $x $y] } {
                    $rangeId -with { Interior } Pattern $::Excel::xlNone
                } else {
                    set rgb [$phImg get $x $y]
                    lassign $rgb r g b
                    Excel SetRangeFillColor $rangeId $r $g $b
                }
            } else {
                set rgb [$phImg get $x $y]
                lassign $rgb r g b
                Excel SetRangeFillColor $rangeId $r $g $b
            }
            incr curCol
            Cawt Destroy $rangeId
        }
        incr curRow
    }
}

proc ::Excel::Import {rangeId fileName args} {

    # Import data from an external data source.
    #
    # rangeId  - Identifier of the cell range.
    # fileName - File name of the data source.
    # args     - Options described below.
    #
    # -delimiter <char>          - Delimiter character. Possible values: `"\t" " " ";" ","`.
    # -decimalseparator <char>   - Decimal separator character.
    # -thousandsseparator <char> - Thousands separator character.
    #
    # Returns no value.
    #
    # See also: OpenWorkbook SaveAsCsv

    set worksheetId [$rangeId Worksheet]
    set queryTableId [$worksheetId -with { QueryTables } Add  "TEXT;$fileName" $rangeId]
    Cawt Destroy $worksheetId
    $queryTableId TextFileConsecutiveDelimiter [Cawt TclBool true]
    foreach { key value } $args {
        if { $value eq "" } {
            error "Import: No value specified for key \"$key\""
        }
        switch -exact -nocase -- $key {
            "-delimiter" {
                if { $value eq "," } {
                    $queryTableId TextFileCommaDelimiter [Cawt TclBool true]
                }
                if { $value eq ";" } {
                    $queryTableId TextFileSemicolonDelimiter [Cawt TclBool true]
                }
                if { $value eq "\t" } {
                    $queryTableId TextFileTabDelimiter [Cawt TclBool true]
                }
                if { $value eq " " } {
                    $queryTableId TextFileSpaceDelimiter [Cawt TclBool true]
                }
            }
            "-decimalseparator" {
                $queryTableId TextFileDecimalSeparator $value
            }
            "-thousandsseparator" {
                $queryTableId TextFileThousandsSeparator $value
            }
            default {
                error "Import: Unknown key \"$key\" specified"
            }
        }
    }
    $queryTableId Refresh
    Cawt Destroy $queryTableId
}

proc ::Excel::InsertColumn {worksheetId col} {

    # Insert a new empty column.
    #
    # worksheetId - Identifier of the worksheet.
    # col         - Column number. Column numbering starts with 1.
    #
    # A new empty column is inserted at given column number.
    #
    # Returns no value.
    #
    # See also: DeleteColumn DuplicateColumn HideColumn InsertRow

    set cell [Excel SelectCellByIndex $worksheetId 1 $col]
    $cell -with { EntireColumn } Insert $::Excel::xlToRight $::Excel::xlFormatFromLeftOrAbove
    Cawt Destroy $cell
}

proc ::Excel::InsertImage {worksheetId imgFileName {row 1} {col 1} {linkToFile false} {saveWithDoc true}} {

    # Insert an image into a worksheet.
    #
    # worksheetId - Identifier of the worksheet where the image is inserted.
    # imgFileName - File name of the image.
    # row         - Row number. Row numbering starts with 1.
    # col         - Column number. Column numbering starts with 1.
    # linkToFile  - Insert a link to the image file.
    # saveWithDoc - Embed the image into the document.
    #
    # The file name of the image must be an absolute pathname. Use a
    # construct like `[file join [pwd] "myImage.gif"]` to insert
    # images from the current directory.
    #
    # If both $linkToFile and $saveWithDoc are set to false, an error is thrown.
    #
    # Returns the identifier of the inserted image as a shape.
    #
    # See also: ScaleImage

    if { ! $linkToFile && ! $saveWithDoc } {
        error "InsertImage: linkToFile and saveWithDoc are both set to false."
    }

    set cellId [Excel SelectCellByIndex $worksheetId $row $col true]
    set fileName [file nativename [file normalize $imgFileName]]
    set shapeId [$cellId -with { Parent Shapes } AddPicture $fileName  [Cawt TclInt $linkToFile]  [Cawt TclInt $saveWithDoc]  [$cellId Left] [$cellId Top] -1 -1]
    Cawt Destroy $cellId
    return $shapeId
}

proc ::Excel::InsertRow {worksheetId row} {

    # Insert a new empty row.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    #
    # A new empty row is inserted at given row number.
    #
    # Returns no value.
    #
    # See also: DeleteRow DuplicateRow HideRow InsertColumn

    set cell [Excel SelectCellByIndex $worksheetId $row 1]
    $cell -with { EntireRow } Insert $::Excel::xlDown $::Excel::xlFormatFromLeftOrAbove
    Cawt Destroy $cell
}

proc ::Excel::IsWorkbookId {objId} {

    # Check, if Excel object is a workbook identifier.
    #
    # objId - The identifier of an Excel object.
    #
    # Returns true, if $objId is a valid Excel workbook identifier.
    # Otherwise returns false.
    #
    # See also: ::Cawt::IsComObject ::Office::GetApplicationId

    set retVal [catch {$objId ActiveSheet} errMsg]
    # ActiveSheet is a property of the workbook class.
    if { $retVal == 0 } {
        return true
    } else {
        return false
    }
}

proc ::Excel::IsWorkbookOpen {appId workbookName} {

    # Check, if a workbook is open.
    #
    # appId        - Identifier of the Excel instance.
    # workbookName - Name of the workbook to find.
    #
    # Returns true, if the workbook is open, otherwise false.
    #
    # See also: OpenWorkbook IsWorkbookProtected

    set retVal [catch {Excel GetWorkbookIdByName $appId $workbookName} errMsg]
    if { $retVal == 0 } {
        return true
    } else {
        return false
    }
}

proc ::Excel::IsWorkbookProtected {workbookId} {

    # Check, if a workbook is protected.
    #
    # workbookId - Identifier of the workbook to be checked.
    #
    # Returns true, if the workbook is protected, otherwise false.
    #
    # See also: OpenWorkbook IsWorkbookOpen

    if { [$workbookId ProtectWindows] } {
        return true
    } else {
        return false
    }
}

proc ::Excel::IsWorksheetEmpty {worksheetId} {

    # Check, if a worksheet is empty.
    #
    # worksheetId - Identifier of the worksheet to be checked.
    #
    # Returns true, if the worksheet is empty, otherwise false.
    #
    # See also: GetNumUsedRows GetNumUsedColumns GetFirstUsedRow GetLastUsedRow

    if { [GetLastUsedRow    $worksheetId] == 1 &&  [GetLastUsedColumn $worksheetId] == 1 &&  [GetCellValue $worksheetId 1 1] eq "" } {
        return true
    }
    return false
}

proc ::Excel::IsWorksheetProtected {worksheetId} {

    # Check, if a worksheet is content protected.
    #
    # worksheetId - Identifier of the worksheet to be checked.
    #
    # Returns true, if the worksheet is protected, otherwise false.
    #
    # See also: AddWorksheet

    if { [$worksheetId ProtectContents] } {
        return true
    } else {
        return false
    }
}

proc ::Excel::IsWorksheetVisible {worksheetId} {

    # Check, if a worksheet is visible.
    #
    # worksheetId - Identifier of the worksheet to be checked.
    #
    # Returns true, if the worksheet is visible, otherwise false.
    #
    # See also: AddWorksheet

    if { [$worksheetId Visible] == $::Excel::xlSheetVisible } {
        return true
    } else {
        return false
    }
}

proc ::Excel::ListToCsvRow {rowList} {

    # Return a list of column values as a `CSV` encoded row string.
    #
    # rowList - List of column values.
    #
    # Returns the list of column values as a `CSV` encoded row string.
    #
    # See also: CsvRowToList

    variable sSepChar

    set rowStr ""
    set len1 [expr [llength $rowList] -1]
    set curVal 0
    foreach val $rowList {
        set tmp [string map {\n\r \ } $val]
        if { [string first $sSepChar $tmp] >= 0 ||  [string first "\"" $tmp] >= 0 } {
            regsub -all {"} $tmp {""} tmp
            set tmp [format "\"%s\"" $tmp]
        }
        if { $curVal < $len1 } {
            append rowStr $tmp $sSepChar
        } else {
            append rowStr $tmp
        }
        incr curVal
    }
    return $rowStr
}

proc ::Excel::MapWorksheetName {name} {

    # Map the name of a worksheet to confirm to Excel constraints.
    #
    # name - Name of the worksheet.
    #
    # The following characters are not allowed in worksheet names
    # and are thus mapped as follows:
    #     [ to (
    #     ] to )
    #     \ to _
    #     / to _
    #     ? to |
    #     * to +
    #     : to ;
    #
    # After mapping, the string is truncated to 31 characters,
    # which is the maximum length of a worksheet name.
    #
    # Returns the mapped worksheet name.
    #
    # See also: SetWorksheetName AddWorksheet

    set mapped [string map { "\[" "("  "\]" ")"  "\\" "_"  "/" "_"  "?" "|"  "*" "+"  ":" ";" } $name]
    set sheetName [string range $mapped 0 30]
    return $sheetName
}

proc ::Excel::MatlabFileToExcelFile {matFileName excelFileName {useHeader true} {quitExcel true}} {

    # Convert a Matlab table file to an Excel file.
    #
    # matFileName   - Name of the Matlab input file.
    # excelFileName - Name of the Excel output file.
    # useHeader     - If set to true, insert the header of the Matlab file as first row.
    #                 Otherwise only transfer the data values as floating point values.
    # quitExcel     - If set to true, quit the Excel instance after generation of output file.
    #                 Otherwise leave the Excel instance open after generation of output file.
    #
    # The table data from the Matlab file will be inserted into a worksheet name "Matlab".
    #
    # **Note:** Only Matlab Level 4 files are currently supported.
    #
    # Returns the Excel application identifier, if $quitExcel is false.
    # Otherwise no return value.
    #
    # See also: MatlabFileToWorksheet ExcelFileToMatlabFile ReadMatlabFile

    set appId [Excel OpenNew true]
    set workbookId [Excel AddWorkbook $appId]
    set worksheetId [Excel AddWorksheet $workbookId "Matlab"]
    Excel MatlabFileToWorksheet $matFileName $worksheetId $useHeader
    Excel SaveAs $workbookId $excelFileName
    if { $quitExcel } {
        Excel Quit $appId
    } else {
        return $appId
    }
}

proc ::Excel::MatlabFileToWorksheet {matFileName worksheetId {useHeader true}} {

    # Insert the data values of a Matlab file into a worksheet.
    #
    # matFileName - Name of the Matlab file.
    # worksheetId - Identifier of the worksheet.
    # useHeader   - If set to true, insert the header of the Matlab file as first row.
    #               Otherwise only transfer the data values as floating point values.
    #
    # The header information are as follows: `MatlabVersion Width Height`
    #
    # **Note:** Only Matlab Level 4 files are currently supported.
    #
    # Returns no value.
    #
    # See also: WorksheetToMatlabFile SetMatrixValues
    # WikitFileToWorksheet MediaWikiFileToWorksheet RawImageFileToWorksheet
    # TablelistToWorksheet WordTableToWorksheet

    set startRow 1
    if { $useHeader } {
        set headerList [Excel ReadMatlabHeader $matFileName]
        Excel SetHeaderRow $worksheetId $headerList
        Excel FreezePanes $worksheetId 1 0 true
        incr startRow
    }
    set matrixList [Excel ReadMatlabFile $matFileName]
    Excel SetMatrixValues $worksheetId $matrixList $startRow 1
}

proc ::Excel::MatrixToClipboard {matrixList {sepChar {;}}} {

    # Copy a matrix into the clipboard.
    #
    # matrixList - Matrix with table data.
    # sepChar    - The separation character of the clipboard matrix data.
    #
    # The clipboard data will be in `CSV` format with $sepChar as separation character.
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns no value.
    #
    # See also: WorksheetToClipboard ClipboardToMatrix

    set csvFmt [twapi::register_clipboard_format "Csv"]
    twapi::open_clipboard
    twapi::empty_clipboard
    Excel SetCsvSeparatorChar $sepChar
    twapi::write_clipboard $csvFmt [Excel MatrixToCsvString $matrixList]
    twapi::close_clipboard
}

proc ::Excel::MatrixToCsvString {matrixList} {

    # Return a `CSV` encoded table string from a matrix list.
    #
    # matrixList - Matrix with table data.
    #
    # Returns the `CSV` encoded table string from a matrix list.
    #
    # See also: CsvStringToMatrix ListToCsvRow

    foreach rowList $matrixList {
        append str [Excel ListToCsvRow $rowList]
        append str "\n"
    }
    return [string range $str 0 end-1]
}

proc ::Excel::MediaWikiFileToExcelFile {wikiFileName excelFileName {useHeader true} {quitExcel true}} {

    # Convert a MediaWiki table file to an Excel file.
    #
    # wikiFileName  - Name of the MediaWiki input file.
    # excelFileName - Name of the Excel output file.
    # useHeader     - If set to true, use header information from the MediaWiki file to
    #                 generate an Excel header (see [SetHeaderRow]).
    #                 Otherwise only transfer the table data.
    # quitExcel     - If set to true, quit the Excel instance after generation of output file.
    #                 Otherwise leave the Excel instance open after generation of output file.
    #
    # The table data from the MediaWiki file will be inserted into a worksheet named "MediaWiki".
    #
    # Returns the Excel application identifier, if $quitExcel is false.
    # Otherwise no return value.
    #
    # See also: MediaWikiFileToWorksheet ExcelFileToMediaWikiFile
    # ReadMediaWikiFile WriteMediaWikiFile WikitFileToExcelFile

    set appId [Excel OpenNew true]
    set workbookId [Excel AddWorkbook $appId]
    set worksheetId [Excel AddWorksheet $workbookId "MediaWiki"]
    Excel MediaWikiFileToWorksheet $wikiFileName $worksheetId $useHeader
    Excel SaveAs $workbookId $excelFileName
    if { $quitExcel } {
        Excel Quit $appId
    } else {
        return $appId
    }
}

proc ::Excel::MediaWikiFileToWorksheet {wikiFileName worksheetId {useHeader true}} {

    # Insert the values of a MediaWiki table file into a worksheet.
    #
    # wikiFileName - Name of the MediaWiki file.
    # worksheetId  - Identifier of the worksheet.
    # useHeader    - If set to true, insert the header of the MediaWiki table as first row.
    #                Otherwise only transfer the table data.
    #
    # The insertion starts at row and column 1.
    # Values contained in the worksheet cells are overwritten.
    #
    # Returns no value.
    #
    # See also: WorksheetToMediaWikiFile SetMatrixValues
    # WikitFileToWorksheet WordTableToWorksheet MatlabFileToWorksheet
    # RawImageFileToWorksheet TablelistToWorksheet

    set catchVal [catch {open $wikiFileName "r"} fp]
    if { $catchVal != 0 } {
        error "Could not open file \"$wikiFileName\" for reading."
    }

    # TODO |- style="background:green"
    set row      1
    set firstRow true
    set rowList  {}

    while { [gets $fp line] >= 0 } {
        if { [string index $line 0] eq "!" && $useHeader } {
            # Found a header line. Currently only headers with "!!" separators are supported.
            set headerList [Excel::_MediaWikiRowString2List $line "!!"]
            Excel SetHeaderRow $worksheetId $headerList
            incr row
        } elseif { [string range $line 0 1] eq "|+" } {
            set worksheetName [string trim [string range $line 2 end]]
            Excel SetWorksheetName $worksheetId $worksheetName
        } elseif { [string range $line 0 1] eq "|-" ||  [string range $line 0 1] eq "|\}" } {
            if { $firstRow } {
                set firstRow false
                continue
            }
            if { [llength $rowList] != 0 } {
                Excel SetRowValues $worksheetId $row $rowList
                incr row
            }
            set rowList {}
        } elseif { [string index $line 0] eq "|" } {
            if { [string first "||" $line] >= 0 } {
                set rowList [Excel::_MediaWikiRowString2List $line "||"]
            } else {
                lappend rowList [Excel::_MediaWikiSubstHtml [string range $line 1 end]]
            }
        }
    }
    close $fp
}

proc ::Excel::Open {{visible true} {width -1} {height -1}} {

    # Open an Excel instance. Use an already running instance, if available.
    #
    # visible - If set to true, show the application window.
    #           Otherwise hide the application window.
    # width   - Width of the application window. If negative, open with last used width.
    # height  - Height of the application window. If negative, open with last used height.
    #
    # Returns the identifier of the Excel application instance.
    #
    # See also: OpenNew Quit Visible

    variable excelAppName
    variable excelVersion

    set appId [Cawt GetOrCreateApp $excelAppName true]
    set excelVersion [Excel GetVersion $appId]
    Excel::_setFloatSeparator $appId
    Excel Visible $appId $visible
    if { $width >= 0 } {
        $appId Width [expr $width]
    }
    if { $height >= 0 } {
        $appId Height [expr $height]
    }
    return $appId
}

proc ::Excel::OpenNew {{visible true} {width -1} {height -1}} {

    # Open a new Excel instance.
    #
    # visible - If set to true, show the application window.
    #           Otherwise hide the application window.
    # width   - Width of the application window. If negative, open with last used width.
    # height  - Height of the application window. If negative, open with last used height.
    #
    # Returns the identifier of the new Excel application instance.
    #
    # See also: Open Quit Visible

    variable excelAppName
    variable excelVersion

    set appId [Cawt GetOrCreateApp $excelAppName false]
    set excelVersion [Excel GetVersion $appId]
    Excel::_setFloatSeparator $appId
    Excel Visible $appId $visible
    if { $width >= 0 } {
        $appId Width [expr $width]
    }
    if { $height >= 0 } {
        $appId Height [expr $height]
    }
    return $appId
}

proc ::Excel::OpenWorkbook {appId fileName args} {

     # Open a workbook, i.e. load an Excel file.
     #
     # appId    - Identifier of the Excel instance.
     # fileName - Name of the Excel file.
     # args     - Options described below.
     #
     # -readonly <bool> - If set to true, open the workbook in read-only mode.
     #                    Default is to open the workbook in read-write mode.
     # -embed <frame>   - Embed the workbook into a Tk frame. This frame must
     #                    exist and must be created with option `-container true`.
     #
     # Returns the identifier of the opened workbook. If the workbook was
     # already open, activate that workbook and return the identifier to
     # that workbook.
     #
     # See also: AddWorkbook Close SaveAs

    set opts [dict create  -readonly false    -embed    ""       ]
     if { [llength $args] == 1 } {
         # Old mode with optional boolean parameter readOnly
         dict set opts -readonly [lindex $args 0]
     } else {
         foreach { key value } $args {
             if { [dict exists $opts $key] } {
                 if { $value eq "" } {
                     error "OpenWorkbook: No value specified for key \"$key\"."
                 }
                 dict set opts $key $value
             } else {
                 error "OpenWorkbook: Unknown option \"$key\" specified."
             }
         }
     }

     if { [Excel IsWorkbookOpen $appId $fileName] } {
         set workbookId [Excel GetWorkbookIdByName $appId $fileName]
         $workbookId Activate
     } else {
         set workbooks [$appId Workbooks]
         # Open(Filename As String, [UpdateLinks], [ReadOnly], [Format],
         # [Password], [WriteResPassword], [IgnoreReadOnlyRecommended],
         # [Origin], [Delimiter], [Editable], [Notify], [Converter],
         # [AddToMru], [Local], [CorruptLoad])
         set workbookId [$workbooks -callnamedargs Open  Filename [file nativename [file normalize $fileName]]  ReadOnly [Cawt TclInt [dict get $opts "-readonly"]]]
         Cawt Destroy $workbooks
     }
     set embedFrame [dict get $opts "-embed"]
     if { $embedFrame ne "" } {
         set workbookWindows [$workbookId Windows]
         $workbookWindows -iterate window {
             set windowHndl [$window Hwnd]
             set windowId   [list $windowHndl HWND]
             break
         }
         Cawt Destroy $workbookWindows
         Cawt EmbedApp $embedFrame -appid [Office GetApplicationId $workbookId] -window $windowId
     }
     return $workbookId
}

proc ::Excel::PlaceChart {chartId worksheetId} {

    # Place an existing chart into a worksheet.
    #
    # chartId     - Identifier of the chart.
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the ChartObject identifier of the placed chart.
    #
    # See also: CreateChart SetChartObjSize SetChartObjPosition

    set newChartId [$chartId Location $::Excel::xlLocationAsObject  [Excel GetWorksheetName $worksheetId]]
    return $newChartId
}

proc ::Excel::Quit {appId {showAlert true}} {

    # Quit an Excel instance.
    #
    # appId     - Identifier of the Excel instance.
    # showAlert - If set to true, show an alert window, if there are unsaved changes.
    #             Otherwise quit without asking and saving any changes.
    #
    # Returns no value.
    #
    # See also: Open OpenNew

    Excel::ShowAlerts $appId $showAlert
    $appId Quit
}

proc ::Excel::RawImageFileToExcelFile {rawFileName excelFileName {useHeader true} {quitExcel true}} {

    # Convert a raw photo image file to an Excel file.
    #
    # rawFileName   - Name of the raw photo image input file.
    # excelFileName - Name of the Excel output file.
    # useHeader     - If set to true, use header information from the image file to
    #                 generate an Excel header (see [SetHeaderRow]).
    #                 Otherwise only transfer the image data.
    # quitExcel     - If set to true, quit the Excel instance after generation of output file.
    #                 Otherwise leave the Excel instance open after generation of output file.
    #
    # The table data from the image file will be inserted into a worksheet named "RawImage".
    #
    # Returns the Excel application identifier, if $quitExcel is false.
    # Otherwise no return value.
    #
    # See also: RawImageFileToWorksheet ExcelFileToRawImageFile ReadRawImageFile WriteRawImageFile

    set appId [Excel OpenNew true]
    set workbookId [Excel AddWorkbook $appId]
    set worksheetId [Excel AddWorksheet $workbookId "RawImage"]
    Excel RawImageFileToWorksheet $rawFileName $worksheetId $useHeader
    Excel SaveAs $workbookId $excelFileName
    if { $quitExcel } {
        Excel Quit $appId
    } else {
        return $appId
    }
}

proc ::Excel::RawImageFileToWorksheet {rawFileName worksheetId {useHeader true}} {

    # Insert the pixel values of a raw photo image into a worksheet.
    #
    # rawFileName - File name of the image.
    # worksheetId - Identifier of the worksheet.
    # useHeader   - If set to true, insert the header of the raw image as first row.
    #               Otherwise only transfer the pixel values as floating point values.
    #
    # The header information are as follows:
    # `Magic Width Height NumChan ByteOrder ScanOrder PixelType`
    #
    # **Note:** Only 1-channel floating-point raw images are currently supported.
    #
    # Returns no value.
    #
    # See also: WorksheetToRawImageFile SetMatrixValues
    # WikitFileToWorksheet MediaWikiFileToWorksheet MatlabFileToWorksheet
    # TablelistToWorksheet WordTableToWorksheet

    set startRow 1
    if { $useHeader } {
        set headerList [Excel ReadRawImageHeader $rawFileName]
        Excel SetHeaderRow $worksheetId $headerList
        Excel FreezePanes $worksheetId 1 0 true
        incr startRow
    }
    set matrixList [Excel ReadRawImageFile $rawFileName]
    Excel SetMatrixValues $worksheetId $matrixList $startRow 1
}

proc ::Excel::ReadCsvFile {csvFileName {useHeader true} {numHeaderRows 0}} {

    # Read a `CSV` table file into a matrix.
    #
    # csvFileName   - Name of the `CSV` file.
    # useHeader     - If set to true, insert the header rows of the `CSV` file into the matrix.
    #                 Otherwise only transfer the table data.
    # numHeaderRows - Number of rows interpreted as header rows.
    #
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns the `CSV` table data as a matrix.
    #
    # See also: WriteCsvFile

    variable sSepChar

    set matrixList {}
    set rowCount 1

    set catchVal [catch {open $csvFileName r} fp]
    if { $catchVal != 0 } {
        error "Could not open file \"$csvFileName\" for reading."
    }
    fconfigure $fp -translation binary

    # Read some bytes and search for \r\n to detect a DOS file.
    set test [read $fp 4096]
    if { [string match "*\r\n*" $test] } {
        fconfigure $fp -translation crlf
    } else {
        fconfigure $fp -translation lf
    }
    seek $fp 0

    while { [gets $fp row] >= 0 } {
        if { $rowCount <= $numHeaderRows && ! $useHeader } {
            incr rowCount
            continue
        }

        set tmpList [Excel CsvRowToList $row]
        lappend matrixList $tmpList
        incr rowCount
    }

    close $fp
    return $matrixList
}

proc ::Excel::ReadMatlabFile {matFileName} {

    # Read a Matlab file into a matrix.
    #
    # matFileName - Name of the Matlab file.
    #
    # **Note:** Only Matlab Level 4 files are currently supported.
    #
    # Returns the Matlab file data as a matrix.
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # See also: ReadMatlabHeader WriteMatlabFile MatlabFileToWorksheet

    set retVal [catch {open $matFileName "r"} matFp]
    if { $retVal != 0 } {
        error "Cannot open file $matFileName"
    }
    fconfigure $matFp -translation binary

    set headerList [Excel::_GetMatlabHeader $matFp]
    lassign $headerList version width height

    # Parse a Level 4 MAT-File
    if { $version == 4 } {
        set bytesPerPixel 8
        for { set col 0 } { $col < $width } { incr col } {
            for { set row 0 } { $row < $height } { incr row } {
                set valBytes [read $matFp $bytesPerPixel]
                binary scan $valBytes d val
                lappend rowList($row) $val
            }
        }
    }

    for { set row 0 } { $row < $height } { incr row } {
        lappend matrixList $rowList($row)
    }

    close $matFp
    return $matrixList
}

proc ::Excel::ReadMatlabHeader {matFileName} {

    # Read the header of a Matlab file.
    #
    # matFileName - Name of the Matlab file.
    #
    # Returns the header information as a list of integers containing the
    # following values: `MatlabVersion Width Height`
    #
    # See also: ReadMatlabFile

    set retVal [catch {open $matFileName "r"} matFp]
    if { $retVal != 0 } {
        error "Cannot open file $matFileName"
    }
    fconfigure $matFp -translation binary
    set headerList [Excel::_GetMatlabHeader $matFp]
    close $matFp
    return $headerList
}

proc ::Excel::ReadMediaWikiFile {wikiFileName {useHeader true}} {

    # Read a MediaWiki table file into a matrix.
    #
    # wikiFileName - Name of the MediaWiki file.
    # useHeader    - If set to true, insert the header of the MediaWiki table as first row.
    #                Otherwise only transfer the table data.
    #
    # Returns the MediaWiki table data as a matrix.
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # See also: WriteMediaWikiFile MediaWikiFileToWorksheet

    set tmpList  {}
    set matrixList {}
    set firstRow true

    set catchVal [catch {open $wikiFileName r} fp]
    if { $catchVal != 0 } {
        error "Could not open file \"$wikiFileName\" for reading."
    }

    while { [gets $fp line] >= 0 } {
        if { [string index $line 0] eq "!" && $useHeader } {
            set tmpList [Excel::_MediaWikiRowString2List $line "!!"]
        } elseif { [string range $line 0 1] eq "|-" ||  [string range $line 0 1] eq "|\}" } {
            if { $firstRow } {
                set firstRow false
                continue
            }
            lappend matrixList $tmpList
            set tmpList {}
        } elseif { [string index $line 0] eq "|" } {
            if { [string first "||" $line] >= 0 } {
                set tmpList [Excel::_MediaWikiRowString2List $line "||"]
            } else {
                lappend tmpList [Excel::_MediaWikiSubstHtml [string range $line 1 end]]
            }
        }
    }
    close $fp
    return $matrixList
}

proc ::Excel::ReadRawImageFile {rawImgFile} {

    # Read a raw photo image into a matrix.
    #
    # rawImgFile - File name of the image.
    #
    # **Note:** Only 1-channel floating-point raw images are currently supported.
    #
    # Returns the image data as a matrix.
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # See also: ReadRawImageHeader WriteRawImageFile RawImageFileToWorksheet

    set retVal [catch {open $rawImgFile "r"} rawFp]
    if { $retVal != 0 } {
        error "Cannot open file $rawImgFile"
    }
    fconfigure $rawFp -translation binary

    set headerList [Excel::_GetRawImageHeader $rawFp]
    lassign $headerList magic width height numChans byteOrder scanOrder pixelType

    if { $numChans != 1 } {
        error "Only 1-channel images currently supported."
    }
    set scanFmt [Excel::_GetScanFormat $pixelType $byteOrder]
    set pixelSize [Excel::_GetPixelSize $pixelType]

    set numVals [expr {$width*$height}]
    for { set row 0 } { $row < $height } { incr row } {
        for { set col 0 } { $col < $width } { incr col } {
            set valBytes [read $rawFp $pixelSize]
            binary scan $valBytes $scanFmt val
            lappend rowList($row) $val
        }
    }

    if { $scanOrder eq "TopDown" } {
        for { set row 0 } { $row < $height } { incr row } {
            lappend matrixList $rowList($row)
        }
    } else {
        for { set row [expr $height-1] } { $row >= 0 } { incr row -1 } {
            lappend matrixList $rowList($row)
        }
    }

    close $rawFp
    return $matrixList
}

proc ::Excel::ReadRawImageHeader {rawImgFile} {

    # Read the header of a raw photo image.
    #
    # rawImgFile - File name of the image.
    #
    # Returns the header information as a list containing the following values:
    # `Magic Width Height NumChan ByteOrder ScanOrder PixelType`
    #
    # See also: ReadRawImageFile

    set retVal [catch {open $rawImgFile "r"} rawFp]
    if { $retVal != 0 } {
        error "Cannot open file $rawImgFile"
    }
    fconfigure $rawFp -translation binary
    set headerList [Excel::_GetRawImageHeader $rawFp]
    close $rawFp
    return $headerList
}

proc ::Excel::ReadWikitFile {wikiFileName {useHeader true}} {

    # Read a Wikit table file into a matrix.
    #
    # wikiFileName - Name of the Wikit file.
    # useHeader    - If set to true, insert the header of the Wikit table as first row.
    #                Otherwise only transfer the table data.
    #
    # Returns the Wikit table data as a matrix.
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # See also: WriteWikitFile WikitFileToWorksheet

    set catchVal [catch {open $wikiFileName r} fp]
    if { $catchVal != 0 } {
        error "Could not open file \"$wikiFileName\" for reading."
    }

    set matrixList [list]
    while { [gets $fp line] >= 0 } {
        set line [string trim $line]
        if { ( [string range $line 0 1] eq "%|" && $useHeader ) } {
            set rowStr [string map {"%|" "" "|%" "" } $line]
        } elseif { [string range $line 0 1] eq "&|" } {
            set rowStr [string map {"&|" "" "|&" "" } $line]
        } elseif { [string index $line 0] eq "|" } {
            set rowStr [string range $line 1 end-1]
        }
        lappend matrixList [Excel::_WikitRowString2List $rowStr]
    }
    close $fp
    return $matrixList
}

proc ::Excel::ResizeChartObj {chartObjId rangeId} {

    # Set the position and size of a chart object.
    #
    # chartObjId - Identifier of the chart object.
    # rangeId    - Identifier of the cell range.
    #
    # Resize the chart object so that it fits into the specified cell range.
    #
    # Returns no value.
    #
    # See also: PlaceChart SetChartObjSize SetChartObjPosition SelectRangeByString

    set chart [$chartObjId Parent]
    $chart Width  [$rangeId Width]
    $chart Height [$rangeId Height]
    $chart Left   [$rangeId Left]
    $chart Top    [$rangeId Top]
    Cawt Destroy $chart
}

proc ::Excel::SaveAs {workbookId fileName {fmt {}} {backup false}} {

    # Save a workbook to an Excel file.
    #
    # workbookId - Identifier of the workbook to save.
    # fileName   - Name of the Excel file.
    # fmt        - Value of enumeration type [Enum::XlFileFormat].
    #              If not given or the empty string, the file is stored in the
    #              native format corresponding to the used Excel version.
    # backup     - If set to true, create a backup file before saving.
    #              Otherwise do not create a backup file.
    #
    # Note, that if you have read a `CSV` file with [OpenWorkbook] and save it with
    # this procedure without specifying a format, the saved file will be in `CSV`
    # format, too. Specify `xlWorkbookDefault` as format, if the file should be
    # an Excel file.
    #
    # Returns no value.
    #
    # See also: SaveAsCsv Close OpenWorkbook

    set fileName [file nativename [file normalize $fileName]]
    set appId [Office GetApplicationId $workbookId]
    Excel::ShowAlerts $appId false
    if { $fmt eq "" } {
        $workbookId SaveAs $fileName
    } else {
        # SaveAs([Filename], [FileFormat], [Password],
        # [WriteResPassword], [ReadOnlyRecommended], [CreateBackup],
        # [AccessMode As XlSaveAsAccessMode = xlNoChange],
        # [ConflictResolution], [AddToMru], [TextCodepage],
        # [TextVisualLayout], [Local])
        $workbookId -callnamedargs SaveAs  FileName $fileName  FileFormat [Excel GetEnum $fmt]  CreateBackup [Cawt TclInt $backup]
    }
    Excel::ShowAlerts $appId true
    Cawt Destroy $appId
}

proc ::Excel::SaveAsCsv {workbookId worksheetId fileName {fmt xlCSV}} {

    # Save a worksheet to file in `CSV` format.
    #
    # workbookId  - Identifier of the workbook containing the worksheet.
    # worksheetId - Identifier of the worksheet to save.
    # fileName    - Name of the `CSV` file.
    # fmt         - Value of enumeration type [Enum::XlFileFormat].
    #
    # Returns no value.
    #
    # See also: SaveAs Close OpenWorkbook

    set fileName [file nativename [file normalize $fileName]]
    set appId [Office GetApplicationId $workbookId]
    Excel::ShowAlerts $appId false
    # SaveAs(Filename As String, [FileFormat], [Password],
    # [WriteResPassword], [ReadOnlyRecommended], [CreateBackup],
    # [AddToMru], [TextCodepage], [TextVisualLayout], [Local])
    $worksheetId -callnamedargs SaveAs  Filename $fileName  FileFormat [Excel GetEnum $fmt]
    Excel::ShowAlerts $appId true
    Cawt Destroy $appId
}

proc ::Excel::SaveChartAsImage {chartId fileName {filterType GIF}} {

    # Obsolete: Replaced with [SaveChartObjAsImage] in version 1.0.1

    Excel SaveChartObjAsImage $chartId $fileName $filterType
}

proc ::Excel::SaveChartObjAsImage {chartObjId fileName {filterType GIF}} {

    # Save a chart as an image in a file.
    #
    # chartObjId - Identifier of the chart object.
    # fileName   - Image file name.
    # filterType - Name of graphic filter. Possible values: `GIF`, `JPEG`, `PNG`.
    #
    # Returns no value.
    #
    # See also: ChartObjToClipboard CreateChart

    set fileName [file nativename [file normalize $fileName]]
    $chartObjId Export $fileName $filterType
}

proc ::Excel::ScaleImage {shapeId scaleWidth scaleHeight} {

    # Scale an image.
    #
    # shapeId     - Identifier of the image shape.
    # scaleWidth  - Horizontal scale factor.
    # scaleHeight - Vertical scale factor.
    #
    # The scale factors are floating point values. 1.0 means no scaling.
    #
    # Returns no value.
    #
    # See also: InsertImage

    $shapeId LockAspectRatio [Cawt TclInt false]
    $shapeId ScaleWidth  [expr double($scaleWidth)]  [Cawt TclInt true]
    $shapeId ScaleHeight [expr double($scaleHeight)] [Cawt TclInt true]
}

proc ::Excel::ScreenUpdate {appId onOff} {

    # Toggle the screen updating of an Excel application window.
    #
    # appId - Identifier of the Excel instance.
    # onOff - If set to true, update the application window.
    #         Otherwise do not update the application window.
    #
    # Returns no value.
    #
    # See also: Visible SetWindowState ArrangeWindows

    $appId ScreenUpdating [Cawt TclBool $onOff]
}

proc ::Excel::Search {worksheetId str {row1 1} {col1 1} {row2 -1} {col2 -1}} {

    # Find a string in a worksheet cell range.
    #
    # worksheetId - Identifier of the worksheet.
    # str         - Search string.
    # row1        - Row number of upper-left corner of the cell range.
    # col1        - Column number of upper-left corner of the cell range.
    # row2        - Row number of lower-right corner of the cell range.
    # col2        - Column number of lower-right corner of the cell range.
    #
    # If $row2 or $col2 is negative, all used rows and columns are searched.
    #
    # Returns the first matching cell as a 2-element list `{row, col}` of indices.
    # If no cell matches the search criteria, an empty list is returned.

    if { $row2 < 0 } {
        set row2 [Excel GetLastUsedRow $worksheetId]
    }
    if { $col2 < 0 } {
        set col2 [Excel GetLastUsedColumn $worksheetId]
    }

    set matrixList [Excel GetMatrixValues $worksheetId $row1 $col1 $row2 $col2]
    set row 1
    foreach rowList $matrixList {
        set col [lsearch -exact $rowList $str]
        if { $col >= 0 } {
            return [list $row [expr {$col + 1}]]
        }
        incr row
    }
    return [list]
}

proc ::Excel::SelectAll {worksheetId} {

    # Select all cells of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # Returns the cells collection of the selected cells.
    #
    # See also: CopyWorksheet

    set appId [Office GetApplicationId $worksheetId]
    set cellsId [$appId Cells]
    Cawt Destroy $appId
    return $cellsId
}

proc ::Excel::SelectCellByIndex {worksheetId row col {visSel false}} {

    # Select a cell by its row/column index.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # col         - Column number. Column numbering starts with 1.
    # visSel      - If set to true, see the selection in the user interface.
    #               Otheriwse the selection is not visible.
    #
    # Returns the identifier of the cell as a range identifier.
    #
    # See also: SelectRangeByIndex AddWorksheet

    return [Excel SelectRangeByIndex $worksheetId $row $col $row $col $visSel]
}

proc ::Excel::SelectRangeByIndex {worksheetId row1 col1 row2 col2 {visSel false}} {

    # Select a range by specifying a numeric cell range.
    #
    # worksheetId - Identifier of the worksheet.
    # row1        - Row number of upper-left corner of the cell range.
    # col1        - Column number of upper-left corner of the cell range.
    # row2        - Row number of lower-right corner of the cell range.
    # col2        - Column number of lower-right corner of the cell range.
    # visSel      - If set to true, see the selection in the user interface.
    #               Otherwise the selection is not visible.
    #
    # Returns the range identifier of the cell range.
    #
    # See also: SelectRangeByString SelectCellByIndex GetCellRange

    set rangeStr [Excel GetCellRange $row1 $col1 $row2 $col2]
    return [Excel SelectRangeByString $worksheetId $rangeStr $visSel]
}

proc ::Excel::SelectRangeByString {worksheetId rangeStr {visSel false}} {

    # Select a range by specifying an Excel range string in A1 notation.
    #
    # worksheetId - Identifier of the worksheet.
    # rangeStr    - String specifying a cell range, ex. `A8:C10`.
    # visSel      - If set to true, see the selection in the user interface.
    #               Otherwise the selection is not visible.
    #
    # Returns the range identifier of the cell range.
    #
    # See also: SelectRangeByIndex GetCellRange

    set cellsId [Excel GetCellsId $worksheetId]
    set rangeId [$cellsId Range $rangeStr]
    if { $visSel } {
        $rangeId Select
    }
    Cawt Destroy $cellsId
    return $rangeId
}

proc ::Excel::SetCellValue {worksheetId row col val {fmt text} {subFmt {}}} {

    # Set the value of a cell.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # col         - Column number. Column numbering starts with 1.
    # val         - String value of the cell.
    # fmt         - Format of the cell. Possible values: `text`, `int`, `real`.
    # subFmt      - Formatting option of the floating-point value (see [SetRangeFormat]).
    #
    # The value to be inserted is interpreted either as string, integer or
    # floating-point number according to the formats specified in $fmt and $subFmt.
    #
    # Returns no value.
    #
    # See also: GetCellValue SetRowValues SetMatrixValues

    set cellsId [Excel GetCellsId $worksheetId]
    set cellId  [Excel GetCellIdByIndex $worksheetId $row $col]
    SetRangeFormat $cellId $fmt $subFmt
    if { $fmt eq "text" } {
        $cellsId Item [expr {int($row)}] [expr {int($col)}] [Cawt TclString $val]
    } elseif { $fmt eq "int" } {
        $cellsId Item [expr {int($row)}] [expr {int($col)}] [expr {int($val)}]
    } elseif { $fmt eq "real" } {
        $cellsId Item [expr {int($row)}] [expr {int($col)}] [expr {double($val)}]
    } else {
        error "SetCellValue: Unknown format $fmt"
    }
    Cawt Destroy $cellId
    Cawt Destroy $cellsId
}

proc ::Excel::SetChartMaxScale {chartId axisName value} {

    # Set the maximum scale of an axis of a chart.
    #
    # chartId  - Identifier of the chart.
    # axisName - Name of axis. Possible values: `x` or `y`.
    # value    - Scale value.
    #
    # Returns no value.
    #
    # See also: SetChartMinScale SetChartScale SetChartObjSize

    if { $axisName eq "x" || $axisName eq "X" } {
        set axis [$chartId -with { Axes } Item $::Excel::xlPrimary]
    } else {
        set axis [$chartId -with { Axes } Item $::Excel::xlSecondary]
    }
    $axis MaximumScale [expr {$value}]
    Cawt Destroy $axis
}

proc ::Excel::SetChartMinScale {chartId axisName value} {

    # Set the minimum scale of an axis of a chart.
    #
    # chartId  - Identifier of the chart.
    # axisName - Name of axis. Possible values: `x` or `y`.
    # value    - Scale value.
    #
    # Returns no value.
    #
    # See also: SetChartMaxScale SetChartScale SetChartObjSize

    if { $axisName eq "x" || $axisName eq "X" } {
        set axis [$chartId -with { Axes } Item $::Excel::xlPrimary]
    } else {
        set axis [$chartId -with { Axes } Item $::Excel::xlSecondary]
    }
    $axis MinimumScale [expr {$value}]
    Cawt Destroy $axis
}

proc ::Excel::SetChartObjPosition {chartObjId left top} {

    # Set the position of a chart object.
    #
    # chartObjId - Identifier of the chart object.
    # left       - Left border of the chart object in pixel.
    # top        - Top border of the chart object in pixel.
    #
    # Returns no value.
    #
    # See also: PlaceChart SetChartObjSize SetChartScale

    set chart [$chartObjId Parent]
    $chart Left $left
    $chart Top  $top
    Cawt Destroy $chart
}

proc ::Excel::SetChartObjSize {chartObjId width height} {

    # Set the size of a chart object.
    #
    # chartObjId - Identifier of the chart object.
    # width      - Width of the chart object in pixel.
    # height     - Height of the chart object in pixel.
    #
    # Returns no value.
    #
    # See also: PlaceChart SetChartObjPosition SetChartScale

    # This is also an Excel mystery. After setting the width and height
    # to the correct size (i.e. use width and height unchanged), Excel
    # says, it has changed the shape to the correct size.
    # But the diagram as displayed and also the exported bitmap has a
    # size 4/3 greater than expected.
    # We correct for that discrepancy here by multiplying with 3/4.

    set chart [$chartObjId Parent]
    $chart Width  [expr {$width  * 0.75}]
    $chart Height [expr {$height * 0.75}]
    Cawt Destroy $chart
}

proc ::Excel::SetChartScale {chartId xmin xmax ymin ymax} {

    # Set the minimum and maximum scale of both axes of a chart.
    #
    # chartId - Identifier of the chart.
    # xmin    - Minimum scale value of x axis.
    # xmax    - Maximum scale value of x axis.
    # ymin    - Minimum scale value of y axis.
    # ymax    - Maximum scale value of y axis.
    #
    # Returns no value.
    #
    # See also: SetChartMinScale SetChartMaxScale SetChartObjSize

    Excel SetChartMinScale $chartId "x" $xmin
    Excel SetChartMaxScale $chartId "x" $xmax
    Excel SetChartMinScale $chartId "y" $ymin
    Excel SetChartMaxScale $chartId "y" $ymax
}

proc ::Excel::SetChartSize {worksheetId chartId width height} {

    # Obsolete: Replaced with [SetChartObjSize] in version 1.0.1

    Excel SetChartObjSize $worksheetId $chartId $width $height
}

proc ::Excel::SetChartSourceByIndex {chartId worksheetId row1 col1 row2 col2 {type xlColumns}} {

    # Set the cell range for the source of a chart.
    #
    # chartId     - Identifier of the chart.
    # worksheetId - Identifier of the worksheet.
    # row1        - Row number of upper-left corner of the cell range.
    # col1        - Column number of upper-left corner of the cell range.
    # row2        - Row number of lower-right corner of the cell range.
    # col2        - Column number of lower-right corner of the cell range.
    # type        - Value of enumeration type [Enum::XlRowCol].
    #
    # Returns no value.
    #
    # See also: CreateChart SetChartTitle SetChartScale

    set rangeId [Excel SelectRangeByIndex $worksheetId $row1 $col1 $row2 $col2]
    $chartId SetSourceData $rangeId [Excel GetEnum $type]
    Cawt Destroy $rangeId
}

proc ::Excel::SetChartTicks {chartId axisName {tickMarkSpacing {}} {tickLabelSpacing {}}} {

    # Set the tick spacing of an axis of a chart.
    #
    # chartId          - Identifier of the chart.
    # axisName         - Name of axis. Possible values: `x` or `y`.
    # tickMarkSpacing  - Spacing of tick marks.
    # tickLabelSpacing - Spacing of tick labels.
    #
    # If spacing values are not specified or the emtpy string, the
    # corresponding spacing uses the default values, which are automatically
    # determined by Excel.
    #
    # Returns no value.
    #
    # See also: SetChartMaxScale SetChartScale SetChartObjSize

    if { $axisName eq "x" || $axisName eq "X" } {
        set axis [$chartId -with { Axes } Item $::Excel::xlPrimary]
    } else {
        set axis [$chartId -with { Axes } Item $::Excel::xlSecondary]
    }
    if { $tickMarkSpacing ne "" } {
        $axis TickMarkSpacing [expr {int($tickMarkSpacing)}]
    }
    if { $tickLabelSpacing ne "" } {
        $axis TickLabelSpacing [expr {int($tickLabelSpacing)}]
    }
    Cawt Destroy $axis
}

proc ::Excel::SetChartTitle {chartId title} {

    # Set the title of a chart.
    #
    # chartId - Identifier of the chart.
    # title   - Name of the chart title.
    #
    # Returns no value.
    #
    # See also: SetChartMinScale SetChartScale CreateChart

    if { $title eq "" } {
        $chartId HasTitle [Cawt TclBool false]
    } else {
        $chartId HasTitle [Cawt TclBool true]
        $chartId -with { ChartTitle Characters } Text $title
    }
}

proc ::Excel::SetColumnsWidth {worksheetId startCol endCol {width 0}} {

    # Set the width of a range of columns.
    #
    # worksheetId - Identifier of the worksheet.
    # startCol    - Range start column number. Column numbering starts with 1.
    # endCol      - Range end column number. Column numbering starts with 1.
    # width       - A positive value specifies the column's width in average-size characters
    #               of the widget's font. A value of zero specifies that the column's width
    #               fits automatically the width of all elements in the column.
    #
    # Returns no value.
    #
    # See also: SetColumnWidth ColumnCharToInt

    for { set c $startCol } { $c <= $endCol } { incr c } {
        Excel SetColumnWidth $worksheetId $c $width
    }
}

proc ::Excel::SetColumnValues {worksheetId col valList {startRow 1} {numVals 0}} {

    # Insert column values from a Tcl list.
    #
    # worksheetId - Identifier of the worksheet.
    # col         - Column number. Column numbering starts with 1.
    # valList     - List of values to be inserted.
    # startRow    - Row number of insertion start. Row numbering starts with 1.
    # numVals     - If negative or zero, all list values are inserted.
    #               If positive, $numVals rows are filled with the list values
    #               (starting at list index 0).
    #
    # Returns no value.
    #
    # See also: GetColumnValues SetRowValues SetCellValue ColumnCharToInt

    set len [llength $valList]
    if { $numVals > 0 } {
        if { $numVals < $len } {
            set len $numVals
        }
    }

    for { set i 0 } { $i < $len } { incr i } {
        lappend valListList [list [lindex $valList $i]]
    }
    set cellId [Excel SelectRangeByIndex $worksheetId  $startRow $col [expr {$startRow + $len - 1}] $col]
    Excel SetRangeValues $cellId $valListList
    Cawt Destroy $cellId
}

proc ::Excel::SetColumnWidth {worksheetId col {width 0}} {

    # Set the width of a column.
    #
    # worksheetId - Identifier of the worksheet.
    # col         - Column number. Column numbering starts with 1.
    # width       - A positive value specifies the column's width in average-size characters
    #               of the widget's font. A value of zero specifies that the column's width
    #               fits automatically the width of all elements in the column.
    #
    # Returns no value.
    #
    # See also: SetColumnsWidth ColumnCharToInt

    set cell [Excel SelectCellByIndex $worksheetId 1 $col]
    set curCol [$cell EntireColumn]
    if { $width == 0 } {
        $curCol -with { Columns } AutoFit
    } else {
        $curCol ColumnWidth $width
    }
    Cawt Destroy $curCol
    Cawt Destroy $cell
}

proc ::Excel::SetCommentDisplayMode {appId {showComment false} {showIndicator true}} {

    # Set the global display mode of comments.
    #
    # appId         - Identifier of the Excel instance.
    # showComment   - If set to true, show the comments.
    #                 Otherwise do not show the comments.
    # showIndicator - If set to true, show an indicator for the comments.
    #                 Otherwise do not show an indicator.
    #
    # Returns no value.
    #
    # See also: SetRangeComment SetCommentSize GetCellComment

    if { $showComment && $showIndicator } {
        $appId DisplayCommentIndicator $::Excel::xlCommentAndIndicator
    } elseif { $showIndicator } {
        $appId DisplayCommentIndicator $::Excel::xlCommentIndicatorOnly
    } else {
        $appId DisplayCommentIndicator $::Excel::xlNoIndicator
    }
}

proc ::Excel::SetCommentSize {commentId width height} {

    # Set the shape size of a comment.
    #
    # commentId - Identifier of the comment.
    # width     - Width of the comment.
    # height    - Height of the comment.
    #
    # The size values may be specified in a format acceptable by
    # procedure [::Cawt::ValueToPoints], i.e. centimeters, inches or points.
    #
    # Returns no value.
    #
    # See also: SetRangeComment SetCommentDisplayMode GetCellComment

    $commentId -with { Shape } LockAspectRatio [Cawt TclInt 0]
    $commentId -with { Shape } Height [Cawt ValueToPoints $width]
    $commentId -with { Shape } Width  [Cawt ValueToPoints $height]
}

proc ::Excel::SetCsvSeparatorChar {{separatorChar {;}}} {

    # Set the column separator character.
    #
    # separatorChar - The character used as the column separator.
    #
    # Returns no value.

    variable sSepChar

    set sSepChar $separatorChar
}

proc ::Excel::SetHeaderRow {worksheetId headerList {row 1} {startCol 1}} {

    # Insert row values from a Tcl list and format as a header row.
    #
    # worksheetId - Identifier of the worksheet.
    # headerList  - List of values to be inserted as header.
    # row         - Row number. Row numbering starts with 1.
    # startCol    - Column number of insertion start. Column numbering starts with 1.
    #
    # Returns no value. If $headerList is an empty list, an error is thrown.
    #
    # See also: SetRowValues FormatHeaderRow

    set len [llength $headerList]
    Excel SetRowValues $worksheetId $row $headerList $startCol $len
    Excel FormatHeaderRow $worksheetId $row $startCol [expr {$startCol + $len -1}]
}

proc ::Excel::SetHyperlink {worksheetId row col link {textDisplay {}}} {

    # Insert a hyperlink into a cell.
    #
    # worksheetId - Identifier of the worksheet the hyperlink is inserted to.
    # row         - Row number. Row numbering starts with 1.
    # col         - Column number. Column numbering starts with 1.
    # link        - URL of the hyperlink.
    # textDisplay - Text to be displayed instead of the URL.
    #
    # URL's are specified as strings:
    # * `file://myLinkedFile` specifies a link to a local file.
    # * `http://myLinkedWebpage` specifies a link to a web address.
    #
    # Returns no value.
    #
    # See also: AddWorksheet SetHyperlinkToFile SetHyperlinkToCell SetLinkToCell

    variable excelVersion

    if { $textDisplay eq "" } {
        set textDisplay $link
    }

    set rangeId [Excel SelectCellByIndex $worksheetId $row $col]
    set hyperId [$worksheetId Hyperlinks]

    # Add(Anchor As Object, Address As String, [SubAddress],
    # [ScreenTip], [TextToDisplay]) As Object
    if { $excelVersion eq "8.0" } {
        $hyperId -callnamedargs Add  Anchor $rangeId  Address $link
    } else {
        $hyperId -callnamedargs Add  Anchor $rangeId  Address $link  TextToDisplay $textDisplay
    }
    Cawt Destroy $hyperId
    Cawt Destroy $rangeId
}

proc ::Excel::SetHyperlinkToCell {srcWorksheetId srcRow srcCol destWorksheetId destRow destCol {textDisplay {}}} {

    # Insert a hyperlink to a cell into another cell.
    #
    # srcWorksheetId  - Identifier of the worksheet the link points to.
    # srcRow          - Source row number. Row numbering starts with 1.
    # srcCol          - Source column number. Column numbering starts with 1.
    # destWorksheetId - Identifier of the worksheet the link is inserted into.
    # destRow         - Destination row number. Row numbering starts with 1.
    # destCol         - Destination column number. Column numbering starts with 1.
    # textDisplay     - Text to be displayed instead of the hyperlink.
    #
    # Returns no value.
    #
    # See also: AddWorksheet SetHyperlinkToFile SetHyperlink SetLinkToCell

    set rangeId [Excel SelectCellByIndex $destWorksheetId $destRow $destCol]
    set hyperId [$destWorksheetId Hyperlinks]

    set subAddress [format "'%s'!%s%d"  [Excel GetWorksheetName $srcWorksheetId]  [Excel ColumnIntToChar $srcCol] $srcRow]

    if { $textDisplay eq "" } {
        set textDisplay $subAddress
    }

    # Add(Anchor As Object, Address As String, [SubAddress],
    # [ScreenTip], [TextToDisplay]) As Object
    $hyperId -callnamedargs Add  Anchor $rangeId  Address ""  SubAddress $subAddress  TextToDisplay $textDisplay
    Cawt Destroy $hyperId
    Cawt Destroy $rangeId
}

proc ::Excel::SetHyperlinkToFile {worksheetId row col fileName {textDisplay {}}} {

    # Insert a hyperlink to a file into a cell.
    #
    # worksheetId - Identifier of the worksheet the hyperlink is inserted to.
    # row         - Row number. Row numbering starts with 1.
    # col         - Column number. Column numbering starts with 1.
    # fileName    - Path name of the linked file.
    # textDisplay - Text to be displayed instead of the file name.
    #
    # Returns no value.
    #
    # See also: AddWorksheet SetHyperlinkToCell SetHyperlink SetLinkToCell

    if { $textDisplay eq "" } {
        set textDisplay $fileName
    }

    set rangeId [Excel SelectCellByIndex $worksheetId $row $col]
    set hyperId [$worksheetId Hyperlinks]

    if { [file pathtype $fileName] eq "relative" } {
        set address [format "file:./%s" [file nativename $fileName]]
    } else {
        set address [format "file://%s" [file nativename [file normalize $fileName]]]
        set appId [Office GetApplicationId $worksheetId]
        $appId -with { DefaultWebOptions } UpdateLinksOnSave [Cawt TclBool false]
        Cawt Destroy $appId
    }

    # Add(Anchor As Object, Address As String, [SubAddress],
    # [ScreenTip], [TextToDisplay]) As Object
    $hyperId -callnamedargs Add  Anchor $rangeId  Address $address  TextToDisplay $textDisplay
    Cawt Destroy $hyperId
    Cawt Destroy $rangeId
}

proc ::Excel::SetLinkToCell {srcWorksheetId srcRow srcCol destWorksheetId destRow destCol} {

    # Insert an internal link to a cell into another cell.
    #
    # srcWorksheetId  - Identifier of the worksheet the link points to.
    # srcRow          - Source row number. Row numbering starts with 1.
    # srcCol          - Source column number. Column numbering starts with 1.
    # destWorksheetId - Identifier of the worksheet the link is inserted to.
    # destRow         - Destination row number. Row numbering starts with 1.
    # destCol         - Destination column number. Column numbering starts with 1.
    #
    # Note, that the number format of the source cell is used as number format of the
    # destination cell.
    #
    # Returns no value.
    #
    # See also: SetHyperlinkToCell SetHyperlinkToFile SetHyperlink

    set srcRangeId  [Excel SelectCellByIndex $srcWorksheetId $srcRow $srcCol]
    set destRangeId [Excel SelectCellByIndex $destWorksheetId $destRow $destCol]

    $destRangeId NumberFormat [$srcRangeId NumberFormat]

    $srcRangeId Copy
    $destRangeId Select
    $destWorksheetId -callnamedargs Paste Link [Cawt TclBool true]

    Cawt Destroy $srcRangeId
    Cawt Destroy $destRangeId
}

proc ::Excel::SetListItemSeparator {separator} {

    # Set the list item separator used by Excel.
    #
    # separator - The character used as list item separator.
    #
    # Use this procedure to overwrite the separator used by Windows.
    #
    # Returns no value.
    #
    # See also: GetListItemSeparator CreateRangeString

    variable listItemSeparator

    set listItemSeparator $separator
}

proc ::Excel::SetMatrixValues {worksheetId matrixList {startRow 1} {startCol 1}} {

    # Insert matrix values into a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # matrixList  - Matrix with table data.
    # startRow    - Row number of insertion start. Row numbering starts with 1.
    # startCol    - Column number of insertion start. Column numbering starts with 1.
    #
    # The matrix data must be stored as a list of lists. Each sub-list contains
    # the values for the row values.
    # The main (outer) list contains the rows of the matrix.
    #
    # Example:
    #     { { R1_C1 R1_C2 R1_C3 } { R2_C1 R2_C2 R2_C3 } }
    #
    # Returns no value.
    #
    # See also: GetMatrixValues SetRowValues SetColumnValues

    set numRows [llength $matrixList]
    if { $numRows == 0 } {
        return
    }
    set numCols [llength [lindex $matrixList 0]]
    if { $numCols == 0 } {
        return
    }

    set cellId [Excel SelectRangeByIndex $worksheetId  $startRow $startCol  [expr {$startRow + $numRows -1}] [expr {$startCol + $numCols -1}]]
    Excel SetRangeValues $cellId $matrixList
    Cawt Destroy $cellId
}

proc ::Excel::SetNamedRange {rangeId rangeName {useWorksheet true}} {

    # Set the name of a cell range.
    #
    # rangeId      - Identifier of the cell range.
    # rangeName    - Name of the cell range. Must not contain spaces.
    # useWorksheet - If set to true, set the name at the worksheet level.
    #                Otherwise set it at the workbook level.
    #
    # Returns no value.
    #
    # See also: GetNamedRange GetNamedRangeNames

    set worksheetId [$rangeId Parent]
    set worksheetName [Excel GetWorksheetName $worksheetId]
    Cawt Destroy $worksheetId

    if { $useWorksheet } {
        set rangeName [format "%s!%s" $worksheetName $rangeName]
    }
    $rangeId Name $rangeName
}

proc ::Excel::SetRangeBorder {rangeId side {weight xlThin} {lineStyle xlContinuous} args} {

    # Set the attributes of one border of a cell range.
    #
    # rangeId   - Identifier of the cell range.
    # side      - Value of enumeration type [Enum::XlBordersIndex].
    #             Typical values: `xlEdgeLeft`, `xlEdgeTop`, `xlEdgeBottom`, `xlEdgeRight`.
    # weight    - Value of enumeration type [Enum::XlBorderWeight].
    #             Typical values: `xlThin`, `xlMedium`, `xlThick`.
    # lineStyle - Value of enumeration type [Enum::XlLineStyle].
    #             Typical values: `xlContinuous`, `xlDash`, `xlDot`.
    # args      - Border color.
    #
    # Color value may be specified in a format acceptable by procedure [::Cawt::GetColor],
    # i.e. color name, hexadecimal string, Office color number or a list of 3 integer RGB values.
    #
    # If no border color is specified, it is set to black.
    #
    # Returns no value.
    #
    # See also: SetRangeBorders SelectRangeByIndex SelectRangeByString

    if { [llength $args] == 0 } {
        set borderColor [Cawt GetColor "black"]
    } else {
        set borderColor [Cawt GetColor {*}$args]
    }

    set borders [$rangeId Borders]
    set sideInt [Excel GetEnum $side]
    set border [$borders Item $sideInt]
    $border Weight    [Excel GetEnum $weight]
    $border LineStyle [Excel GetEnum $lineStyle]
    $border Color     $borderColor
    Cawt Destroy $border
    Cawt Destroy $borders
}

proc ::Excel::SetRangeBorders {rangeId {weight xlThin} {lineStyle xlContinuous} {r 0} {g 0} {b 0}} {

    # Set the attributes of all borders of a cell range.
    #
    # rangeId   - Identifier of the cell range.
    # weight    - Value of enumeration type [Enum::XlBorderWeight].
    #             Typical values: `xlThin`, `xlMedium`, `xlThick`.
    # lineStyle - Value of enumeration type [Enum::XlLineStyle].
    #             Typical values: `xlContinuous`, `xlDash`, `xlDot`.
    # r         - Red component of the border color.
    # g         - Green component of the border color.
    # b         - Blue component of the border color.
    #
    # The r, g and b values are specified as integers in the
    # range \[0, 255\].
    #
    # Returns no value.
    #
    # See also: SetRangeBorder SelectRangeByIndex SelectRangeByString

    Excel SetRangeBorder $rangeId xlEdgeLeft   $weight $lineStyle $r $g $b
    Excel SetRangeBorder $rangeId xlEdgeRight  $weight $lineStyle $r $g $b
    Excel SetRangeBorder $rangeId xlEdgeBottom $weight $lineStyle $r $g $b
    Excel SetRangeBorder $rangeId xlEdgeTop    $weight $lineStyle $r $g $b
}

proc ::Excel::SetRangeComment {rangeId comment {imgFileName {}} {addUserName true} {visible false}} {

    # Set the comment text of a cell range.
    #
    # rangeId     - Identifier of the cell range.
    # comment     - Comment text.
    # imgFileName - File name of an image used as comment background.
    # addUserName - Automatically add user name before comment text.
    # visible     - If set to true, show the comment window.
    #               Otherwise hide the comment window.
    #
    # Note, that an already existing comment is overwritten.
    #
    # A comment may be used as a mouse-over tooltip, if parameter showComments of
    # [SetCommentDisplayMode] is set to false. For a selection tooltip, use [SetRangeTooltip].
    #
    # Returns the comment identifier.
    #
    # See also: SetCommentDisplayMode SetCommentSize GetCellComment
    # SelectRangeByIndex SelectRangeByString SetRangeTooltip ::Office::GetUserName

    set commentId [$rangeId Comment]
    if { ! [Cawt IsComObject $commentId] } {
        set commentId [$rangeId AddComment]
    }
    $commentId Visible [Cawt TclBool $visible]
    if { $addUserName } {
        set userName [Office GetUserName [$commentId Application]]
        set msg [format "%s:\n%s" $userName $comment]
    } else {
        set msg $comment
    }
    $commentId Text $msg
    if { $imgFileName ne "" } {
        set fileName [file nativename [file normalize $imgFileName]]
        $commentId -with { Shape Fill } UserPicture $fileName
    }
    return $commentId
}

proc ::Excel::SetRangeFillColor {rangeId args} {

    # Set the fill color of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # args    - Background fill color.
    #
    # Color value may be specified in a format acceptable by procedure [::Cawt::GetColor],
    # i.e. color name, hexadecimal string, Office color number or a list of 3 integer RGB values.
    #
    # Returns no value.
    #
    # See also: SetRangeTextColor SelectRangeByIndex SelectRangeByString

    set color [Cawt GetColor {*}$args]
    $rangeId -with { Interior } Color $color
    $rangeId -with { Interior } Pattern $::Excel::xlSolid
}

proc ::Excel::SetRangeFontAttributes {rangeId args} {

    # Set the font attibutes of a cell or character range.
    #
    # rangeId - Identifier of the cell range.
    # args    - Options described below.
    #
    # -bold <bool>          - Switch attribute on or off.
    # -fontstyle <string>   - Font style as string.
    # -italic <bool>        - Switch attribute on or off.
    # -name <string>        - Font name as string.
    # -outlinefont <bool>   - Switch attribute on or off.
    # -size <size>          - Font size in points.
    # -shadow <bool>        - Switch attribute on or off.
    # -strikethrough <bool> - Switch attribute on or off.
    # -subscript <bool>     - Switch attribute on or off.
    # -superscript <bool>   - Switch attribute on or off.
    # -underline <enum>     - Enumeration of type [Enum::XlUnderlineStyle]
    # -themecolor <enum>    - Enumeration of type [Enum::XlThemeColor].
    # -themefont <enum>     - Enumeration of type [Enum::XlThemeFont].
    # -tintandshade <float> - Floating point number from -1 (darkest) to 1 (lightest). Zero is neutral.
    #
    # The size value may be specified in a format acceptable by
    # procedure [::Cawt::ValueToPoints], i.e. centimeters, inches or points.
    #
    # Example:
    #     SetRangeFontAttributes $rangeId -size 2c -bold true
    #     sets the font size to 2 centimeters and the enables the Bold attribute.
    #
    # Returns no value.
    #
    # See also: GetRangeFontAttributes SelectRangeByIndex
    # SetRangeFontBold SetRangeFontItalic SetRangeFontName SetRangeFontSize
    # SetRangeFontSubscript SetRangeFontSuperscript SetRangeFontUnderline

    set fontId [$rangeId Font]
    foreach { key value } $args {
        if { $value eq "" } {
            error "SetRangeFontAttributes: No value specified for key \"$key\""
        }
        switch -exact -nocase -- $key {
            "-bold"          { $fontId Bold [Cawt TclBool $value] }
            "-fontstyle"     { $fontId FontStyle $value }
            "-italic"        { $fontId Italic [Cawt TclBool $value] }
            "-name"          { $fontId Name $value }
            "-outlinefont"   { $fontId OutlineFont [Cawt TclBool $value] }
            "-size"          { $fontId Size [Cawt ValueToPoints $value] }
            "-shadow"        { $fontId Shadow [Cawt TclBool $value] }
            "-strikethrough" { $fontId Strikethrough [Cawt TclBool $value] }
            "-subscript"     { $fontId Subscript [Cawt TclBool $value] }
            "-superscript"   { $fontId Superscript [Cawt TclBool $value] }
            "-underline"     { $fontId Underline [Excel GetEnum $value] }
            "-themecolor"    { $fontId ThemeColor [Excel GetEnum $value] }
            "-themefont"     { $fontId ThemeFont [Excel GetEnum $value] }
            "-tintandshade"  { $fontId TintAndShade [expr double( $value )] }
            default          { error "SetRangeFontAttributes: Unknown key \"$key\" specified" }
        }
    }
    Cawt Destroy $fontId
}

proc ::Excel::SetRangeFontBold {rangeId {onOff true}} {

    # Set the bold font style of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # onOff   - If set to true, set bold style on.
    #           Otherwise set bold style off.
    #
    # Returns no value.
    #
    # See also: GetRangeFontBold SelectRangeByIndex SetRangeFontAttributes

    $rangeId -with { Font } Bold [Cawt TclBool $onOff]
}

proc ::Excel::SetRangeFontItalic {rangeId {onOff true}} {

    # Set the italic font style of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # onOff   - If set to true, set italic style on.
    #           Otherwise set italic style off.
    #
    # Returns no value.
    #
    # See also: GetRangeFontItalic SelectRangeByIndex SetRangeFontAttributes

    $rangeId -with { Font } Italic [Cawt TclBool $onOff]
}

proc ::Excel::SetRangeFontName {rangeId fontName} {

    # Set the font name of a cell or character range.
    #
    # rangeId  - Identifier of the cell range.
    # fontName - Name of the font as a string.
    #
    # Returns no value.
    #
    # See also: GetRangeFontName SelectRangeByIndex SetRangeFontAttributes

    $rangeId -with { Font } Name $fontName
}