::ExcelMain

The Excel namespace provides commands to control Microsoft Excel.

CommandsExcel, Main

AddColumnChartSimple [::Excel]Excel, Main

Add a clustered column chart to a worksheet. Simple case.

AddColumnChartSimple worksheetId numRows numCols ?title?
worksheetIdIdentifier of the worksheet.
numRowsNumber of rows beeing used for the chart.
numColsNumber of columns beeing used for the chart.
titleString used as title of the chart. Optional, default "".

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

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
}

AddLineChart [::Excel]Excel, Main

Add a line chart to a worksheet. Generic case.

AddLineChart worksheetId headerRow xaxisCol startRow numRows startCol numCols ?title? ?yaxisName? ?markerSize?
worksheetIdIdentifier of the worksheet.
headerRowRow containing names for the lines.
xaxisColData for the x-axis is taken from this column.
startRowStarting row for data of x-axis.
numRowsNumber of rows used as data of x-axis.
startColColumn in header from which names start.
numColsNumber of columns to use for the chart.
titleString used as title of the chart. Optional, default "".
yaxisNameName of y-axis. Optional, default Values.
markerSizeSize of marker. Optional, default 5.

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

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
}

AddLineChartSimple [::Excel]Excel, Main

Add a line chart to a worksheet. Simple case.

AddLineChartSimple worksheetId numRows numCols ?title? ?yaxisName? ?markerSize?
worksheetIdIdentifier of the worksheet.
numRowsNumber of rows used as data of x-axis.
numColsNumber of columns used as data of y-axis.
titleString used as title of the chart. Optional, default "".
yaxisNameName of y-axis. Optional, default Values.
markerSizeSize of marker. Optional, default 5.

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

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]
}

AddPointChartSimple [::Excel]Excel, Main

Add a point chart to a worksheet. Simple case.

AddPointChartSimple worksheetId numRows col1 col2 ?title? ?markerSize?
worksheetIdIdentifier of the worksheet.
numRowsNumber of rows beeing used for the chart.
col1Start column of the chart data.
col2End column of the chart data.
titleString used as title of the chart. Optional, default "".
markerSizeSize of the point marker. Optional, default 5.

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

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
}

AddRadarChartSimple [::Excel]Excel, Main

Add a radar chart to a worksheet. Simple case.

AddRadarChartSimple worksheetId numRows numCols ?title?
worksheetIdIdentifier of the worksheet.
numRowsNumber of rows beeing used for the chart.
numColsNumber of columns beeing used for the chart.
titleString used as title of the chart. Optional, default "".

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

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
}

AddSeriesTrendLine [::Excel]Excel, Main

Add a trend line to a series.

AddSeriesTrendLine seriesId ?args?
seriesIdIdentifier of the series.
argsOptions 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).
-linecolor <color>Set the line color.
-linewidth <size>Set the line width.
-order <int>Set the order ( > 1) of a polynomal trend line. Only valid, if type is xlPolynomal.
-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.
  • 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

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 $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
}

AddWorkbook [::Excel]Excel, Main

Add a new workbook with one worksheet.

AddWorkbook appId ?type?
appIdIdentifier of the Excel instance.
typeValue of enumeration type Enum::XlWBATemplate. Possible values: xlWBATChart, xlWBATExcel4IntlMacroSheet, xlWBATExcel4MacroSheet, xlWBATWorksheet. Optional, default xlWBATWorksheet.

Returns the identifier of the new workbook.

See also: OpenWorkbook, Close, SaveAs

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]]
}

AddWorksheet [::Excel]Excel, Main

Add a new worksheet to the end of a workbook.

AddWorksheet workbookId name ?visibleType?
workbookIdIdentifier of the workbook containing the new worksheet.
nameName of the new worksheet.
visibleTypeValue of enumeration type Enum::XlSheetVisibility. Possible values: xlSheetVisible, xlSheetHidden, xlSheetVeryHidden. Optional, default xlSheetVisible.

Returns the identifier of the new worksheet.

See also: GetNumWorksheets, DeleteWorksheet

proc ::Excel::AddWorksheet {workbookId name {visibleType xlSheetVisible}} {

    # 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.
    # visibleType - Value of enumeration type [Enum::XlSheetVisibility].
    #               Possible values: `xlSheetVisible`, `xlSheetHidden`, `xlSheetVeryHidden`.
    #
    # Returns the identifier of the new worksheet.
    #
    # See also: GetNumWorksheets DeleteWorksheet

    set worksheets [$workbookId Worksheets]
    set lastWorksheetId [$worksheets Item [$worksheets Count]]
    set worksheetId [$worksheets -callnamedargs Add After $lastWorksheetId]
    $worksheetId Name $name
    $worksheetId Visible [Excel GetEnum $visibleType]
    Cawt Destroy $lastWorksheetId
    Cawt Destroy $worksheets
    return $worksheetId
}

ArrangeWindows [::Excel]Excel, Main

Arrange the windows of an Excel application.

ArrangeWindows appId ?arrangeStyle?
appIdIdentifier of the Excel instance.
arrangeStyleValue of enumeration type Enum::XlArrangeStyle. Typical values are: xlArrangeStyleHorizontal, xlArrangeStyleTiled, xlArrangeStyleVertical. Optional, default xlArrangeStyleVertical.

Returns no value.

See also: Open, Visible, SetWindowState

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]
}

ChartObjToClipboard [::Excel]Excel, Main

Copy a chart object to the clipboard.

ChartObjToClipboard chartObjId
chartObjIdIdentifier 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

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
    }
}

ChartToClipboard [::Excel]Excel, Main

Obsolete: Replaced with ChartObjToClipboard in version 1.0.1

ChartToClipboard chartId
chartIdNot documented.
proc ::Excel::ChartToClipboard {chartId} {

    # Obsolete: Replaced with [ChartObjToClipboard] in version 1.0.1

    Excel ChartObjToClipboard $chartId
}

ClipboardToMatrix [::Excel]Excel, Main

Return the matrix values contained in the clipboard.

ClipboardToMatrix ?sepChar?
sepCharThe separation character of the clipboard matrix data. Optional, default ;.

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

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
}

ClipboardToWorksheet [::Excel]Excel, Main

Insert the matrix values contained in the clipboard into a worksheet.

ClipboardToWorksheet worksheetId ?startRow? ?startCol? ?sepChar?
worksheetIdIdentifier of the worksheet.
startRowRow number. Row numbering starts with 1. Optional, default 1.
startColColumn number. Column numbering starts with 1. Optional, default 1.
sepCharThe separation character of the clipboard matrix data. Optional, default ;.

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

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
}

Close [::Excel]Excel, Main

Close a workbook without saving changes.

Close workbookId
workbookIdIdentifier of the workbook.

Use the SaveAs method before closing, if you want to save changes.

Returns no value.

See also: SaveAs, OpenWorkbook

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]
}

ColumnCharToInt [::Excel]Excel, Main

Return an Excel column string as a column number.

ColumnCharToInt colChar
colCharColumn string.

Example:

[Excel ColumnCharToInt A] returns 1.
[Excel ColumnCharToInt Z] returns 26.

Returns the corresponding column number.

See also: GetColumnNumber, ColumnIntToChar

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
}

ColumnIntToChar [::Excel]Excel, Main

Return a column number as an Excel column string.

ColumnIntToChar col
colColumn number.

Example:

[Excel ColumnIntToChar 1]  returns "A".
[Excel ColumnIntToChar 26] returns "Z".

Returns the corresponding column string.

See also: ColumnCharToInt

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
}

CopyColumn [::Excel]Excel, Main

Copy the contents of a column into another column.

CopyColumn fromWorksheetId fromCol toWorksheetId toCol ?fromRow? ?toRow? ?pasteType?
fromWorksheetIdIdentifier of the source worksheet.
fromColSource column number. Column numbering starts with 1.
toWorksheetIdIdentifier of the destination worksheet.
toColDestination column number. Column numbering starts with 1.
fromRowStart row of source column. Optional, default 1.
toRowStart row of destination column. Optional, default 1.
pasteTypeValue of enumeration type Enum::XlPasteType. Typical values are: xlPasteAll, xlPasteAllExceptBorders, xlPasteValues. Optional, default xlPasteAll.

Note, that the contents of the destination column are overwritten.

Returns no value.

See also: CopyRange, CopyWorksheet

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
}

CopyRange [::Excel]Excel, Main

Copy the contents of a cell range into another cell range.

CopyRange fromRangeId toRangeId ?pasteType?
fromRangeIdIdentifier of the source range.
toRangeIdIdentifier of the destination range.
pasteTypeValue of enumeration type Enum::XlPasteType. Typical values are: xlPasteAll, xlPasteAllExceptBorders, xlPasteValues. Optional, default xlPasteAll.

Note, that the contents of the destination range are overwritten.

Returns no value.

See also: SelectAll, CopyWorksheet, CopyColumn

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]
}

CopyWorksheet [::Excel]Excel, Main

Copy the contents of a worksheet into another worksheet.

CopyWorksheet fromWorksheetId toWorksheetId
fromWorksheetIdIdentifier of the source worksheet.
toWorksheetIdIdentifier of the destination worksheet.

Note, that the contents of worksheet $toWorksheetId are overwritten.

Returns no value.

See also: SelectAll, CopyWorksheetBefore, CopyWorksheetAfter, AddWorksheet

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
}

CopyWorksheetAfter [::Excel]Excel, Main

Copy the contents of a worksheet after another worksheet.

CopyWorksheetAfter fromWorksheetId afterWorksheetId ?worksheetName?
fromWorksheetIdIdentifier of the source worksheet.
afterWorksheetIdIdentifier of the destination worksheet.
worksheetNameName of the new worksheet. If no name is specified, or an empty string, the naming is done by Excel. Optional, default "".

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

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
}

CopyWorksheetBefore [::Excel]Excel, Main

Copy the contents of a worksheet before another worksheet.

CopyWorksheetBefore fromWorksheetId beforeWorksheetId ?worksheetName?
fromWorksheetIdIdentifier of the source worksheet.
beforeWorksheetIdIdentifier of the destination worksheet.
worksheetNameName of the new worksheet. If no name is specified, or an empty string, the naming is done by Excel. Optional, default "".

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

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
}

CreateChart [::Excel]Excel, Main

Create a new empty chart in a worksheet.

CreateChart worksheetId chartType
worksheetIdIdentifier of the worksheet.
chartTypeValue of enumeration type Enum::XlChartType.

Returns the identifier of the new chart.

See also: PlaceChart, AddLineChart, AddLineChartSimple, AddPointChartSimple, AddRadarChartSimple

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
}

CreateRangeString [::Excel]Excel, Main

Create a range string in A1 notation.

CreateRangeString ?args?
argsList 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.

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

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.
    #
    # 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

    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 ";"
        }
        incr ind
    }
    return $extendedRangeStr
}

CsvRowToList [::Excel]Excel, Main

Return a CSV encoded row as a list of column values.

CsvRowToList rowStr
rowStrCSV encoded row as string.

Returns the CSV encoded row as a list of column values.

See also: ListToCsvRow

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
}

CsvStringToMatrix [::Excel]Excel, Main

Return a matrix from a CSV encoded table string.

CsvStringToMatrix csvString
csvStringCSV encoded table as string.

Returns the matrix from the CSV encoded table string.

See also: MatrixToCsvString, CsvRowToList

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
}

DeleteColumn [::Excel]Excel, Main

Delete a column.

DeleteColumn worksheetId col
worksheetIdIdentifier of the worksheet.
colColumn number. Column numbering starts with 1.

The specified column is deleted.

Returns no value.

See also: InsertColumn, DuplicateColumn, HideColumn, DeleteRow, DeleteWorksheet

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
}

DeleteRow [::Excel]Excel, Main

Delete a row.

DeleteRow worksheetId row
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.

The specified row is deleted.

Returns no value.

See also: InsertRow, DuplicateRow, HideRow, DeleteColumn, DeleteWorksheet

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
}

DeleteWorksheet [::Excel]Excel, Main

Delete a worksheet.

DeleteWorksheet workbookId worksheetId
workbookIdIdentifier of the workbook containing the worksheet.
worksheetIdIdentifier 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

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
}

DeleteWorksheetByIndex [::Excel]Excel, Main

Delete a worksheet identified by its index.

DeleteWorksheetByIndex workbookId index
workbookIdIdentifier of the workbook containing the worksheet.
indexIndex of the worksheet to delete.

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.

Returns no value.

See also: GetNumWorksheets, GetWorksheetIdByIndex, AddWorksheet

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
}

DiffExcelFiles [::Excel]Excel, Main

Compare two Excel files visually.

DiffExcelFiles excelBaseFile excelNewFile ?args?
excelBaseFileName of the base Excel file.
excelNewFileName of the new Excel file.
argsMark 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

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 "Diff: Base file $excelBaseFile does not exists"
    }
    if { ! [file exists $excelNewFile] } {
        error "Diff: New file $excelNewFile does not exists"
    }
    if { [file normalize $excelBaseFile] eq [file normalize $excelNewFile] } {
        error "Diff: 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 [poMisc GetTmpDir] $tmpName]
        file copy -force $excelBaseFile $tmpName
        set excelBaseFile $tmpName
    }
    set appId [Excel OpenNew true]
    set baseWorkbookId [Excel OpenWorkbook $appId [file nativename $excelBaseFile] true]
    set newWorkbookId  [Excel OpenWorkbook $appId [file nativename $excelNewFile]  true]
    if { [Excel IsWorkbookProtected $baseWorkbookId] } {
        puts "Unable to arrange windows, because $excelBaseFile is protected."
    }
    if { [Excel IsWorkbookProtected $newWorkbookId] } {
        puts "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] } {
            puts "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
}

DuplicateColumn [::Excel]Excel, Main

Duplicate a column.

DuplicateColumn worksheetId col
worksheetIdIdentifier of the worksheet.
colColumn number. Column numbering starts with 1.

The specified column is duplicated with formatting and formulas.

Returns no value.

See also: InsertColumn, DeleteColumn, HideColumn, DuplicateRow

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
}

DuplicateRow [::Excel]Excel, Main

Duplicate a row.

DuplicateRow worksheetId row
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.

The specified row is duplicated with formatting and formulas.

Returns no value.

See also: InsertRow, DeleteRow, HideRow, DuplicateColumn

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
}

ExcelFileToHtmlFile [::Excel]Excel, Main

Convert an Excel file to a HTML table file.

ExcelFileToHtmlFile excelFileName htmlFileName ?args?
excelFileNameName of the Excel input file.
htmlFileNameName of the HTML output file.
argsOptions described below.
-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.
-worksheet <int>Set the worksheet name or index to convert. Default value: 0

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

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 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
    }
}

ExcelFileToMatlabFile [::Excel]Excel, Main

Convert an Excel file to a Matlab table file.

ExcelFileToMatlabFile excelFileName matFileName ?worksheetNameOrIndex? ?useHeader? ?quitExcel?
excelFileNameName of the Excel input file.
matFileNameName of the Matlab output file.
worksheetNameOrIndexWorksheet name or index to convert. Optional, default 0.
useHeaderIf 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. Optional, default true.
quitExcelIf set to true, quit the Excel instance after generation of output file. Otherwise leave the Excel instance open after generation of output file. Optional, default true.

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

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 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
    }
}

ExcelFileToMediaWikiFile [::Excel]Excel, Main

Convert an Excel file to a MediaWiki table file.

ExcelFileToMediaWikiFile excelFileName wikiFileName ?worksheetNameOrIndex? ?useHeader? ?quitExcel?
excelFileNameName of the Excel input file.
wikiFileNameName of the MediaWiki output file.
worksheetNameOrIndexWorksheet name or index to convert. Optional, default 0.
useHeaderIf 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. Optional, default true.
quitExcelIf set to true, quit the Excel instance after generation of output file. Otherwise leave the Excel instance open after generation of output file. Optional, default true.

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

proc ::Excel::ExcelFileToMediaWikiFile {excelFileName wikiFileName {worksheetNameOrIndex 0} {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 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
    }
}

ExcelFileToRawImageFile [::Excel]Excel, Main

Convert an Excel file to a raw photo image file.

ExcelFileToRawImageFile excelFileName rawFileName ?worksheetNameOrIndex? ?useHeader? ?quitExcel? ?pixelType?
excelFileNameName of the Excel input file.
rawFileNameName of the image output file.
worksheetNameOrIndexWorksheet name or index to convert. Optional, default 0.
useHeaderIf 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. Optional, default true.
quitExcelIf set to true, quit the Excel instance after generation of output file. Otherwise leave the Excel instance open after generation of output file. Optional, default true.
pixelTypePixel type: byte, short, float. Optional, default 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

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 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
    }
}

ExcelFileToWikitFile [::Excel]Excel, Main

Convert an Excel file to a Wikit table file.

ExcelFileToWikitFile excelFileName wikiFileName ?worksheetNameOrIndex? ?useHeader? ?quitExcel?
excelFileNameName of the Excel input file.
wikiFileNameName of the Wikit output file.
worksheetNameOrIndexWorksheet name or index to convert. Optional, default 0.
useHeaderIf 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. Optional, default true.
quitExcelIf set to true, quit the Excel instance after generation of output file. Otherwise leave the Excel instance open after generation of output file. Optional, default true.

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

proc ::Excel::ExcelFileToWikitFile {excelFileName wikiFileName {worksheetNameOrIndex 0} {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 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
    }
}

FormatHeaderRow [::Excel]Excel, Main

Format a row as a header row.

FormatHeaderRow worksheetId row startCol endCol
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
startColColumn number of formatting start. Column numbering starts with 1.
endColColumn 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

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
}

FreezePanes [::Excel]Excel, Main

Freeze a range in a worksheet identified by its row/column index.

FreezePanes worksheetId row col ?onOff?
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
colColumn number. Column numbering starts with 1.
onOffIf set to true, freeze the range. Otherwise unfreeze the range. Optional, default true.

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

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
}

GetActiveWorkbook [::Excel]Excel, Main

Return the active workbook of an application.

GetActiveWorkbook appId
appIdIdentifier of the Excel instance.

Returns the identifier of the active workbook.

See also: OpenWorkbook

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]
}

GetCellComment [::Excel]Excel, Main

Return the comment text of a cell.

GetCellComment worksheetId row col
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
colColumn 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

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
}

GetCellIdByIndex [::Excel]Excel, Main

Return a cell of a worksheet.

GetCellIdByIndex worksheetId row col
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
colColumn number. Column numbering starts with 1.

Returns the cell identifier of the cell with index (row, col).

See also: SelectCellByIndex, AddWorksheet

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
}

GetCellRange [::Excel]Excel, Main

Return a numeric cell range as an Excel range string in A1 notation.

GetCellRange row1 col1 row2 col2
row1Row number of upper-left corner of the cell range.
col1Column number of upper-left corner of the cell range.
row2Row number of lower-right corner of the cell range.
col2Column 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

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
}

GetCellsId [::Excel]Excel, Main

Return the cells identifier of a worksheet.

GetCellsId worksheetId
worksheetIdIdentifier of the worksheet.

Returns the range of all cells from the worksheet. This corresponds to the method Cells() of the Worksheet object.

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
}

GetCellValue [::Excel]Excel, Main

Return the value of a cell.

GetCellValue worksheetId row col ?fmt?
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
colColumn number. Column numbering starts with 1.
fmtFormat of the cell. Possible values: text, int, real. Optional, default text.

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: SetCellValue, ColumnCharToInt

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: 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"
    }
}

GetChartNumSeries [::Excel]Excel, Main

Return the number of series of a chart.

GetChartNumSeries chartId
chartIdIdentifier of the chart.

Returns the number of series of the chart.

See also: GetChartSeries, CreateChart

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]
}

GetChartSeries [::Excel]Excel, Main

Get a specific series of a chart.

GetChartSeries chartId index
chartIdIdentifier of the chart.
indexIndex of the series. Index numbering starts with 1.

Returns the series identifier.

See also: GetChartNumSeries, CreateChart, SetSeriesAttributes

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)}]]
}

GetColumnNumber [::Excel]Excel, Main

Return an Excel column string or number as a column number.

GetColumnNumber colStrOrInt
colStrOrIntColumn string.

Returns the corresponding column number.

See also: ColumnCharToInt

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]
    }
}

GetColumnRange [::Excel]Excel, Main

Return a numeric column range as an Excel range string.

GetColumnRange col1 col2
col1Column number of the left-most column.
col2Column 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

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
}

GetColumnValues [::Excel]Excel, Main

Return column values as a Tcl list.

GetColumnValues worksheetId col ?startRow? ?numVals?
worksheetIdIdentifier of the worksheet.
colColumn number. Column numbering starts with 1.
startRowRow number of start. Row numbering starts with 1. If negative or zero, start at first available row. Optional, default 0.
numValsIf negative or zero, all available column values are returned. If positive, only numVals values of the column are returned. Optional, default 0.

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

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]
}

GetCsvSeparatorChar [::Excel]Excel, Main

Returns the column separator character.

GetCsvSeparatorChar

Returns the column separator character.

proc ::Excel::GetCsvSeparatorChar {} {

    # Returns the column separator character.

    variable sSepChar

    return $sSepChar
}

GetCurrencyFormat [::Excel]Excel, Main

Return an Excel number format string for currencies.

GetCurrencyFormat appId currency ?pre? ?post? ?floatSep?
appIdIdentifier of the Excel instance.
currencyString identifying the currency symbol.
preNumber of digits before the decimal point. Optional, default 0.
postNumber of digits after the decimal point. Optional, default 00.
floatSepSpecify the floating point separator character. Optional, default "".

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

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
}

GetDecimalSeparator [::Excel]Excel, Main

Return the decimal separator used by Excel.

GetDecimalSeparator appId
appIdIdentifier of the Excel instance.

Returns the decimal separator used by Excel.

See also: GetVersion, GetThousandsSeparator

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

    return [$appId DecimalSeparator]
}

GetEnum [::Excel]Excel, Main

Get numeric value of an enumeration.

GetEnum enumOrString
enumOrStringEnumeration name

Returns the numeric value of an enumeration.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnumNames

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]
    }
}

GetEnumName [::Excel]Excel, Main

Get name of a given enumeration type and numeric value.

GetEnumName enumType enumVal
enumTypeEnumeration type
enumValEnumeration numeric value.

Returns the list of names of a given enumeration type.

See also: GetEnumNames, GetEnumTypes, GetEnumVal, GetEnum

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
}

GetEnumNames [::Excel]Excel, Main

Get names of a given enumeration type.

GetEnumNames enumType
enumTypeEnumeration type

Returns the list of names of a given enumeration type.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnum

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]
    }
}

GetEnumTypes [::Excel]Excel, Main

Get available enumeration types.

GetEnumTypes

Returns the list of available enumeration types.

See also: GetEnumName, GetEnumNames, GetEnumVal, GetEnum

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]]
}

GetEnumVal [::Excel]Excel, Main

Get numeric value of an enumeration name.

GetEnumVal enumName
enumNameEnumeration name

Returns the numeric value of an enumeration name.

See also: GetEnumName, GetEnumTypes, GetEnumNames, GetEnum

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 ""
}

GetExtString [::Excel]Excel, Main

Return the default extension of an Excel file.

GetExtString appId
appIdIdentifier 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

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"
    }
}

GetFirstUsedColumn [::Excel]Excel, Main

Return the index of the first used column of a worksheet.

GetFirstUsedColumn worksheetId
worksheetIdIdentifier of the worksheet.

Returns the index of the first used column of a worksheet.

See also: GetNumColumns, GetNumUsedColumns, GetLastUsedColumn, GetNumUsedRows

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]
}

GetFirstUsedRow [::Excel]Excel, Main

Return the index of the first used row of a worksheet.

GetFirstUsedRow worksheetId
worksheetIdIdentifier of the worksheet.

Returns the index of the first used row of a worksheet.

See also: GetNumRows, GetNumUsedRows, GetLastUsedRow, GetNumUsedColumns

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]
}

GetFloatSeparator [::Excel]Excel, Main

Obsolete: Replaced with GetDecimalSeparator in version 2.1.0

GetFloatSeparator

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

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
}

GetHiddenColumns [::Excel]Excel, Main

Return the hidden columns of a worksheet.

GetHiddenColumns worksheetId
worksheetIdIdentifier 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

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
}

GetHiddenRows [::Excel]Excel, Main

Return the hidden rows of a worksheet.

GetHiddenRows worksheetId
worksheetIdIdentifier 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

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
}

GetLangNumberFormat [::Excel]Excel, Main

Obsolete: Replaced with GetNumberFormat in version 2.1.0

GetLangNumberFormat pre post ?floatSep?
preNumber of digits before the decimal point.
postNumber of digits after the decimal point.
floatSepSpecify the floating point separator character. Optional, default "".

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

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]
}

GetLastUsedColumn [::Excel]Excel, Main

Return the index of the last used column of a worksheet.

GetLastUsedColumn worksheetId
worksheetIdIdentifier of the worksheet.

Returns the index of the last used column of a worksheet.

See also: GetNumColumns, GetNumUsedColumns, GetFirstUsedColumn, GetNumUsedRows

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 }]
}

GetLastUsedRow [::Excel]Excel, Main

Return the index of the last used row of a worksheet.

GetLastUsedRow worksheetId
worksheetIdIdentifier of the worksheet.

Returns the index of the last used row of a worksheet.

See also: GetNumRows, GetNumUsedRows, GetFirstUsedRow, GetNumUsedColumns

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 }]
}

GetMatrixValues [::Excel]Excel, Main

Return worksheet table values as a matrix.

GetMatrixValues worksheetId row1 col1 row2 col2
worksheetIdIdentifier of the worksheet.
row1Row number of upper-left corner of the cell range.
col1Column number of upper-left corner of the cell range.
row2Row number of lower-right corner of the cell range.
col2Column number of lower-right corner of the cell range.

Returns the worksheet table values as a matrix.

See also: SetMatrixValues, GetRowValues, GetColumnValues

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
}

GetMaxColumns [::Excel]Excel, Main

Return the maximum number of columns of an Excel table.

GetMaxColumns appId
appIdIdentifier of the Excel instance.

Returns the maximum number of columns of an Excel table.

See also: GetNumColumns

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
    }
}

GetMaxRows [::Excel]Excel, Main

Return the maximum number of rows of an Excel table.

GetMaxRows appId
appIdIdentifier of the Excel instance.

Returns the maximum number of rows of an Excel table.

See also: GetNumRows

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
    }
}

GetNamedRange [::Excel]Excel, Main

Get the identifier of a named range.

GetNamedRange objId rangeName
objIdIdentifier of a workbook or worksheet.
rangeNameName of range to get.

Returns the range identifier of the named range.

See also: SelectRangeByIndex, GetNamedRangeNames, SetNamedRange

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."
}

GetNamedRangeNames [::Excel]Excel, Main

Get the names of named ranges.

GetNamedRangeNames objId
objIdIdentifier of a workbook or worksheet.

Returns a sorted list of all names.

See also: GetNamedRange, SetNamedRange

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]
}

GetNumberFormat [::Excel]Excel, Main

Return an Excel number format string.

GetNumberFormat appId pre post ?floatSep?
appIdIdentifier of the Excel instance.
preNumber of digits before the decimal point.
postNumber of digits after the decimal point.
floatSepSpecify the floating point separator character. Optional, default "".

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

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]
}

GetNumColumns [::Excel]Excel, Main

Return the number of columns of a cell range.

GetNumColumns rangeId
rangeIdIdentifier 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

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]
}

GetNumRows [::Excel]Excel, Main

Return the number of rows of a cell range.

GetNumRows rangeId
rangeIdIdentifier 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

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]
}

GetNumUsedColumns [::Excel]Excel, Main

Return the number of used columns of a worksheet.

GetNumUsedColumns worksheetId
worksheetIdIdentifier 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

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]
}

GetNumUsedRows [::Excel]Excel, Main

Return the number of used rows of a worksheet.

GetNumUsedRows worksheetId
worksheetIdIdentifier 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

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]
}

GetNumWorksheets [::Excel]Excel, Main

Return the number of worksheets in a workbook.

GetNumWorksheets workbookId
workbookIdIdentifier of the workbook.

Returns the number of worksheets in the workbook.

See also: AddWorksheet, OpenWorkbook

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]
}

GetRangeAsIndex [::Excel]Excel, Main

Get address of a cell range as list of row/column indices.

GetRangeAsIndex rangeId
rangeIdIdentifier of the cell range.

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.

Returns address of a cell range as a 2 or 4 element list of integers:

See also: SelectRangeByIndex, GetCellRange

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 {(\w+)(\d+):(\w+)(\d+)} $rangeStr -> colStr1 row1 colStr2 row2
        set col1 [Excel ColumnCharToInt $colStr1]
        set col2 [Excel ColumnCharToInt $colStr2]
        return [list $row1 $col1 $row2 $col2]
    } else {
        regexp {(\w+)(\d+)} $rangeStr -> colStr row
        set col [Excel ColumnCharToInt $colStr]
        return [list $row $col]
    }
}

GetRangeAsString [::Excel]Excel, Main

Get address of a cell range as Excel range string in A1 notation.

GetRangeAsString rangeId
rangeIdIdentifier of the cell range.

Returns address of a cell range as Excel range string in A1 notation.

See also: SelectRangeByString, GetCellRange

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
}

GetRangeCharacters [::Excel]Excel, Main

Return characters of a cell range.

GetRangeCharacters rangeId ?start? ?length?
rangeIdIdentifier of the cell range.
startStart of the character range. Optional, default 1.
lengthThe number of characters after start. Optional, default -1.

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

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]
    }
}

GetRangeFillColor [::Excel]Excel, Main

Get the fill color of a cell range.

GetRangeFillColor rangeId
rangeIdIdentifier 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

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]
}

GetRangeFontBold [::Excel]Excel, Main

Get the bold font style of a cell range.

GetRangeFontBold rangeId
rangeIdIdentifier of the cell range.

Returns true, if the font in specified cell range has the bold flag set.

See also: SetRangeFontBold, SelectRangeByIndex

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

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

GetRangeFontItalic [::Excel]Excel, Main

Get the italic font style of a cell range.

GetRangeFontItalic rangeId
rangeIdIdentifier of the cell range.

Returns true, if the font in specified cell range has the italic flag set.

See also: SetRangeFontItalic, SelectRangeByIndex

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

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

GetRangeFontName [::Excel]Excel, Main

Get the font name of a cell or character range.

GetRangeFontName rangeId
rangeIdIdentifier of the cell range.

Returns the font name in specified cell range as a string.

See also: SetRangeFontName, SelectRangeByIndex

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

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

GetRangeFontSize [::Excel]Excel, Main

Get the font size of a cell range.

GetRangeFontSize rangeId
rangeIdIdentifier of the cell range.

Returns the size of the font in specified cell range measured in points.

See also: SetRangeFontSize, SelectRangeByIndex

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

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

GetRangeFontSubscript [::Excel]Excel, Main

Get the subscript font style of a cell or character range.

GetRangeFontSubscript rangeId
rangeIdIdentifier of the cell range.

Returns true, if the font in specified cell range has the subscript flag set.

See also: SetRangeFontSubscript, SelectRangeByIndex

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

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

GetRangeFontSuperscript [::Excel]Excel, Main

Get the superscript font style of a cell or character range.

GetRangeFontSuperscript rangeId
rangeIdIdentifier of the cell range.

Returns true, if the font in specified cell range has the superscript flag set.

See also: SetRangeFontSuperscript, SelectRangeByIndex, GetRangeCharacters

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 GetRangeCharacters

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

GetRangeFontUnderline [::Excel]Excel, Main

Get the underline font style of a cell range.

GetRangeFontUnderline rangeId
rangeIdIdentifier 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

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

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

GetRangeFormat [::Excel]Excel, Main

Get the number format of a cell range.

GetRangeFormat rangeId
rangeIdIdentifier of the cell range.

Returns the number format in Excel style.

See also: SetRangeFormat, SelectRangeByIndex, SelectRangeByString

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]
}

GetRangeHorizontalAlignment [::Excel]Excel, Main

Get the horizontal alignment of a cell range.

GetRangeHorizontalAlignment rangeId
rangeIdIdentifier of the cell range.

Returns the horizontal alignment as a value of enumeration type Enum::XlHAlign.

See also: SetRangeHorizontalAlignment, SelectRangeByIndex, SelectRangeByString

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]
}

GetRangeTextColor [::Excel]Excel, Main

Get the text color of a cell range.

GetRangeTextColor rangeId
rangeIdIdentifier 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

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]
}

GetRangeValues [::Excel]Excel, Main

Return range values as a matrix.

GetRangeValues rangeId
rangeIdIdentifier of the cell range.

Returns the range values as a matrix.

See also: SetRangeValues, GetMatrixValues, GetRowValues, GetColumnValues, GetCellValue

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]
}

GetRangeVerticalAlignment [::Excel]Excel, Main

Get the vertical alignment of a cell range.

GetRangeVerticalAlignment rangeId
rangeIdIdentifier of the cell range.

Returns the vertical alignment as a value of enumeration type Enum::XlVAlign.

See also: SetRangeVerticalAlignment, SelectRangeByIndex, SelectRangeByString

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]
}

GetRangeWrapText [::Excel]Excel, Main

Get the wrap text mode of a cell range.

GetRangeWrapText rangeId
rangeIdIdentifier of the cell range.

Returns true, if the specified cell range has the wrap text flag set.

See also: SetRangeWrapText, GetRangeHorizontalAlignment, GetRangeTextColor, SelectRangeByIndex

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]
}

GetRowValues [::Excel]Excel, Main

Return row values as a Tcl list.

GetRowValues worksheetId row ?startCol? ?numVals?
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
startColColumn number of start. Column numbering starts with 1. If negative or zero, start at first available column. Optional, default 0.
numValsIf negative or zero, all available row values are returned. If positive, only $numVals values of the row are returned. Optional, default 0.

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

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]
}

GetTablelistHeader [::Excel]Excel, Main

Return the header line of a tablelist as a list.

GetTablelistHeader tableId
tableIdIdentifier of the tablelist.

Returns the header line of the tablelist as a list.

See also: TablelistToWorksheet, WorksheetToTablelist, SetTablelistHeader, GetTablelistValues

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
}

GetTablelistValues [::Excel]Excel, Main

Return the values of a tablelist as a matrix.

GetTablelistValues tableId
tableIdIdentifier of the tablelist.

Returns the values of the tablelist as a matrix.

See also: TablelistToWorksheet, WorksheetToTablelist, SetTablelistValues, GetTablelistHeader

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]
}

GetThousandsSeparator [::Excel]Excel, Main

Return the thousands separator used by Excel.

GetThousandsSeparator appId
appIdIdentifier of the Excel instance.

Returns the thousands separator used by Excel.

See also: GetVersion, GetDecimalSeparator

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

    return [$appId ThousandsSeparator]
}

GetVersion [::Excel]Excel, Main

Return the version of an Excel application.

GetVersion objId ?useString?
objIdIdentifier of an Excel object instance.
useStringIf set to true, return the version name (ex. Excel 2000). Otherwise return the version number (ex. 9.0). Optional, default false.

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

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
}

GetWorkbookIdByName [::Excel]Excel, Main

Find an open workbook by its name.

GetWorkbookIdByName appId workbookName
appIdIdentifier of the Excel instance.
workbookNameName 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

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"
}

GetWorkbookName [::Excel]Excel, Main

Return the name of a workbook.

GetWorkbookName workbookId
workbookIdIdentifier of the workbook.

Returns the name of the workbook.

See also: AddWorkbook

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]
}

GetWorksheetAsMatrix [::Excel]Excel, Main

Return worksheet table as a matrix.

GetWorksheetAsMatrix worksheetId
worksheetIdIdentifier of the worksheet.

Returns the range of the worksheet with valid data as a matrix.

See also: SetMatrixValues, GetMatrixValues, GetFirstUsedRow, GetLastUsedRow

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]]
}

GetWorksheetIdByIndex [::Excel]Excel, Main

Find a worksheet by its index.

GetWorksheetIdByIndex workbookId index ?activate?
workbookIdIdentifier of the workbook containing the worksheet.
indexIndex of the worksheet to find.
activateIf set to true, activate the found worksheet. Otherwise just return the identifier. Optional, default true.

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

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
}

GetWorksheetIdByName [::Excel]Excel, Main

Find a worksheet by its name.

GetWorksheetIdByName workbookId worksheetName ?activate?
workbookIdIdentifier of the workbook containing the worksheet.
worksheetNameName of the worksheet to find.
activateIf set to true, activate the found worksheet. Otherwise just return the identifier. Optional, default true.

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

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"
}

GetWorksheetIndexByName [::Excel]Excel, Main

Find a worksheet index by its name.

GetWorksheetIndexByName workbookId worksheetName ?activate?
workbookIdIdentifier of the workbook containing the worksheet.
worksheetNameName of the worksheet to find.
activateIf set to true, activate the found worksheet. Otherwise just return the index. Optional, default true.

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

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"
}

GetWorksheetName [::Excel]Excel, Main

Return the name of a worksheet.

GetWorksheetName worksheetId
worksheetIdIdentifier of the worksheet.

Returns the name of the worksheet.

See also: SetWorksheetName, AddWorksheet

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]
}

HideColumn [::Excel]Excel, Main

Hide or unhide a column.

HideColumn worksheetId col ?hide?
worksheetIdIdentifier of the worksheet.
colColumn number. Column numbering starts with 1.
hideIf set to true, the specified column is hidden, otherwise it is shown. Optional, default true.

Returns no value.

See also: InsertColumn, DeleteColumn, DuplicateColumn, GetHiddenColumns, HideRow

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
}

HideRow [::Excel]Excel, Main

Hide or unhide a row.

HideRow worksheetId row ?hide?
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
hideIf set to true, the specified row is hidden, otherwise it is shown. Optional, default true.

Returns no value.

See also: InsertRow, DeleteRow, DuplicateRow, GetHiddenRows, HideColumn

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
}

ImgToWorksheet [::Excel]Excel, Main

Put a photo image into a worksheet.

ImgToWorksheet phImg worksheetId ?row? ?col? ?rowHeight? ?colWidth?
phImgThe photo image identifier.
worksheetIdIdentifier of the worksheet.
rowRow number of the top-left corner of the image. Row numbering starts with 1. Optional, default 1.
colColumn number of the top-left corner of the image. Column numbering starts with 1. Optional, default 1.
rowHeightRow height. Optional, default 9.
colWidthColumn width in average-size characters of the widget's font. Optional, default 1.

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

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
    }
}

Import [::Excel]Excel, Main

Import data from an external data source.

Import rangeId fileName ?args?
rangeIdIdentifier of the cell range.
fileNameFile name of the data source.
argsOptions described below.
-decimalseparator <char>Decimal separator character.
-delimiter <char>Delimiter character. Possible values: "\t" " " ";" ",".
-thousandsseparator <char>Thousands separator character.

Returns no value.

See also: OpenWorkbook, SaveAsCsv

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 $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
}

InsertColumn [::Excel]Excel, Main

Insert a new empty column.

InsertColumn worksheetId col
worksheetIdIdentifier of the worksheet.
colColumn 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

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
}

InsertImage [::Excel]Excel, Main

Insert an image into a worksheet.

InsertImage worksheetId imgFileName ?row? ?col? ?linkToFile? ?saveWithDoc?
worksheetIdIdentifier of the worksheet where the image is inserted.
imgFileNameFile name of the image.
rowRow number. Row numbering starts with 1. Optional, default 1.
colColumn number. Column numbering starts with 1. Optional, default 1.
linkToFileInsert a link to the image file. Optional, default false.
saveWithDocEmbed the image into the document. Optional, default true.

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

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
}

InsertRow [::Excel]Excel, Main

Insert a new empty row.

InsertRow worksheetId row
worksheetIdIdentifier of the worksheet.
rowRow 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

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
}

IsWorkbookId [::Excel]Excel, Main

Check, if Excel object is a workbook identifier.

IsWorkbookId objId
objIdThe identifier of an Excel object.

Returns true, if $objId is a valid Excel workbook identifier. Otherwise returns false.

See also: ::Cawt::IsComObject, ::Office::GetApplicationId

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
    }
}

IsWorkbookOpen [::Excel]Excel, Main

Check, if a workbook is open.

IsWorkbookOpen appId workbookName
appIdIdentifier of the Excel instance.
workbookNameName of the workbook to find.

Returns true, if the workbook is open, otherwise false.

See also: OpenWorkbook, IsWorkbookProtected

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
    }
}

IsWorkbookProtected [::Excel]Excel, Main

Check, if a workbook is protected.

IsWorkbookProtected workbookId
workbookIdIdentifier of the workbook to be checked.

Returns true, if the workbook is protected, otherwise false.

See also: OpenWorkbook, IsWorkbookOpen

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
    }
}

IsWorksheetEmpty [::Excel]Excel, Main

Check, if a worksheet is empty.

IsWorksheetEmpty worksheetId
worksheetIdIdentifier of the worksheet to be checked.

Returns true, if the worksheet is empty, otherwise false.

See also: GetNumUsedRows, GetNumUsedColumns, GetFirstUsedRow, GetLastUsedRow

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
}

IsWorksheetProtected [::Excel]Excel, Main

Check, if a worksheet is content protected.

IsWorksheetProtected worksheetId
worksheetIdIdentifier of the worksheet to be checked.

Returns true, if the worksheet is protected, otherwise false.

See also: AddWorksheet

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
    }
}

IsWorksheetVisible [::Excel]Excel, Main

Check, if a worksheet is visible.

IsWorksheetVisible worksheetId
worksheetIdIdentifier of the worksheet to be checked.

Returns true, if the worksheet is visible, otherwise false.

See also: AddWorksheet

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
    }
}

ListToCsvRow [::Excel]Excel, Main

Return a list of column values as a CSV encoded row string.

ListToCsvRow rowList
rowListList of column values.

Returns the list of column values as a CSV encoded row string.

See also: CsvRowToList

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
}

MatlabFileToExcelFile [::Excel]Excel, Main

Convert a Matlab table file to an Excel file.

MatlabFileToExcelFile matFileName excelFileName ?useHeader? ?quitExcel?
matFileNameName of the Matlab input file.
excelFileNameName of the Excel output file.
useHeaderIf set to true, insert the header of the Matlab file as first row. Otherwise only transfer the data values as floating point values. Optional, default true.
quitExcelIf set to true, quit the Excel instance after generation of output file. Otherwise leave the Excel instance open after generation of output file. Optional, default true.

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

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
    }
}

MatlabFileToWorksheet [::Excel]Excel, Main

Insert the data values of a Matlab file into a worksheet.

MatlabFileToWorksheet matFileName worksheetId ?useHeader?
matFileNameName of the Matlab file.
worksheetIdIdentifier of the worksheet.
useHeaderIf set to true, insert the header of the Matlab file as first row. Otherwise only transfer the data values as floating point values. Optional, default true.

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

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
}

MatrixToClipboard [::Excel]Excel, Main

Copy a matrix into the clipboard.

MatrixToClipboard matrixList ?sepChar?
matrixListMatrix with table data.
sepCharThe separation character of the clipboard matrix data. Optional, default ;.

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

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
}

MatrixToCsvString [::Excel]Excel, Main

Return a CSV encoded table string from a matrix list.

MatrixToCsvString matrixList
matrixListMatrix with table data.

Returns the CSV encoded table string from a matrix list.

See also: CsvStringToMatrix, ListToCsvRow

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]
}

MediaWikiFileToExcelFile [::Excel]Excel, Main

Convert a MediaWiki table file to an Excel file.

MediaWikiFileToExcelFile wikiFileName excelFileName ?useHeader? ?quitExcel?
wikiFileNameName of the MediaWiki input file.
excelFileNameName of the Excel output file.
useHeaderIf set to true, use header information from the MediaWiki file to generate an Excel header (see SetHeaderRow). Otherwise only transfer the table data. Optional, default true.
quitExcelIf set to true, quit the Excel instance after generation of output file. Otherwise leave the Excel instance open after generation of output file. Optional, default true.

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

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
    }
}

MediaWikiFileToWorksheet [::Excel]Excel, Main

Insert the values of a MediaWiki table file into a worksheet.

MediaWikiFileToWorksheet wikiFileName worksheetId ?useHeader?
wikiFileNameName of the MediaWiki file.
worksheetIdIdentifier of the worksheet.
useHeaderIf set to true, insert the header of the MediaWiki table as first row. Otherwise only transfer the table data. Optional, default true.

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

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
}

Open [::Excel]Excel, Main

Open an Excel instance. Use an already running instance, if available.

Open ?visible? ?width? ?height?
visibleIf set to true, show the application window. Otherwise hide the application window. Optional, default true.
widthWidth of the application window. If negative, open with last used width. Optional, default -1.
heightHeight of the application window. If negative, open with last used height. Optional, default -1.

Returns the identifier of the Excel application instance.

See also: OpenNew, Quit, Visible

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
}

OpenNew [::Excel]Excel, Main

Open a new Excel instance.

OpenNew ?visible? ?width? ?height?
visibleIf set to true, show the application window. Otherwise hide the application window. Optional, default true.
widthWidth of the application window. If negative, open with last used width. Optional, default -1.
heightHeight of the application window. If negative, open with last used height. Optional, default -1.

Returns the identifier of the new Excel application instance.

See also: Open, Quit, Visible

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
}

OpenWorkbook [::Excel]Excel, Main

Open a workbook, i.e. load an Excel file.

OpenWorkbook appId fileName ?readOnly?
appIdIdentifier of the Excel instance.
fileNameName of the Excel file.
readOnlyIf set to true, open the workbook in read-only mode. Otherwise open the workbook in read-write mode. Optional, default false.

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

proc ::Excel::OpenWorkbook {appId fileName {readOnly false}} {

    # Open a workbook, i.e. load an Excel file.
    #
    # appId    - Identifier of the Excel instance.
    # fileName - Name of the Excel file.
    # readOnly - If set to true, open the workbook in read-only mode.
    #            Otherwise open the workbook in read-write mode.
    #
    # 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

    if { [Excel IsWorkbookOpen $appId $fileName] } {
        set workbookId [Excel GetWorkbookIdByName $appId $fileName]
        $workbookId Activate
        return $workbookId
    }

    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 $readOnly]]
    Cawt Destroy $workbooks
    return $workbookId
}

PlaceChart [::Excel]Excel, Main

Place an existing chart into a worksheet.

PlaceChart chartId worksheetId
chartIdIdentifier of the chart.
worksheetIdIdentifier of the worksheet.

Returns the ChartObject identifier of the placed chart.

See also: CreateChart, SetChartObjSize, SetChartObjPosition

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
}

Quit [::Excel]Excel, Main

Quit an Excel instance.

Quit appId ?showAlert?
appIdIdentifier of the Excel instance.
showAlertIf set to true, show an alert window, if there are unsaved changes. Otherwise quit without asking and saving any changes. Optional, default true.

Returns no value.

See also: Open, OpenNew

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
}

RawImageFileToExcelFile [::Excel]Excel, Main

Convert a raw photo image file to an Excel file.

RawImageFileToExcelFile rawFileName excelFileName ?useHeader? ?quitExcel?
rawFileNameName of the raw photo image input file.
excelFileNameName of the Excel output file.
useHeaderIf set to true, use header information from the image file to generate an Excel header (see SetHeaderRow). Otherwise only transfer the image data. Optional, default true.
quitExcelIf set to true, quit the Excel instance after generation of output file. Otherwise leave the Excel instance open after generation of output file. Optional, default true.

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

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
    }
}

RawImageFileToWorksheet [::Excel]Excel, Main

Insert the pixel values of a raw photo image into a worksheet.

RawImageFileToWorksheet rawFileName worksheetId ?useHeader?
rawFileNameFile name of the image.
worksheetIdIdentifier of the worksheet.
useHeaderIf set to true, insert the header of the raw image as first row. Otherwise only transfer the pixel values as floating point values. Optional, default true.

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

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
}

ReadCsvFile [::Excel]Excel, Main

Read a CSV table file into a matrix.

ReadCsvFile csvFileName ?useHeader? ?numHeaderRows?
csvFileNameName of the CSV file.
useHeaderIf set to true, insert the header rows of the CSV file into the matrix. Otherwise only transfer the table data. Optional, default true.
numHeaderRowsNumber of rows interpreted as header rows. Optional, default 0.

See SetMatrixValues for the description of a matrix representation.

Returns the CSV table data as a matrix.

See also: WriteCsvFile

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 crlf

    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
}

ReadMatlabFile [::Excel]Excel, Main

Read a Matlab file into a matrix.

ReadMatlabFile matFileName
matFileNameName 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

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
}

ReadMatlabHeader [::Excel]Excel, Main

Read the header of a Matlab file.

ReadMatlabHeader matFileName
matFileNameName of the Matlab file.

Returns the header information as a list of integers containing the following values: MatlabVersion Width Height

See also: ReadMatlabFile

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
}

ReadMediaWikiFile [::Excel]Excel, Main

Read a MediaWiki table file into a matrix.

ReadMediaWikiFile wikiFileName ?useHeader?
wikiFileNameName of the MediaWiki file.
useHeaderIf set to true, insert the header of the MediaWiki table as first row. Otherwise only transfer the table data. Optional, default true.

Returns the MediaWiki table data as a matrix. See SetMatrixValues for the description of a matrix representation.

See also: WriteMediaWikiFile, MediaWikiFileToWorksheet

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
}

ReadRawImageFile [::Excel]Excel, Main

Read a raw photo image into a matrix.

ReadRawImageFile rawImgFile
rawImgFileFile 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

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
}

ReadRawImageHeader [::Excel]Excel, Main

Read the header of a raw photo image.

ReadRawImageHeader rawImgFile
rawImgFileFile 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

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
}

ReadWikitFile [::Excel]Excel, Main

Read a Wikit table file into a matrix.

ReadWikitFile wikiFileName ?useHeader?
wikiFileNameName of the Wikit file.
useHeaderIf set to true, insert the header of the Wikit table as first row. Otherwise only transfer the table data. Optional, default true.

Returns the Wikit table data as a matrix. See SetMatrixValues for the description of a matrix representation.

See also: WriteWikitFile, WikitFileToWorksheet

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
}

ResizeChartObj [::Excel]Excel, Main

Set the position and size of a chart object.

ResizeChartObj chartObjId rangeId
chartObjIdIdentifier of the chart object.
rangeIdIdentifier 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

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
}

SaveAs [::Excel]Excel, Main

Save a workbook to an Excel file.

SaveAs workbookId fileName ?fmt? ?backup?
workbookIdIdentifier of the workbook to save.
fileNameName of the Excel file.
fmtValue 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. Optional, default "".
backupIf set to true, create a backup file before saving. Otherwise do not create a backup file. Optional, default false.

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

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
}

SaveAsCsv [::Excel]Excel, Main

Save a worksheet to file in CSV format.

SaveAsCsv workbookId worksheetId fileName ?fmt?
workbookIdIdentifier of the workbook containing the worksheet.
worksheetIdIdentifier of the worksheet to save.
fileNameName of the CSV file.
fmtValue of enumeration type Enum::XlFileFormat. Optional, default xlCSV.

Returns no value.

See also: SaveAs, Close, OpenWorkbook

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
}

SaveChartAsImage [::Excel]Excel, Main

Obsolete: Replaced with SaveChartObjAsImage in version 1.0.1

SaveChartAsImage chartId fileName ?filterType?
chartIdNot documented.
fileNameNot documented.
filterTypeNot documented. Optional, default GIF.
proc ::Excel::SaveChartAsImage {chartId fileName {filterType GIF}} {

    # Obsolete: Replaced with [SaveChartObjAsImage] in version 1.0.1

    Excel SaveChartObjAsImage $chartId $fileName $filterType
}

SaveChartObjAsImage [::Excel]Excel, Main

Save a chart as an image in a file.

SaveChartObjAsImage chartObjId fileName ?filterType?
chartObjIdIdentifier of the chart object.
fileNameImage file name.
filterTypeName of graphic filter. Possible values: GIF, JPEG, PNG. Optional, default GIF.

Returns no value.

See also: ChartObjToClipboard, CreateChart

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
}

ScaleImage [::Excel]Excel, Main

Scale an image.

ScaleImage shapeId scaleWidth scaleHeight
shapeIdIdentifier of the image shape.
scaleWidthHorizontal scale factor.
scaleHeightVertical scale factor.

The scale factors are floating point values. 1.0 means no scaling.

Returns no value.

See also: InsertImage

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]
}

ScreenUpdate [::Excel]Excel, Main

Toggle the screen updating of an Excel application window.

ScreenUpdate appId onOff
appIdIdentifier of the Excel instance.
onOffIf set to true, update the application window. Otherwise do not update the application window.

Returns no value.

See also: Visible, SetWindowState, ArrangeWindows

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]
}

Search [::Excel]Excel, Main

Find a string in a worksheet cell range.

Search worksheetId str ?row1? ?col1? ?row2? ?col2?
worksheetIdIdentifier of the worksheet.
strSearch string.
row1Row number of upper-left corner of the cell range. Optional, default 1.
col1Column number of upper-left corner of the cell range. Optional, default 1.
row2Row number of lower-right corner of the cell range. Optional, default -1.
col2Column number of lower-right corner of the cell range. Optional, default -1.

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.

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]
}

SelectAll [::Excel]Excel, Main

Select all cells of a worksheet.

SelectAll worksheetId
worksheetIdIdentifier of the worksheet.

Returns the cells collection of the selected cells.

See also: CopyWorksheet

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
}

SelectCellByIndex [::Excel]Excel, Main

Select a cell by its row/column index.

SelectCellByIndex worksheetId row col ?visSel?
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
colColumn number. Column numbering starts with 1.
visSelIf set to true, see the selection in the user interface. Otheriwse the selection is not visible. Optional, default false.

Returns the identifier of the cell as a range identifier.

See also: SelectRangeByIndex, AddWorksheet

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]
}

SelectRangeByIndex [::Excel]Excel, Main

Select a range by specifying a numeric cell range.

SelectRangeByIndex worksheetId row1 col1 row2 col2 ?visSel?
worksheetIdIdentifier of the worksheet.
row1Row number of upper-left corner of the cell range.
col1Column number of upper-left corner of the cell range.
row2Row number of lower-right corner of the cell range.
col2Column number of lower-right corner of the cell range.
visSelIf set to true, see the selection in the user interface. Otherwise the selection is not visible. Optional, default false.

Returns the range identifier of the cell range.

See also: SelectCellByIndex, GetCellRange

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: SelectCellByIndex GetCellRange

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

SelectRangeByString [::Excel]Excel, Main

Select a range by specifying an Excel range string in A1 notation.

SelectRangeByString worksheetId rangeStr ?visSel?
worksheetIdIdentifier of the worksheet.
rangeStrString specifying a cell range, ex. A8:C10.
visSelIf set to true, see the selection in the user interface. Otherwise the selection is not visible. Optional, default false.

Returns the range identifier of the cell range.

See also: SelectRangeByIndex, GetCellRange

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
}

SetCellValue [::Excel]Excel, Main

Set the value of a cell.

SetCellValue worksheetId row col val ?fmt? ?subFmt?
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
colColumn number. Column numbering starts with 1.
valString value of the cell.
fmtFormat of the cell. Possible values: text, int, real. Optional, default text.
subFmtFormatting option of the floating-point value (see SetRangeFormat). Optional, default "".

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

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
}

SetChartMaxScale [::Excel]Excel, Main

Set the maximum scale of an axis of a chart.

SetChartMaxScale chartId axisName value
chartIdIdentifier of the chart.
axisNameName of axis. Possible values: x or y.
valueScale value.

Returns no value.

See also: SetChartMinScale, SetChartScale, SetChartObjSize

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
}

SetChartMinScale [::Excel]Excel, Main

Set the minimum scale of an axis of a chart.

SetChartMinScale chartId axisName value
chartIdIdentifier of the chart.
axisNameName of axis. Possible values: x or y.
valueScale value.

Returns no value.

See also: SetChartMaxScale, SetChartScale, SetChartObjSize

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
}

SetChartObjPosition [::Excel]Excel, Main

Set the position of a chart object.

SetChartObjPosition chartObjId left top
chartObjIdIdentifier of the chart object.
leftLeft border of the chart object in pixel.
topTop border of the chart object in pixel.

Returns no value.

See also: PlaceChart, SetChartObjSize, SetChartScale

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
}

SetChartObjSize [::Excel]Excel, Main

Set the size of a chart object.

SetChartObjSize chartObjId width height
chartObjIdIdentifier of the chart object.
widthWidth of the chart object in pixel.
heightHeight of the chart object in pixel.

Returns no value.

See also: PlaceChart, SetChartObjPosition, SetChartScale

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
}

SetChartScale [::Excel]Excel, Main

Set the minimum and maximum scale of both axes of a chart.

SetChartScale chartId xmin xmax ymin ymax
chartIdIdentifier of the chart.
xminMinimum scale value of x axis.
xmaxMaximum scale value of x axis.
yminMinimum scale value of y axis.
ymaxMaximum scale value of y axis.

Returns no value.

See also: SetChartMinScale, SetChartMaxScale, SetChartObjSize

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
}

SetChartSize [::Excel]Excel, Main

Obsolete: Replaced with SetChartObjSize in version 1.0.1

SetChartSize worksheetId chartId width height
worksheetIdNot documented.
chartIdNot documented.
widthNot documented.
heightNot documented.
proc ::Excel::SetChartSize {worksheetId chartId width height} {

    # Obsolete: Replaced with [SetChartObjSize] in version 1.0.1

    Excel SetChartObjSize $worksheetId $chartId $width $height
}

SetChartSourceByIndex [::Excel]Excel, Main

Set the cell range for the source of a chart.

SetChartSourceByIndex chartId worksheetId row1 col1 row2 col2 ?type?
chartIdIdentifier of the chart.
worksheetIdIdentifier of the worksheet.
row1Row number of upper-left corner of the cell range.
col1Column number of upper-left corner of the cell range.
row2Row number of lower-right corner of the cell range.
col2Column number of lower-right corner of the cell range.
typeValue of enumeration type Enum::XlRowCol. Optional, default xlColumns.

Returns no value.

See also: CreateChart, SetChartTitle, SetChartScale

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
}

SetChartTicks [::Excel]Excel, Main

Set the tick spacing of an axis of a chart.

SetChartTicks chartId axisName ?tickMarkSpacing? ?tickLabelSpacing?
chartIdIdentifier of the chart.
axisNameName of axis. Possible values: x or y.
tickMarkSpacingSpacing of tick marks. Optional, default "".
tickLabelSpacingSpacing of tick labels. Optional, default "".

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

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
}

SetChartTitle [::Excel]Excel, Main

Set the title of a chart.

SetChartTitle chartId title
chartIdIdentifier of the chart.
titleName of the chart title.

Returns no value.

See also: SetChartMinScale, SetChartScale, CreateChart

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
    }
}

SetColumnsWidth [::Excel]Excel, Main

Set the width of a range of columns.

SetColumnsWidth worksheetId startCol endCol ?width?
worksheetIdIdentifier of the worksheet.
startColRange start column number. Column numbering starts with 1.
endColRange end column number. Column numbering starts with 1.
widthA 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. Optional, default 0.

Returns no value.

See also: SetColumnWidth, ColumnCharToInt

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
    }
}

SetColumnValues [::Excel]Excel, Main

Insert column values from a Tcl list.

SetColumnValues worksheetId col valList ?startRow? ?numVals?
worksheetIdIdentifier of the worksheet.
colColumn number. Column numbering starts with 1.
valListList of values to be inserted.
startRowRow number of insertion start. Row numbering starts with 1. Optional, default 1.
numValsIf negative or zero, all list values are inserted. If positive, $numVals rows are filled with the list values (starting at list index 0). Optional, default 0.

Returns no value.

See also: GetColumnValues, SetRowValues, SetCellValue, ColumnCharToInt

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
}

SetColumnWidth [::Excel]Excel, Main

Set the width of a column.

SetColumnWidth worksheetId col ?width?
worksheetIdIdentifier of the worksheet.
colColumn number. Column numbering starts with 1.
widthA 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. Optional, default 0.

Returns no value.

See also: SetColumnsWidth, ColumnCharToInt

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
}

SetCommentDisplayMode [::Excel]Excel, Main

Set the global display mode of comments.

SetCommentDisplayMode appId ?showComment? ?showIndicator?
appIdIdentifier of the Excel instance.
showCommentIf set to true, show the comments. Otherwise do not show the comments. Optional, default false.
showIndicatorIf set to true, show an indicator for the comments. Otherwise do not show an indicator. Optional, default true.

Returns no value.

See also: SetRangeComment, SetCommentSize, GetCellComment

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
    }
}

SetCommentSize [::Excel]Excel, Main

Set the shape size of a comment.

SetCommentSize commentId width height
commentIdIdentifier of the comment.
widthWidth of the comment.
heightHeight 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

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]
}

SetCsvSeparatorChar [::Excel]Excel, Main

Set the column separator character.

SetCsvSeparatorChar ?separatorChar?
separatorCharThe character used as the column separator. Optional, default ;.

Returns no value.

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
}

SetHeaderRow [::Excel]Excel, Main

Insert row values from a Tcl list and format as a header row.

SetHeaderRow worksheetId headerList ?row? ?startCol?
worksheetIdIdentifier of the worksheet.
headerListList of values to be inserted as header.
rowRow number. Row numbering starts with 1. Optional, default 1.
startColColumn number of insertion start. Column numbering starts with 1. Optional, default 1.

Returns no value. If $headerList is an empty list, an error is thrown.

See also: SetRowValues, FormatHeaderRow

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}]
}

SetHyperlink [::Excel]Excel, Main

Insert a hyperlink into a cell.

SetHyperlink worksheetId row col link ?textDisplay?
worksheetIdIdentifier of the worksheet the hyperlink is inserted to.
rowRow number. Row numbering starts with 1.
colColumn number. Column numbering starts with 1.
linkURL of the hyperlink.
textDisplayText to be displayed instead of the URL. Optional, default "".

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

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
}

SetHyperlinkToCell [::Excel]Excel, Main

Insert a hyperlink to a cell into another cell.

SetHyperlinkToCell srcWorksheetId srcRow srcCol destWorksheetId destRow destCol ?textDisplay?
srcWorksheetIdIdentifier of the worksheet the link points to.
srcRowSource row number. Row numbering starts with 1.
srcColSource column number. Column numbering starts with 1.
destWorksheetIdIdentifier of the worksheet the link is inserted into.
destRowDestination row number. Row numbering starts with 1.
destColDestination column number. Column numbering starts with 1.
textDisplayText to be displayed instead of the hyperlink. Optional, default "".

Returns no value.

See also: AddWorksheet, SetHyperlinkToFile, SetHyperlink, SetLinkToCell

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
}

SetHyperlinkToFile [::Excel]Excel, Main

Insert a hyperlink to a file into a cell.

SetHyperlinkToFile worksheetId row col fileName ?textDisplay?
worksheetIdIdentifier of the worksheet the hyperlink is inserted to.
rowRow number. Row numbering starts with 1.
colColumn number. Column numbering starts with 1.
fileNamePath name of the linked file.
textDisplayText to be displayed instead of the file name. Optional, default "".

Returns no value.

See also: AddWorksheet, SetHyperlinkToCell, SetHyperlink, SetLinkToCell

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
}

SetLinkToCell [::Excel]Excel, Main

Insert an internal link to a cell into another cell.

SetLinkToCell srcWorksheetId srcRow srcCol destWorksheetId destRow destCol
srcWorksheetIdIdentifier of the worksheet the link points to.
srcRowSource row number. Row numbering starts with 1.
srcColSource column number. Column numbering starts with 1.
destWorksheetIdIdentifier of the worksheet the link is inserted to.
destRowDestination row number. Row numbering starts with 1.
destColDestination 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

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
}

SetMatrixValues [::Excel]Excel, Main

Insert matrix values into a worksheet.

SetMatrixValues worksheetId matrixList ?startRow? ?startCol?
worksheetIdIdentifier of the worksheet.
matrixListMatrix with table data.
startRowRow number of insertion start. Row numbering starts with 1. Optional, default 1.
startColColumn number of insertion start. Column numbering starts with 1. Optional, default 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

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 numCols [llength [lindex $matrixList 0]]
    set numRows [llength $matrixList]

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

SetNamedRange [::Excel]Excel, Main

Set the name of a cell range.

SetNamedRange rangeId rangeName ?useWorksheet?
rangeIdIdentifier of the cell range.
rangeNameName of the cell range. Must not contain spaces.
useWorksheetIf set to true, set the name at the worksheet level. Otherwise set it at the workbook level. Optional, default true.

Returns no value.

See also: GetNamedRange, GetNamedRangeNames

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
}

SetRangeBorder [::Excel]Excel, Main

Set the attributes of one border of a cell range.

SetRangeBorder rangeId side ?weight? ?lineStyle? ?args?
rangeIdIdentifier of the cell range.
sideValue of enumeration type Enum::XlBordersIndex. Typical values: xlEdgeLeft, xlEdgeTop, xlEdgeBottom, xlEdgeRight.
weightValue of enumeration type Enum::XlBorderWeight. Typical values: xlThin, xlMedium, xlThick. Optional, default xlThin.
lineStyleValue of enumeration type Enum::XlLineStyle. Typical values: xlContinuous, xlDash, xlDot. Optional, default xlContinuous.
argsBorder 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

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
}

SetRangeBorders [::Excel]Excel, Main

Set the attributes of all borders of a cell range.

SetRangeBorders rangeId ?weight? ?lineStyle? ?r? ?g? ?b?
rangeIdIdentifier of the cell range.
weightValue of enumeration type Enum::XlBorderWeight. Typical values: xlThin, xlMedium, xlThick. Optional, default xlThin.
lineStyleValue of enumeration type Enum::XlLineStyle. Typical values: xlContinuous, xlDash, xlDot. Optional, default xlContinuous.
rRed component of the border color. Optional, default 0.
gGreen component of the border color. Optional, default 0.
bBlue component of the border color. Optional, default 0.

The r, g and b values are specified as integers in the range [0, 255].

Returns no value.

See also: SetRangeBorder, SelectRangeByIndex, SelectRangeByString

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
}

SetRangeComment [::Excel]Excel, Main

Set the comment text of a cell range.

SetRangeComment rangeId comment ?imgFileName? ?addUserName? ?visible?
rangeIdIdentifier of the cell range.
commentComment text.
imgFileNameFile name of an image used as comment background. Optional, default "".
addUserNameAutomatically add user name before comment text. Optional, default true.
visibleIf set to true, show the comment window. Otherwise hide the comment window. Optional, default false.

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

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
}

SetRangeFillColor [::Excel]Excel, Main

Set the fill color of a cell range.

SetRangeFillColor rangeId ?args?
rangeIdIdentifier of the cell range.
argsBackground 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

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
}

SetRangeFontBold [::Excel]Excel, Main

Set the bold font style of a cell range.

SetRangeFontBold rangeId ?onOff?
rangeIdIdentifier of the cell range.
onOffIf set to true, set bold style on. Otherwise set bold style off. Optional, default true.

Returns no value.

See also: SetRangeFontName, SetRangeFontItalic, SetRangeFontUnderline, SetRangeFontSize, SelectRangeByIndex

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: SetRangeFontName SetRangeFontItalic SetRangeFontUnderline SetRangeFontSize SelectRangeByIndex

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

SetRangeFontItalic [::Excel]Excel, Main

Set the italic font style of a cell range.

SetRangeFontItalic rangeId ?onOff?
rangeIdIdentifier of the cell range.
onOffIf set to true, set italic style on. Otherwise set italic style off. Optional, default true.

Returns no value.

See also: SetRangeFontName, SetRangeFontBold, SetRangeFontUnderline, SetRangeFontSize, SelectRangeByIndex

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: SetRangeFontName SetRangeFontBold SetRangeFontUnderline SetRangeFontSize SelectRangeByIndex

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

SetRangeFontName [::Excel]Excel, Main

Set the font name of a cell or character range.

SetRangeFontName rangeId fontName
rangeIdIdentifier of the cell range.
fontNameName of the font as a string.

Returns no value.

See also: SetRangeFontSubscript, SetRangeFontSuperscript, SetRangeFontBold, SetRangeFontSize, SelectRangeByIndex

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: SetRangeFontSubscript SetRangeFontSuperscript SetRangeFontBold SetRangeFontSize SelectRangeByIndex

    $rangeId -with { Font } Name $fontName
}

SetRangeFontSize [::Excel]Excel, Main

Set the font size of a cell range.

SetRangeFontSize rangeId size
rangeIdIdentifier of the cell range.
sizeFont size.

The size value may be specified in a format acceptable by procedure ::Cawt::ValueToPoints, i.e. centimeters, inches or points.

Returns no value.

See also: SetRangeFontName, SetRangeFontBold, SetRangeFontItalic, SetRangeFontUnderline, SelectRangeByIndex

proc ::Excel::SetRangeFontSize {rangeId size} {

    # Set the font size of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # size    - Font size.
    #
    # The size value may be specified in a format acceptable by
    # procedure [::Cawt::ValueToPoints], i.e. centimeters, inches or points.
    #
    # Returns no value.
    #
    # See also: SetRangeFontName SetRangeFontBold SetRangeFontItalic SetRangeFontUnderline
    # SelectRangeByIndex

    $rangeId -with { Font } Size [Cawt ValueToPoints $size]
}

SetRangeFontSubscript [::Excel]Excel, Main

Set the subscript font style of a cell or character range.

SetRangeFontSubscript rangeId ?onOff?
rangeIdIdentifier of the cell range.
onOffIf set to true, set subscript style on. Otherwise set subscript style off. Optional, default true.

Returns no value.

See also: SetRangeFontName, SetRangeFontSuperscript, SelectRangeByIndex

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

    # Set the subscript font style of a cell or character range.
    #
    # rangeId - Identifier of the cell range.
    # onOff   - If set to true, set subscript style on.
    #           Otherwise set subscript style off.
    #
    # Returns no value.
    #
    # See also: SetRangeFontName SetRangeFontSuperscript SelectRangeByIndex

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

SetRangeFontSuperscript [::Excel]Excel, Main

Set the superscript font style of a cell or character range.

SetRangeFontSuperscript rangeId ?onOff?
rangeIdIdentifier of the cell range.
onOffIf set to true, set superscript style on. Otherwise set superscript style off. Optional, default true.

Returns no value.

See also: SetRangeFontName, SetRangeFontSubscript, SelectRangeByIndex, GetRangeCharacters

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

    # Set the superscript font style of a cell or character range.
    #
    # rangeId - Identifier of the cell range.
    # onOff   - If set to true, set superscript style on.
    #           Otherwise set superscript style off.
    #
    # Returns no value.
    #
    # See also: SetRangeFontName SetRangeFontSubscript SelectRangeByIndex GetRangeCharacters

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

SetRangeFontUnderline [::Excel]Excel, Main

Set the underline font style of a cell range.

SetRangeFontUnderline rangeId ?style?
rangeIdIdentifier of the cell range.
styleValue of enumeration type Enum::XlUnderlineStyle. Optional, default xlUnderlineStyleSingle.

Returns no value.

See also: SetRangeFontName, SetRangeFontBold, SetRangeFontItalic, SetRangeFontSize, SelectRangeByIndex

proc ::Excel::SetRangeFontUnderline {rangeId {style xlUnderlineStyleSingle}} {

    # Set the underline font style of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # style   - Value of enumeration type [Enum::XlUnderlineStyle].
    #
    # Returns no value.
    #
    # See also: SetRangeFontName SetRangeFontBold SetRangeFontItalic SetRangeFontSize SelectRangeByIndex

    $rangeId -with { Font } Underline [Excel GetEnum $style]
}

SetRangeFormat [::Excel]Excel, Main

Set the number format of a cell range.

SetRangeFormat rangeId fmt ?subFmt?
rangeIdIdentifier of the cell range.
fmtFormat of the cell range. Possible values: "text", "int", "real".
subFmtSub-format of the cell range. Only valid, if fmt is "real". Then it specifies the number of digits before and after the decimal point. Use the GetNumberFormat procedure for specifying the sub-format. If subFmt is the empty string 2 digits after the decimal point are used. Optional, default "".

If parameter $fmt is not any of the predefined values, it is interpreted as a custom number format specified in Excel style.

Returns no value.

See also: GetRangeFormat, SelectRangeByIndex, SelectRangeByString

proc ::Excel::SetRangeFormat {rangeId fmt {subFmt {}}} {

    # Set the number format of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # fmt     - Format of the cell range.  Possible values: "text", "int", "real".
    # subFmt  - Sub-format of the cell range. Only valid, if fmt is "real". Then it
    #           specifies the number of digits before and after the decimal point.
    #           Use the [GetNumberFormat] procedure for specifying the sub-format.
    #           If subFmt is the empty string 2 digits after the decimal point are used.
    #
    # If parameter $fmt is not any of the predefined values, it is interpreted as a
    # custom number format specified in Excel style.
    #
    # Returns no value.
    #
    # See also: GetRangeFormat SelectRangeByIndex SelectRangeByString

    if { $fmt eq "text" } {
        set numberFormat "@"
    } elseif { $fmt eq "int" } {
        set numberFormat "0"
    } elseif { $fmt eq "real" } {
        if { $subFmt eq "" } {
            set appId  [Office GetApplicationId $rangeId]
            set subFmt [Excel GetNumberFormat $appId "0" "00"]
            Cawt Destroy $appId
        }
        set numberFormat $subFmt
    } else {
        set numberFormat $fmt
    }
    $rangeId NumberFormat [Cawt TclString $numberFormat]
}

SetRangeHorizontalAlignment [::Excel]Excel, Main

Set the horizontal alignment of a cell range.

SetRangeHorizontalAlignment rangeId align
rangeIdIdentifier of the cell range.
alignValue of enumeration type Enum::XlHAlign.

Returns no value.

See also: GetRangeHorizontalAlignment, SetRangeVerticalAlignment, SelectRangeByIndex, SelectRangeByString

proc ::Excel::SetRangeHorizontalAlignment {rangeId align} {

    # Set the horizontal alignment of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # align   - Value of enumeration type [Enum::XlHAlign].
    #
    # Returns no value.
    #
    # See also: GetRangeHorizontalAlignment SetRangeVerticalAlignment
    # SelectRangeByIndex SelectRangeByString

    $rangeId HorizontalAlignment [Excel GetEnum $align]
}

SetRangeMergeCells [::Excel]Excel, Main

Merge/Unmerge a range of cells.

SetRangeMergeCells rangeId ?onOff?
rangeIdIdentifier of the cell range.
onOffIf set to true, set cell merge on. Otherwise set cell merge off. Optional, default true.

Returns no value.

See also: SetRangeVerticalAlignment, SelectRangeByIndex, SelectRangeByString

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

    # Merge/Unmerge a range of cells.
    #
    # rangeId - Identifier of the cell range.
    # onOff   - If set to true, set cell merge on.
    #           Otherwise set cell merge off.
    #
    # Returns no value.
    #
    # See also: SetRangeVerticalAlignment SelectRangeByIndex SelectRangeByString

    set appId [Office GetApplicationId $rangeId]
    Excel::ShowAlerts $appId false
    $rangeId MergeCells [Cawt TclBool $onOff]
    Excel::ShowAlerts $appId true
    Cawt Destroy $appId
}

SetRangeTextColor [::Excel]Excel, Main

Set the text color of a cell range.

SetRangeTextColor rangeId ?args?
rangeIdIdentifier of the cell range.
argsText 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: SetRangeFillColor, SelectRangeByIndex, SelectRangeByString

proc ::Excel::SetRangeTextColor {rangeId args} {

    # Set the text color of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # args    - Text 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: SetRangeFillColor SelectRangeByIndex SelectRangeByString

    set color [Cawt GetColor {*}$args]
    $rangeId -with { Font } Color $color
}

SetRangeTooltip [::Excel]Excel, Main

Set a selection based tooltip for a cell range.

SetRangeTooltip rangeId tooltipMessage ?tooltipTitle?
rangeIdIdentifier of the cell range.
tooltipMessageThe tooltip message string.
tooltipTitleThe optional tooltip title string. Optional, default "".

The tooltip will be shown, if the cell is selected by the user. It is implemented by using the data validation functionality of Excel. If a mouse-over tooltip is needed, use SetRangeComment.

Returns the validation identifier.

See also: SelectRangeByIndex, SelectRangeByString, SetRangeComment

proc ::Excel::SetRangeTooltip {rangeId tooltipMessage {tooltipTitle {}}} {

    # Set a selection based tooltip for a cell range.
    #
    # rangeId        - Identifier of the cell range.
    # tooltipMessage - The tooltip message string.
    # tooltipTitle   - The optional tooltip title string.
    #
    # The tooltip will be shown, if the cell is selected by the user. It is implemented by using
    # the data validation functionality of Excel.
    # If a mouse-over tooltip is needed, use [SetRangeComment].
    #
    # Returns the validation identifier.
    #
    # See also: SelectRangeByIndex SelectRangeByString SetRangeComment

    set validationId [$rangeId Validation]
    $validationId Add $Excel::xlValidateInputOnly
    $validationId InputMessage $tooltipMessage
    if { $tooltipTitle ne "" } {
        $validationId InputTitle $tooltipTitle
    }
    $validationId ShowInput [Cawt TclBool true]
    return $validationId
}

SetRangeValues [::Excel]Excel, Main

Set range values from a matrix.

SetRangeValues rangeId matrixList
rangeIdIdentifier of the cell range.
matrixListMatrix with table data.

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: GetRangeValues, SetMatrixValues, SetRowValues, SetColumnValues, SetCellValue

proc ::Excel::SetRangeValues {rangeId matrixList} {

    # Set range values from a matrix.
    #
    # rangeId    - Identifier of the cell range.
    # matrixList - Matrix with table data.
    #
    # 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: GetRangeValues SetMatrixValues SetRowValues SetColumnValues SetCellValue

    $rangeId Value2 $matrixList
}

SetRangeVerticalAlignment [::Excel]Excel, Main

Set the vertical alignment of a cell range.

SetRangeVerticalAlignment rangeId align
rangeIdIdentifier of the cell range.
alignValue of enumeration type Enum::XlVAlign.

Returns no value.

See also: SetRangeHorizontalAlignment, SelectRangeByIndex, SelectRangeByString

proc ::Excel::SetRangeVerticalAlignment {rangeId align} {

    # Set the vertical alignment of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # align   - Value of enumeration type [Enum::XlVAlign].
    #
    # Returns no value.
    #
    # See also: SetRangeHorizontalAlignment SelectRangeByIndex SelectRangeByString

    $rangeId VerticalAlignment [Excel GetEnum $align]
}

SetRangeWrapText [::Excel]Excel, Main

Set the text wrapping mode of a cell range.

SetRangeWrapText rangeId ?onOff?
rangeIdIdentifier of the cell range.
onOffIf set to true, set text wrapping on. Otherwise set text wrapping off. Optional, default true.

Returns no value.

See also: GetRangeWrapText, SetRangeHorizontalAlignment, SetRangeTextColor, SelectRangeByIndex

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

    # Set the text wrapping mode of a cell range.
    #
    # rangeId - Identifier of the cell range.
    # onOff   - If set to true, set text wrapping on.
    #           Otherwise set text wrapping off.
    #
    # Returns no value.
    #
    # See also: GetRangeWrapText SetRangeHorizontalAlignment SetRangeTextColor SelectRangeByIndex

    $rangeId WrapText [Cawt TclBool $onOff]
}

SetRowHeight [::Excel]Excel, Main

Set the height of a row.

SetRowHeight worksheetId row ?height?
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
heightA positive value specifies the row's height. A value of zero specifies that the rows's height fits automatically the height of all elements in the row. Optional, default 0.

The height value may be specified in a format acceptable by procedure ::Cawt::ValueToPoints, i.e. centimeters, inches or points.

Returns no value.

See also: SetRowsHeight, SetColumnWidth, ColumnCharToInt

proc ::Excel::SetRowHeight {worksheetId row {height 0}} {

    # Set the height of a row.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # height      - A positive value specifies the row's height.
    #               A value of zero specifies that the rows's height
    #               fits automatically the height of all elements in the row.
    #
    # The height value may be specified in a format acceptable by
    # procedure [::Cawt::ValueToPoints], i.e. centimeters, inches or points.
    #
    # Returns no value.
    #
    # See also: SetRowsHeight SetColumnWidth ColumnCharToInt

    set cell [Excel SelectCellByIndex $worksheetId $row 1]
    set curRow [$cell EntireRow]
    set height [Cawt ValueToPoints $height]
    if { $height == 0 } {
        $curRow -with { Rows } AutoFit
    } else {
        $curRow RowHeight $height
    }
    Cawt Destroy $curRow
    Cawt Destroy $cell
}

SetRowsHeight [::Excel]Excel, Main

Set the height of a range of rows.

SetRowsHeight worksheetId startRow endRow ?height?
worksheetIdIdentifier of the worksheet.
startRowRange start row number. Row numbering starts with 1.
endRowRange end row number. Row numbering starts with 1.
heightA positive value specifies the row's height. A value of zero specifies that the rows's height fits automatically the height of all elements in the row. Optional, default 0.

The height value may be specified in a format acceptable by procedure ::Cawt::ValueToPoints, i.e. centimeters, inches or points.

Returns no value.

See also: SetRowHeight, SetColumnsWidth, ColumnCharToInt

proc ::Excel::SetRowsHeight {worksheetId startRow endRow {height 0}} {

    # Set the height of a range of rows.
    #
    # worksheetId - Identifier of the worksheet.
    # startRow    - Range start row number. Row numbering starts with 1.
    # endRow      - Range end row number. Row numbering starts with 1.
    # height      - A positive value specifies the row's height.
    #               A value of zero specifies that the rows's height
    #               fits automatically the height of all elements in the row.
    #
    # The height value may be specified in a format acceptable by
    # procedure [::Cawt::ValueToPoints], i.e. centimeters, inches or points.
    #
    # Returns no value.
    #
    # See also: SetRowHeight SetColumnsWidth ColumnCharToInt

    for { set r $startRow } { $r <= $endRow } { incr r } {
        Excel SetRowHeight $worksheetId $r $height
    }
}

SetRowValues [::Excel]Excel, Main

Insert row values from a Tcl list.

SetRowValues worksheetId row valList ?startCol? ?numVals?
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
valListList of values to be inserted.
startColColumn number of insertion start. Column numbering starts with 1. Optional, default 1.
numValsIf negative or zero, all list values are inserted. If positive, $numVals columns are filled with the list values (starting at list index 0). Optional, default 0.

Returns no value. If $valList is an empty list, an error is thrown.

See also: GetRowValues, SetColumnValues, SetCellValue, ColumnCharToInt

proc ::Excel::SetRowValues {worksheetId row valList {startCol 1} {numVals 0}} {

    # Insert row values from a Tcl list.
    #
    # worksheetId - Identifier of the worksheet.
    # row         - Row number. Row numbering starts with 1.
    # valList     - List of values to be inserted.
    # startCol    - Column number of insertion start. Column numbering starts with 1.
    # numVals     - If negative or zero, all list values are inserted.
    #               If positive, $numVals columns are filled with the list values
    #               (starting at list index 0).
    #
    # Returns no value. If $valList is an empty list, an error is thrown.
    #
    # See also: GetRowValues SetColumnValues SetCellValue ColumnCharToInt

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

    set cellId [Excel SelectRangeByIndex $worksheetId  $row $startCol $row [expr {$startCol + $len -1}]]
    Excel SetRangeValues $cellId $valList
    Cawt Destroy $cellId
}

SetSeriesAttributes [::Excel]Excel, Main

Set the attributes of a series.

SetSeriesAttributes seriesId ?args?
seriesIdIdentifier of the series.
argsOptions described below.
-linecolor <color>Set the line color.
-linewidth <size>Set the line width.
-markerstyle <XlMarkerStyle>Set the style of the marker. Typical values: xlMarkerStyleNone, xlMarkerStyleSquare.
  • 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 no value.

See also: AddSeriesTrendLine, GetChartNumSeries, GetChartSeries

proc ::Excel::SetSeriesAttributes {seriesId args} {

    # Set the attributes of a series.
    #
    # seriesId - Identifier of the series.
    # args     - Options described below.
    #
    # -linewidth <size>            - Set the line width.
    # -linecolor <color>           - Set the line color.
    # -markerstyle <XlMarkerStyle> - Set the style of the marker.
    #                                Typical values: xlMarkerStyleNone, xlMarkerStyleSquare.
    #
    # * 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 no value.
    #
    # See also: AddSeriesTrendLine GetChartNumSeries GetChartSeries

    foreach { key value } $args {
        if { $value eq "" } {
            error "SetSeriesAttributes: No value specified for key \"$key\""
        }
        switch -exact $key {
            "-linewidth" {
                $seriesId -with { Format Line } Visible [Cawt TclInt true]
                $seriesId -with { Format Line } Weight [Cawt ValueToPoints $value]
            }
            "-linecolor" {
                $seriesId -with { Format Line } Visible [Cawt TclInt true]
                $seriesId -with { Format Line ForeColor } RGB [Cawt GetColor $value]
            }
            "-markerstyle" {
                $seriesId MarkerStyle [Excel GetEnum $value]
            }
            default {
                error "SetSeriesAttributes: Unknown key \"$key\" specified"
            }
        }
    }
}

SetSeriesLineWidth [::Excel]Excel, Main

Set the line width of a series.

SetSeriesLineWidth seriesId width
seriesIdIdentifier of the series.
widthLine width.

Returns no value.

See also: GetChartNumSeries, GetChartSeries, AddSeriesTrendLine

proc ::Excel::SetSeriesLineWidth {seriesId width} {

    # Set the line width of a series.
    #
    # seriesId - Identifier of the series.
    # width    - Line width.
    #
    # Returns no value.
    #
    # See also: GetChartNumSeries GetChartSeries AddSeriesTrendLine

    $seriesId -with { Format Line } Weight [expr {int($width)}]
}

SetTablelistHeader [::Excel]Excel, Main

Insert header values into a tablelist.

SetTablelistHeader tableId headerList
tableIdIdentifier of the tablelist.
headerListList with table header data.

Returns no value.

See also: TablelistToWorksheet, WorksheetToTablelist, SetTablelistValues, GetTablelistHeader

proc ::Excel::SetTablelistHeader {tableId headerList} {

    # Insert header values into a tablelist.
    #
    # tableId    - Identifier of the tablelist.
    # headerList - List with table header data.
    #
    # Returns no value.
    #
    # See also: TablelistToWorksheet WorksheetToTablelist
    # SetTablelistValues GetTablelistHeader

    foreach title $headerList {
        $tableId insertcolumns end 0 $title left
    }
}

SetTablelistValues [::Excel]Excel, Main

Insert matrix values into a tablelist.

SetTablelistValues tableId matrixList
tableIdIdentifier of the tablelist.
matrixListMatrix with table data.

Returns no value.

See also: TablelistToWorksheet, WorksheetToTablelist, SetTablelistHeader, GetTablelistValues

proc ::Excel::SetTablelistValues {tableId matrixList} {

    # Insert matrix values into a tablelist.
    #
    # tableId    - Identifier of the tablelist.
    # matrixList - Matrix with table data.
    #
    # Returns no value.
    #
    # See also: TablelistToWorksheet WorksheetToTablelist
    # SetTablelistHeader GetTablelistValues

    foreach rowList $matrixList {
        $tableId insert end $rowList
    }
}

SetWindowState [::Excel]Excel, Main

Set the window state of an Excel application.

SetWindowState appId ?windowState?
appIdIdentifier of the Excel instance.
windowStateValue of enumeration type Enum::XlWindowState. Typical values are: xlMaximized, xlMinimized, xlNormal. Optional, default xlNormal.

Returns no value.

See also: Open, Visible, ArrangeWindows

proc ::Excel::SetWindowState {appId {windowState xlNormal}} {

    # Set the window state of an Excel application.
    #
    # appId       - Identifier of the Excel instance.
    # windowState - Value of enumeration type [Enum::XlWindowState].
    #               Typical values are: `xlMaximized`, `xlMinimized`, `xlNormal`.
    #
    # Returns no value.
    #
    # See also: Open Visible ArrangeWindows

    $appId -with { Application } WindowState [Excel GetEnum $windowState]
}

SetWorksheetFitToPages [::Excel]Excel, Main

Adjust a worksheet to fit onto given number of pages.

SetWorksheetFitToPages worksheetId ?wide? ?tall?
worksheetIdIdentifier of the worksheet.
wideThe number of pages in horizontal direction. Optional, default 1.
tallThe number of pages in vertical direction. Optional, default 1.

Use zero for parameters $wide or $tall to automatically determine the number of pages. When using the default values for $wide and $tall, the worksheet is adjusted to fit onto exactly one piece of paper.

Returns no value.

See also: SetWorksheetOrientation, SetWorksheetZoom, SetWorksheetPrintOptions, SetWorksheetPaperSize, SetWorksheetMargins, SetWorksheetHeader, SetWorksheetFooter

proc ::Excel::SetWorksheetFitToPages {worksheetId {wide 1} {tall 1}} {

    # Adjust a worksheet to fit onto given number of pages.
    #
    # worksheetId - Identifier of the worksheet.
    # wide        - The number of pages in horizontal direction.
    # tall        - The number of pages in vertical direction.
    #
    # Use zero for parameters $wide or $tall to automatically determine the
    # number of pages.
    # When using the default values for $wide and $tall, the worksheet is adjusted
    # to fit onto exactly one piece of paper.
    #
    # Returns no value.
    #
    # See also: SetWorksheetOrientation SetWorksheetZoom SetWorksheetPrintOptions
    # SetWorksheetPaperSize SetWorksheetMargins
    # SetWorksheetHeader SetWorksheetFooter

    if { $wide < 0 || $tall < 0 } {
        error "SetWorksheetFitToPages: Number of pages must be greater or equal to 0."
    }
    if { $wide == 0 } {
        set wideVar [Cawt TclBool false]
    } else {
        set wideVar [expr int($wide)]
    }
    if { $tall == 0 } {
        set tallVar [Cawt TclBool false]
    } else {
        set tallVar [expr int($tall)]
    }
    set pageSetup [$worksheetId PageSetup]
    $pageSetup Zoom [Cawt TclBool false]
    $pageSetup FitToPagesWide $wideVar
    $pageSetup FitToPagesTall $tallVar
    Cawt Destroy $pageSetup
}

SetWorksheetFooter [::Excel]Excel, Main

Set the texts of the footer of a worksheet.

SetWorksheetFooter worksheetId ?args?
worksheetIdIdentifier of the worksheet.
argsOptions described below.
-center <string>Set the text of the center footer.
-left <string>Set the text of the left footer.
-right <string>Set the text of the right footer.

Returns no value.

See also: SetWorksheetOrientation, SetWorksheetFitToPages, SetWorksheetZoom, SetWorksheetPrintOptions, SetWorksheetPaperSize, SetWorksheetHeader, SetWorksheetFooter

proc ::Excel::SetWorksheetFooter {worksheetId args} {

    # Set the texts of the footer of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # args        - Options described below.
    #
    # -left <string>   - Set the text of the left footer.
    # -center <string> - Set the text of the center footer.
    # -right <string>  - Set the text of the right footer.
    #
    # Returns no value.
    #
    # See also: SetWorksheetOrientation SetWorksheetFitToPages SetWorksheetZoom
    # SetWorksheetPrintOptions SetWorksheetPaperSize
    # SetWorksheetHeader SetWorksheetFooter

    set pageSetup [$worksheetId PageSetup]
    foreach { key value } $args {
        if { $value eq "" } {
            error "SetWorksheetFooter: No value specified for key \"$key\""
        }
        switch -exact $key {
            "-left"   { $pageSetup LeftFooter   $value }
            "-center" { $pageSetup CenterFooter $value }
            "-right"  { $pageSetup RightFooter  $value }
            default   { error "SetWorksheetFooter: Unknown key \"$key\" specified" }
        }
    }
    Cawt Destroy $pageSetup
}

SetWorksheetHeader [::Excel]Excel, Main

Set the texts of the header of a worksheet.

SetWorksheetHeader worksheetId ?args?
worksheetIdIdentifier of the worksheet.
argsOptions described below.
-center <string>Set the text of the center header.
-left <string>Set the text of the left header.
-right <string>Set the text of the right header.

Returns no value.

See also: SetWorksheetOrientation, SetWorksheetFitToPages, SetWorksheetZoom, SetWorksheetPrintOptions, SetWorksheetPaperSize, SetWorksheetHeader, SetWorksheetFooter

proc ::Excel::SetWorksheetHeader {worksheetId args} {

    # Set the texts of the header of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # args        - Options described below.
    #
    # -left <string>   - Set the text of the left header.
    # -center <string> - Set the text of the center header.
    # -right <string>  - Set the text of the right header.
    #
    # Returns no value.
    #
    # See also: SetWorksheetOrientation SetWorksheetFitToPages SetWorksheetZoom
    # SetWorksheetPrintOptions SetWorksheetPaperSize
    # SetWorksheetHeader SetWorksheetFooter

    set pageSetup [$worksheetId PageSetup]
    foreach { key value } $args {
        if { $value eq "" } {
            error "SetWorksheetHeader: No value specified for key \"$key\""
        }
        switch -exact $key {
            "-left"   { $pageSetup LeftHeader   $value }
            "-center" { $pageSetup CenterHeader $value }
            "-right"  { $pageSetup RightHeader  $value }
            default   { error "SetWorksheetHeader: Unknown key \"$key\" specified" }
        }
    }
    Cawt Destroy $pageSetup
}

SetWorksheetMargins [::Excel]Excel, Main

Set the margins of a worksheet.

SetWorksheetMargins worksheetId ?args?
worksheetIdIdentifier of the worksheet.
argsOptions described below.
-bottom <size>Set the size of the bottom margin.
-footer <size>Set the size of the footer margin.
-header <size>Set the size of the header margin.
-left <size>Set the size of the left margin.
-right <size>Set the size of the right margin.
-top <size>Set the size of the top margin.

The margin values may be specified in a format acceptable by procedure ::Cawt::ValueToPoints, i.e. centimeters, inches or points.

Example:

SetWorksheetMargins $worksheetId -top 1.5c -left 2i
sets the top margin to 1.5 centimeters and the left margin to 2 inches.

Returns no value.

See also: SetWorksheetOrientation, SetWorksheetFitToPages, SetWorksheetZoom, SetWorksheetPrintOptions, SetWorksheetPaperSize, SetWorksheetHeader, SetWorksheetFooter

proc ::Excel::SetWorksheetMargins {worksheetId args} {

    # Set the margins of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # args        - Options described below.
    #
    # -top <size>    - Set the size of the top margin.
    # -bottom <size> - Set the size of the bottom margin.
    # -left <size>   - Set the size of the left margin.
    # -right <size>  - Set the size of the right margin.
    # -footer <size> - Set the size of the footer margin.
    # -header <size> - Set the size of the header margin.
    #
    # The margin values may be specified in a format acceptable by
    # procedure [::Cawt::ValueToPoints], i.e. centimeters, inches or points.
    #
    # Example:
    #     SetWorksheetMargins $worksheetId -top 1.5c -left 2i
    #     sets the top margin to 1.5 centimeters and the left margin to 2 inches.
    #
    # Returns no value.
    #
    # See also: SetWorksheetOrientation SetWorksheetFitToPages SetWorksheetZoom
    # SetWorksheetPrintOptions SetWorksheetPaperSize
    # SetWorksheetHeader SetWorksheetFooter

    set pageSetup [$worksheetId PageSetup]
    foreach { key value } $args {
        if { $value eq "" } {
            error "SetWorksheetMargins: No value specified for key \"$key\""
        }
        set pointValue [Cawt ValueToPoints $value]
        switch -exact $key {
            "-top"    { $pageSetup TopMargin    $pointValue }
            "-bottom" { $pageSetup BottomMargin $pointValue }
            "-left"   { $pageSetup LeftMargin   $pointValue }
            "-right"  { $pageSetup RightMargin  $pointValue }
            "-header" { $pageSetup HeaderMargin $pointValue }
            "-footer" { $pageSetup FooterMargin $pointValue }
            default   { error "SetWorksheetMargins: Unknown key \"$key\" specified" }
        }
    }
    Cawt Destroy $pageSetup
}

SetWorksheetName [::Excel]Excel, Main

Set the name of a worksheet.

SetWorksheetName worksheetId name
worksheetIdIdentifier of the worksheet.
nameName of the worksheet.

Returns no value.

See also: GetWorksheetName, AddWorksheet

proc ::Excel::SetWorksheetName {worksheetId name} {

    # Set the name of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # name        - Name of the worksheet.
    #
    # Returns no value.
    #
    # See also: GetWorksheetName AddWorksheet

    $worksheetId Name $name
}

SetWorksheetOrientation [::Excel]Excel, Main

Set the orientation of a worksheet.

SetWorksheetOrientation worksheetId orientation
worksheetIdIdentifier of the worksheet.
orientationValue of enumeration type Enum::XlPageOrientation. Possible values: xlLandscape or xlPortrait.

Returns no value.

See also: SetWorksheetFitToPages, SetWorksheetZoom, SetWorksheetPrintOptions, SetWorksheetPaperSize, SetWorksheetMargins, SetWorksheetHeader, SetWorksheetFooter

proc ::Excel::SetWorksheetOrientation {worksheetId orientation} {

    # Set the orientation of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # orientation - Value of enumeration type [Enum::XlPageOrientation].
    #               Possible values: `xlLandscape` or `xlPortrait`.
    #
    # Returns no value.
    #
    # See also: SetWorksheetFitToPages SetWorksheetZoom SetWorksheetPrintOptions
    # SetWorksheetPaperSize SetWorksheetMargins
    # SetWorksheetHeader SetWorksheetFooter

    $worksheetId -with { PageSetup } Orientation [Excel GetEnum $orientation]
}

SetWorksheetPaperSize [::Excel]Excel, Main

Set the paper size of a worksheet.

SetWorksheetPaperSize worksheetId paperSize
worksheetIdIdentifier of the worksheet.
paperSizeValue of enumeration type Enum::XlPaperSize.

Returns no value.

See also: SetWorksheetOrientation, SetWorksheetFitToPages, SetWorksheetZoom, SetWorksheetPrintOptions, SetWorksheetMargins, SetWorksheetHeader, SetWorksheetFooter

proc ::Excel::SetWorksheetPaperSize {worksheetId paperSize} {

    # Set the paper size of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # paperSize   - Value of enumeration type [Enum::XlPaperSize].
    #
    # Returns no value.
    #
    # See also: SetWorksheetOrientation SetWorksheetFitToPages SetWorksheetZoom
    # SetWorksheetPrintOptions SetWorksheetMargins
    # SetWorksheetHeader SetWorksheetFooter

    $worksheetId -with { PageSetup } PaperSize [Excel GetEnum $paperSize]
}

SetWorksheetPrintOptions [::Excel]Excel, Main

Set printing options of a worksheet.

SetWorksheetPrintOptions worksheetId ?args?
worksheetIdIdentifier of the worksheet.
argsOptions described below.
-bw <bool>Set printing in black-white only.
-comments <enum>Set printing of comments. Enumeration of type Enum::XlPrintLocation. Typical values: xlPrintInPlace, xlPrintNoComments.
-draft <bool>Set printing quality to draft mode.
-errors <enum>Set printing of errors. Enumeration of type Enum::XlPrintErrors. Typical values: xlPrintErrorsDisplayed, xlPrintErrorsBlank.
-gridlines <bool>Set the printing of grid lines.
-headings <bool>Set printing of headings.

Returns no value.

See also: SetWorksheetOrientation, SetWorksheetFitToPages, SetWorksheetZoom, SetWorksheetPaperSize, SetWorksheetMargins, SetWorksheetHeader, SetWorksheetFooter

proc ::Excel::SetWorksheetPrintOptions {worksheetId args} {

    # Set printing options of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # args        - Options described below.
    #
    # -gridlines <bool> - Set the printing of grid lines.
    # -bw <bool>        - Set printing in black-white only.
    # -draft <bool>     - Set printing quality to draft mode.
    # -headings <bool>  - Set printing of headings.
    # -comments <enum>  - Set printing of comments. Enumeration of type [Enum::XlPrintLocation].
    #                     Typical values: `xlPrintInPlace`, `xlPrintNoComments`.
    # -errors <enum>    - Set printing of errors. Enumeration of type [Enum::XlPrintErrors].
    #                     Typical values: `xlPrintErrorsDisplayed`, `xlPrintErrorsBlank`.
    #
    # Returns no value.
    #
    # See also: SetWorksheetOrientation SetWorksheetFitToPages SetWorksheetZoom
    # SetWorksheetPaperSize SetWorksheetMargins
    # SetWorksheetHeader SetWorksheetFooter

    set pageSetup [$worksheetId PageSetup]
    foreach { key value } $args {
        if { $value eq "" } {
            error "SetWorksheetPrintOptions: No value specified for key \"$key\""
        }
        switch -exact $key {
            "-gridlines" { $pageSetup PrintGridlines [Cawt TclBool $value] }
            "-bw"        { $pageSetup BlackAndWhite  [Cawt TclBool $value] }
            "-draft"     { $pageSetup Draft          [Cawt TclBool $value] }
            "-headings"  { $pageSetup PrintHeadings  [Cawt TclBool $value] }
            "-comments"  { $pageSetup PrintComments  [Excel GetEnum $value] }
            "-errors"    { $pageSetup PrintErrors    [Excel GetEnum $value] }
            default      { error "SetWorksheetPrintOptions: Unknown key \"$key\" specified" }
        }
    }
    Cawt Destroy $pageSetup
}

SetWorksheetTabColor [::Excel]Excel, Main

Set the color of the tab of a worksheet.

SetWorksheetTabColor worksheetId ?args?
worksheetIdIdentifier of the worksheet.
argsTab 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, GetWorksheetIdByIndex

proc ::Excel::SetWorksheetTabColor {worksheetId args} {

    # Set the color of the tab of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # args        - Tab 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 GetWorksheetIdByIndex

    set color [Cawt GetColor {*}$args]
    $worksheetId -with { Tab } Color $color
}

SetWorksheetZoom [::Excel]Excel, Main

Set the zoom factor for printing of a worksheet.

SetWorksheetZoom worksheetId ?zoom?
worksheetIdIdentifier of the worksheet.
zoomThe zoom factor in percent as an integer value. Optional, default 100.

Valid zoom values are in the range [10, 400].

Returns no value.

See also: SetWorksheetOrientation, SetWorksheetFitToPages, SetWorksheetPrintOptions, SetWorksheetPaperSize, SetWorksheetMargins, SetWorksheetHeader, SetWorksheetFooter

proc ::Excel::SetWorksheetZoom {worksheetId {zoom 100}} {

    # Set the zoom factor for printing of a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    # zoom        - The zoom factor in percent as an integer value.
    #
    # Valid zoom values are in the range \[10, 400\].
    #
    # Returns no value.
    #
    # See also: SetWorksheetOrientation SetWorksheetFitToPages SetWorksheetPrintOptions
    # SetWorksheetPaperSize SetWorksheetMargins
    # SetWorksheetHeader SetWorksheetFooter

    $worksheetId -with { PageSetup } Zoom [expr int($zoom)]
}

ShowAlerts [::Excel]Excel, Main

Toggle the display of Excel application alerts.

ShowAlerts appId onOff
appIdThe application identifier.
onOffSwitch the alerts on or off.

Returns no value.

proc ::Excel::ShowAlerts {appId onOff} {

    # Toggle the display of Excel application alerts.
    #
    # appId - The application identifier.
    # onOff - Switch the alerts on or off.
    #
    # Returns no value.

    if { $onOff } {
        set alertLevel [expr 1]
    } else {
        set alertLevel [expr 0]
    }
    $appId DisplayAlerts $alertLevel
}

ShowCellByIndex [::Excel]Excel, Main

Show a cell identified by its row/column index.

ShowCellByIndex worksheetId row col
worksheetIdIdentifier of the worksheet.
rowRow number. Row numbering starts with 1.
colColumn number. Column numbering starts with 1.

Set the scrolling, so that the cell is shown at the upper left corner.

See also: SelectCellByIndex

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

    # Show a cell 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.
    #
    # Set the scrolling, so that the cell is shown at the upper left corner.
    #
    # See also: SelectCellByIndex

    if { $row <= 0 } {
        error "Row number $row is invalid."
    }
    if { $col <= 0 } {
        error "Column number $col is invalid."
    }
    $worksheetId Activate
    set appId [Office GetApplicationId $worksheetId]
    set actWin [$appId ActiveWindow]
    $actWin ScrollColumn $col
    $actWin ScrollRow $row
    Cawt Destroy $actWin
    Cawt Destroy $appId
}

ShowWorksheet [::Excel]Excel, Main

Show a worksheet.

ShowWorksheet worksheetId
worksheetIdIdentifier of the worksheet.

See also: GetNumWorksheets, GetWorksheetIdByName, AddWorksheet

proc ::Excel::ShowWorksheet {worksheetId} {

    # Show a worksheet.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # See also: GetNumWorksheets GetWorksheetIdByName AddWorksheet

    $worksheetId Activate
}

TablelistToWorksheet [::Excel]Excel, Main

Insert the values of a tablelist into a worksheet.

TablelistToWorksheet tableId worksheetId ?useHeader? ?startRow?
tableIdIdentifier of the tablelist.
worksheetIdIdentifier of the worksheet.
useHeaderIf set to true, insert the header of the tablelist as first row. Otherwise only transfer the tablelist data. Optional, default true.
startRowRow number of insertion start. Row numbering starts with 1. Optional, default 1.

Note: The contents of hidden columns are transfered to Excel and are hidden there, too. If the tablelist contains a column with automatic line numbering, this column is transfered to Excel, too. If this behaviour is not wished, use the DeleteColumn procedure to delete the corresponding column in Excel.

Returns no value.

See also: WorksheetToTablelist, SetMatrixValues, WikitFileToWorksheet, MediaWikiFileToWorksheet, MatlabFileToWorksheet, RawImageFileToWorksheet, WordTableToWorksheet

proc ::Excel::TablelistToWorksheet {tableId worksheetId {useHeader true} {startRow 1}} {

    # Insert the values of a tablelist into a worksheet.
    #
    # tableId     - Identifier of the tablelist.
    # worksheetId - Identifier of the worksheet.
    # useHeader   - If set to true, insert the header of the tablelist as first row.
    #               Otherwise only transfer the tablelist data.
    # startRow    - Row number of insertion start. Row numbering starts with 1.
    #
    # **Note:**
    # The contents of hidden columns are transfered to Excel and are hidden there, too.
    # If the tablelist contains a column with automatic line numbering, this column is
    # transfered to Excel, too. If this behaviour is not wished, use the [DeleteColumn]
    # procedure to delete the corresponding column in Excel.
    #
    # Returns no value.
    #
    # See also: WorksheetToTablelist SetMatrixValues
    # WikitFileToWorksheet MediaWikiFileToWorksheet MatlabFileToWorksheet
    # RawImageFileToWorksheet WordTableToWorksheet

    set curRow $startRow
    set numCols [$tableId columncount]
    if { $useHeader } {
        set headerList [list]
        for { set col 0 } { $col < $numCols } { incr col } {
            lappend headerList [$tableId columncget $col -title]
        }
        Excel SetHeaderRow $worksheetId $headerList $curRow
        incr curRow
    }
    set matrixList [$tableId get 0 end]
    Excel SetMatrixValues $worksheetId $matrixList $curRow 1
    for { set col 0 } { $col < $numCols } { incr col } {
        if { [$tableId columncget $col -hide] } {
            Excel HideColumn $worksheetId [expr {$col + 1}]
        }
    }
}

ToggleAutoFilter [::Excel]Excel, Main

Toggle the AutoFilter switch of a cell range.

ToggleAutoFilter rangeId
rangeIdIdentifier of the cell range.

Returns no value.

See also: SelectRangeByIndex, SelectRangeByString

proc ::Excel::ToggleAutoFilter {rangeId} {

    # Toggle the AutoFilter switch of a cell range.
    #
    # rangeId - Identifier of the cell range.
    #
    # Returns no value.
    #
    # See also: SelectRangeByIndex SelectRangeByString

    $rangeId AutoFilter
}

UnhideWorksheet [::Excel]Excel, Main

Unhide a worksheet, if it is hidden.

UnhideWorksheet worksheetId
worksheetIdIdentifier of the worksheet.

If the worksheet is hidden, it is made visible.

Returns no value.

See also: SetWorksheetTabColor, IsWorksheetVisible

proc ::Excel::UnhideWorksheet {worksheetId} {

    # Unhide a worksheet, if it is hidden.
    #
    # worksheetId - Identifier of the worksheet.
    #
    # If the worksheet is hidden, it is made visible.
    #
    # Returns no value.
    #
    # See also: SetWorksheetTabColor IsWorksheetVisible

    if { ! [Excel IsWorksheetVisible $worksheetId] } {
        if { [$worksheetId -with { Parent } ProtectStructure] } {
            error "Unable to unhide because the Workbook's structure is protected."
        } else {
            $worksheetId Visible $Excel::xlSheetVisible
        }
    }
}

UseImgTransparency [::Excel]Excel, Main

Toggle usage of transparency channel of an image.

UseImgTransparency onOff
onOffNot documented.

Only valid for ImgToWorksheet and WorksheetToImg procedures.

See also: ImgToWorksheet, WorksheetToImg

proc ::Excel::UseImgTransparency {onOff} {

    # Toggle usage of transparency channel of an image.
    #
    # Only valid for [ImgToWorksheet] and [WorksheetToImg] procedures.
    #
    # See also: ImgToWorksheet WorksheetToImg

    variable sUseTransparency

    set sUseTransparency $onOff
}

Visible [::Excel]Excel, Main

Set or query the visibility of an Excel application window.

Visible appId ?visible?
appIdIdentifier of the Excel instance.
visibleIf set to true, show the application window. If set to false, hide the application window. If empty, return the visbility status. Optional, default "".

If parameter $visible is not set or the empty string, the visibility status is returned as a boolean value. Otherwise no return value.

See also: Open, OpenNew, SetWindowState, ArrangeWindows

proc ::Excel::Visible {appId {visible {}}} {

    # Set or query the visibility of an Excel application window.
    #
    # appId   - Identifier of the Excel instance.
    # visible - If set to true, show the application window.
    #           If set to false, hide the application window.
    #           If empty, return the visbility status.
    #
    # If parameter $visible is not set or the empty string, the visibility status
    # is returned as a boolean value.
    # Otherwise no return value.
    #
    # See also: Open OpenNew SetWindowState ArrangeWindows

    if { $visible eq "" } {
        return [$appId Visible]
    }
    $appId Visible [Cawt TclInt $visible]
}

WikitFileToExcelFile [::Excel]Excel, Main

Convert a Wikit table file to an Excel file.

WikitFileToExcelFile wikiFileName excelFileName ?useHeader? ?quitExcel?
wikiFileNameName of the Wikit input file.
excelFileNameName of the Excel output file.
useHeaderIf set to true, use header information from the Wikit file to generate an Excel header (see SetHeaderRow). Otherwise only transfer the table data. Optional, default true.
quitExcelIf set to true, quit the Excel instance after generation of output file. Otherwise leave the Excel instance open after generation of output file. Optional, default true.

The table data from the Wikit file will be inserted into a worksheet named "Wikit".

Returns the Excel application identifier, if $quitExcel is false. Otherwise no return value.

See also: WikitFileToWorksheet, ExcelFileToWikitFile, ReadWikitFile, MediaWikiFileToExcelFile

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

    # Convert a Wikit table file to an Excel file.
    #
    # wikiFileName  - Name of the Wikit input file.
    # excelFileName - Name of the Excel output file.
    # useHeader     - If set to true, use header information from the Wikit 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 Wikit file will be inserted into a worksheet named "Wikit".
    #
    # Returns the Excel application identifier, if $quitExcel is false.
    # Otherwise no return value.
    #
    # See also: WikitFileToWorksheet ExcelFileToWikitFile
    # ReadWikitFile MediaWikiFileToExcelFile

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

WikitFileToWorksheet [::Excel]Excel, Main

Insert the values of a Wikit table file into a worksheet.

WikitFileToWorksheet wikiFileName worksheetId ?useHeader?
wikiFileNameName of the Wikit file.
worksheetIdIdentifier of the worksheet.
useHeaderIf set to true, insert the header of the Wikit table as first row. Otherwise only transfer the table data. Optional, default true.

The insertion starts at row and column 1. Values contained in the worksheet cells are overwritten.

Returns no value.

See also: WorksheetToWikitFile, SetMatrixValues, MediaWikiFileToWorksheet, WordTableToWorksheet, MatlabFileToWorksheet, RawImageFileToWorksheet, TablelistToWorksheet

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

    # Insert the values of a Wikit table file into a worksheet.
    #
    # wikiFileName - Name of the Wikit file.
    # worksheetId  - Identifier of the worksheet.
    # useHeader    - If set to true, insert the header of the Wikit 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: WorksheetToWikitFile SetMatrixValues
    # MediaWikiFileToWorksheet WordTableToWorksheet MatlabFileToWorksheet
    # RawImageFileToWorksheet TablelistToWorksheet

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

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

WordTableToWorksheet [::Excel]Excel, Main

Insert the values of a Word table into a worksheet.

WordTableToWorksheet tableId worksheetId ?useHeader?
tableIdIdentifier of the Word table.
worksheetIdIdentifier of the worksheet.
useHeaderIf set to true, insert the header of the Word table as first row. Otherwise transfer the table data only. Optional, default true.

Returns no value.

See also: WorksheetToWordTable, SetMatrixValues, WikitFileToWorksheet, MediaWikiFileToWorksheet, MatlabFileToWorksheet, RawImageFileToWorksheet, TablelistToWorksheet

proc ::Excel::WordTableToWorksheet {tableId worksheetId {useHeader true}} {

    # Insert the values of a Word table into a worksheet.
    #
    # tableId     - Identifier of the Word table.
    # worksheetId - Identifier of the worksheet.
    # useHeader   - If set to true, insert the header of the Word table as first row.
    #               Otherwise transfer the table data only.
    #
    # Returns no value.
    #
    # See also: WorksheetToWordTable SetMatrixValues
    # WikitFileToWorksheet MediaWikiFileToWorksheet MatlabFileToWorksheet
    # RawImageFileToWorksheet TablelistToWorksheet

    set numCols [Word GetNumColumns $tableId]
    if { $useHeader } {
        for { set col 1 } { $col <= $numCols } { incr col } {
            lappend headerList [Word GetCellValue $tableId 1 $col]
        }
        Excel SetHeaderRow $worksheetId $headerList
    }
    set numRows [Word GetNumRows $tableId]
    incr numRows -1
    set startWordRow 2
    if { $useHeader } {
        set startExcelRow 2
    } else {
        set startExcelRow 1
    }
    set tableList [Word GetMatrixValues $tableId  $startWordRow 1 [expr {$startWordRow + $numRows-1}] $numCols]
    Excel SetMatrixValues $worksheetId $tableList $startExcelRow 1
}

WorksheetToClipboard [::Excel]Excel, Main

Copy worksheet data into the clipboard.

WorksheetToClipboard worksheetId row1 col1 row2 col2 ?sepChar?
worksheetIdIdentifier of the worksheet.
row1Row number of upper-left corner of the copy range.
col1Column number of upper-left corner of the copy range.
row2Row number of lower-right corner of the copy range.
col2Column number of lower-right corner of the copy range.
sepCharThe separation character of the clipboard matrix data. Optional, default ;.

The clipboard data will be in CSV format with $sepChar as separation character.

Returns no value.

See also: ClipboardToWorksheet, MatrixToClipboard

proc ::Excel::WorksheetToClipboard {worksheetId row1 col1 row2 col2 {sepChar {;}}} {

    # Copy worksheet data into the clipboard.
    #
    # worksheetId - Identifier of the worksheet.
    # row1        - Row number of upper-left corner of the copy range.
    # col1        - Column number of upper-left corner of the copy range.
    # row2        - Row number of lower-right corner of the copy range.
    # col2        - Column number of lower-right corner of the copy range.
    # sepChar     - The separation character of the clipboard matrix data.
    #
    # The clipboard data will be in `CSV` format with $sepChar as separation character.
    #
    # Returns no value.
    #
    # See also: ClipboardToWorksheet MatrixToClipboard

    set matrixList [Excel GetMatrixValues $worksheetId $row1 $col1 $row2 $col2]
    Excel MatrixToClipboard $matrixList $sepChar
}

WorksheetToHtmlFile [::Excel]Excel, Main

Write the values of a worksheet into a HTML table file.

WorksheetToHtmlFile worksheetId htmlFileName ?useTarget?
worksheetIdIdentifier of the worksheet.
htmlFileNameName of the HTML file.
useTargetIf set to true, generate a target attribute for hyperlinks. Otherwise, no target attribute for hyperlinks, i.e. link opens in same tab. Optional, default true.

The following attributes are exported to the HTML file:

  • Font: Name, size, style (bold, italic, underline).
  • Column span across a row.
  • Text and background color.
  • Horizontal and vertical text alignment.
  • Hyperlinks.

Returns no value.

See also: GetMatrixValues, ExcelFileToHtmlFile, WorksheetToMediaWikiFile, WorksheetToWikitFile, WorksheetToWordTable, WorksheetToMatlabFile, WorksheetToRawImageFile, WorksheetToTablelist

proc ::Excel::WorksheetToHtmlFile {worksheetId htmlFileName {useTarget true}} {

    # Write the values of a worksheet into a HTML table file.
    #
    # worksheetId  - Identifier of the worksheet.
    # htmlFileName - Name of the HTML file.
    # useTarget    - If set to true, generate a target attribute for hyperlinks.
    #                Otherwise, no target attribute for hyperlinks, i.e. link opens in same tab.
    #
    # The following attributes are exported to the HTML file:
    # * Font: Name, size, style (bold, italic, underline).
    # * Column span across a row.
    # * Text and background color.
    # * Horizontal and vertical text alignment.
    # * Hyperlinks.
    #
    # Returns no value.
    #
    # See also: GetMatrixValues ExcelFileToHtmlFile
    # WorksheetToMediaWikiFile WorksheetToWikitFile WorksheetToWordTable
    # WorksheetToMatlabFile WorksheetToRawImageFile WorksheetToTablelist

    set numRows [Excel GetLastUsedRow $worksheetId]
    set numCols [Excel GetLastUsedColumn $worksheetId]
    set startRow 1
    set catchVal [catch {open $htmlFileName w} fp]
    if { $catchVal != 0 } {
        error "Could not open file \"$htmlFileName\" for writing."
    }

    Excel::_WriteTableBegin $fp
    for { set row $startRow } { $row <= $numRows } { incr row } {
        set spanList  [Excel::_GetRowSpan            $worksheetId $row $numCols]
        set bgColors  [Excel::_GetRowBackgroundColor $worksheetId $row $numCols]
        Excel::_WriteTableRow $worksheetId $row $numCols $fp $bgColors $spanList $useTarget
    }
    Excel::_WriteTableEnd $fp
    close $fp
}

WorksheetToImg [::Excel]Excel, Main

Put worksheet background colors into a photo image.

WorksheetToImg worksheetId ?startRow? ?startCol? ?endRow? ?endCol?
worksheetIdIdentifier of the worksheet.
startRowRow number of the top-left corner of the image. Optional, default 1.
startColColumn number of the top-left corner of the image. Optional, default 1.
endRowRow number of the bottom-right corner of the image. Optional, default end.
endColColumn number of the bottom-right corner of the image. Optional, default end.

Note: Row and column numbering starts with 1. Instead of using a number for $endRow or $endCol, it is possible to use the special word end to use the last used row or column.

Returns the photo image identifier.

See also: ImgToWorksheet, UseImgTransparency, ::Cawt::ImgToClipboard, RawImageFileToWorksheet, GetLastUsedRow, GetLastUsedColumn

proc ::Excel::WorksheetToImg {worksheetId {startRow 1} {startCol 1} {endRow end} {endCol end}} {

    # Put worksheet background colors into a photo image.
    #
    # worksheetId - Identifier of the worksheet.
    # startRow    - Row number of the top-left corner of the image.
    # startCol    - Column number of the top-left corner of the image.
    # endRow      - Row number of the bottom-right corner of the image.
    # endCol      - Column number of the bottom-right corner of the image.
    #
    # **Note:**
    # Row and column numbering starts with 1.
    # Instead of using a number for $endRow or $endCol, it is possible to use
    # the special word `end` to use the last used row or column.
    #
    # Returns the photo image identifier.
    #
    # See also: ImgToWorksheet UseImgTransparency
    # ::Cawt::ImgToClipboard RawImageFileToWorksheet
    # GetLastUsedRow GetLastUsedColumn

    variable sUseTransparency

    if { $endRow eq "end" } {
        set endRow [Excel GetLastUsedRow $worksheetId]
    }
    if { $endCol eq "end" } {
        set endCol [Excel GetLastUsedColumn $worksheetId]
    }

    set w [expr { $endCol - $startCol + 1 }]
    set h [expr { $endRow - $startRow + 1 }]

    set phImg [image create photo -width $w -height $h]

    set curRow $startRow
    for { set y 0 } { $y < $h } { incr y } {
        set curCol $startCol
        for { set x 0 } { $x < $w } { incr x } {
            set rangeId [Excel SelectCellByIndex $worksheetId $curRow $curCol]
            if { $sUseTransparency } {
                if { [$rangeId -with { Interior } Pattern] == $Excel::xlNone } {
                    $phImg transparency set $x $y true
                } else {
                    set rgb [Excel GetRangeFillColor $rangeId]
                    set colorVal [format "#%02X%02X%02X" [lindex $rgb 0] [lindex $rgb 1] [lindex $rgb 2]]
                    $phImg put $colorVal -to $x $y
                }
            } else {
                set rgb [Excel GetRangeFillColor $rangeId]
                set colorVal [format "#%02X%02X%02X" [lindex $rgb 0] [lindex $rgb 1] [lindex $rgb 2]]
                $phImg put $colorVal -to $x $y
            }
            incr curCol
            Cawt Destroy $rangeId
        }
        incr curRow
    }
    return $phImg
}

WorksheetToMatlabFile [::Excel]Excel, Main

Insert the values of a worksheet into a Matlab file.

WorksheetToMatlabFile worksheetId matFileName ?useHeader?
worksheetIdIdentifier of the worksheet.
matFileNameName of the Matlab file.
useHeaderIf set to true, interpret the first row of the worksheet as header and thus do not transfer this row into the Matlab file. Otherwise all worksheet cells are interpreted as data. Optional, default true.

Note: Only Matlab Level 4 files are currently supported.

Returns no value.

See also: MatlabFileToWorksheet, GetMatrixValues, WorksheetToWikitFile, WorksheetToMediaWikiFile, WorksheetToRawImageFile, WorksheetToTablelist, WorksheetToWordTable

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

    # Insert the values of a worksheet into a Matlab file.
    #
    # worksheetId - Identifier of the worksheet.
    # matFileName - Name of the Matlab file.
    # useHeader   - If set to true, interpret the first row of the worksheet as header and
    #               thus do not transfer this row into the Matlab file.
    #               Otherwise all worksheet cells are interpreted as data.
    #
    # **Note:** Only Matlab Level 4 files are currently supported.
    #
    # Returns no value.
    #
    # See also: MatlabFileToWorksheet GetMatrixValues
    # WorksheetToWikitFile WorksheetToMediaWikiFile WorksheetToRawImageFile
    # WorksheetToTablelist WorksheetToWordTable

    set numRows [Excel GetLastUsedRow $worksheetId]
    set numCols [Excel GetLastUsedColumn $worksheetId]
    set startRow 1
    if { $useHeader } {
        incr startRow
    }
    set excelList [Excel GetMatrixValues $worksheetId $startRow 1 $numRows $numCols]
    Excel WriteMatlabFile $excelList $matFileName
}

WorksheetToMediaWikiFile [::Excel]Excel, Main

Insert the values of a worksheet into a MediaWiki table file.

WorksheetToMediaWikiFile worksheetId wikiFileName ?useHeader?
worksheetIdIdentifier of the worksheet.
wikiFileNameName of the MediaWiki file.
useHeaderIf 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. Optional, default true.

Returns no value.

See also: MediaWikiFileToWorksheet, GetMatrixValues, WorksheetToWikitFile, WorksheetToWordTable, WorksheetToMatlabFile, WorksheetToRawImageFile, WorksheetToTablelist

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

    # Insert the values of a worksheet into a MediaWiki table file.
    #
    # worksheetId  - Identifier of the worksheet.
    # wikiFileName - Name of the MediaWiki file.
    # 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.
    #
    # Returns no value.
    #
    # See also: MediaWikiFileToWorksheet GetMatrixValues
    # WorksheetToWikitFile WorksheetToWordTable WorksheetToMatlabFile
    # WorksheetToRawImageFile WorksheetToTablelist

    set numRows [Excel GetLastUsedRow $worksheetId]
    set numCols [Excel GetLastUsedColumn $worksheetId]
    set startRow 1
    set catchVal [catch {open $wikiFileName w} fp]
    if { $catchVal != 0 } {
        error "Could not open file \"$wikiFileName\" for writing."
    }
    if { $useHeader } {
        set headerList [Excel GetMatrixValues $worksheetId $startRow 1 $startRow $numCols]
        set worksheetName [Excel GetWorksheetName $worksheetId]
        Excel::_WriteMediaWikiHeader $fp [lindex $headerList 0] $worksheetName
        incr startRow
    }
    set matrixList [Excel GetMatrixValues $worksheetId $startRow 1 $numRows $numCols]
    Excel::_WriteMediaWikiData $fp $matrixList
    close $fp
}

WorksheetToRawImageFile [::Excel]Excel, Main

Insert the values of a worksheet into a raw photo image file.

WorksheetToRawImageFile worksheetId rawFileName ?useHeader? ?pixelType?
worksheetIdIdentifier of the worksheet.
rawFileNameFile name of the image.
useHeaderIf set to true, interpret the first row of the worksheet as header and thus do not transfer this row into the image. Otherwise all worksheet cells are interpreted as data. Optional, default true.
pixelTypePixel type: byte, short, float. Optional, default float.

The image generated is a 1-channel floating point photo image. It can be read and manipulated with the Img extension. It is not a "raw" image as used with digital cameras, but just "raw" image data.

Returns no value.

See also: RawImageFileToWorksheet, GetMatrixValues, WorksheetToWikitFile, WorksheetToMediaWikiFile, WorksheetToMatlabFile, WorksheetToTablelist, WorksheetToWordTable

proc ::Excel::WorksheetToRawImageFile {worksheetId rawFileName {useHeader true} {pixelType float}} {

    # Insert the values of a worksheet into a raw photo image file.
    #
    # worksheetId - Identifier of the worksheet.
    # rawFileName - File name of the image.
    # useHeader   - If set to true, interpret the first row of the worksheet as header and
    #               thus do not transfer this row into the image.
    #               Otherwise all worksheet cells are interpreted as data.
    # pixelType   - Pixel type: `byte`, `short`, `float`.
    #
    # The image generated is a 1-channel floating point photo image. It can be
    # read and manipulated with the Img extension. It is not a "raw" image as used
    # with digital cameras, but just "raw" image data.
    #
    # Returns no value.
    #
    # See also: RawImageFileToWorksheet GetMatrixValues
    # WorksheetToWikitFile WorksheetToMediaWikiFile WorksheetToMatlabFile
    # WorksheetToTablelist WorksheetToWordTable

    set numRows [Excel GetLastUsedRow $worksheetId]
    set numCols [Excel GetLastUsedColumn $worksheetId]
    set startRow 1
    if { $useHeader } {
        incr startRow
    }
    set excelList [Excel GetMatrixValues $worksheetId $startRow 1 $numRows $numCols]
    Excel WriteRawImageFile $excelList $rawFileName $pixelType
}

WorksheetToTablelist [::Excel]Excel, Main

Insert the values of a worksheet into a tablelist.

WorksheetToTablelist worksheetId tableId ?useHeader?
worksheetIdIdentifier of the worksheet.
tableIdIdentifier of the tablelist.
useHeaderIf set to true, use the first row of the worksheet as the header of the tablelist. Otherwise do not generate a tablelist header. All worksheet cells are interpreted as data. Optional, default true.

Note: The contents of hidden columns are transfered from Excel to the tablelist and are hidden there, too.

Returns no value.

See also: TablelistToWorksheet, GetMatrixValues, WorksheetToWikitFile, WorksheetToMediaWikiFile, WorksheetToMatlabFile, WorksheetToRawImageFile, WorksheetToWordTable

proc ::Excel::WorksheetToTablelist {worksheetId tableId {useHeader true}} {

    # Insert the values of a worksheet into a tablelist.
    #
    # worksheetId - Identifier of the worksheet.
    # tableId     - Identifier of the tablelist.
    # useHeader   - If set to true, use the first row of the worksheet as the header
    #               of the tablelist.
    #               Otherwise do not generate a tablelist header. All worksheet
    #               cells are interpreted as data.
    #
    # **Note:**
    # The contents of hidden columns are transfered from Excel to the tablelist
    # and are hidden there, too.
    #
    # Returns no value.
    #
    # See also: TablelistToWorksheet GetMatrixValues
    # WorksheetToWikitFile WorksheetToMediaWikiFile WorksheetToMatlabFile
    # WorksheetToRawImageFile WorksheetToWordTable

    set numRows [Excel GetLastUsedRow $worksheetId]
    set numCols [Excel GetLastUsedColumn $worksheetId]
    set startRow 1
    if { $useHeader } {
        set headerList [Excel GetRowValues $worksheetId 1 1 $numCols]
        foreach title $headerList {
            $tableId insertcolumns end 0 $title left
        }
        incr startRow
    } else {
        for { set col 1 } { $col <= $numCols } { incr col } {
            $tableId insertcolumns end 0 "NN" left
        }
    }
    set excelList [Excel GetMatrixValues $worksheetId $startRow 1 $numRows $numCols]
    foreach rowList $excelList {
        $tableId insert end $rowList
    }
    foreach col [Excel GetHiddenColumns $worksheetId] {
        $tableId columnconfigure [expr {$col - 1}] -hide true
    }
}

WorksheetToWikitFile [::Excel]Excel, Main

Insert the values of a worksheet into a Wikit table file.

WorksheetToWikitFile worksheetId wikiFileName ?useHeader?
worksheetIdIdentifier of the worksheet.
wikiFileNameName of the Wikit file.
useHeaderIf 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. Optional, default true.

Returns no value.

See also: WikitFileToWorksheet, GetMatrixValues, WorksheetToMediaWikiFile, WorksheetToWordTable, WorksheetToMatlabFile, WorksheetToRawImageFile, WorksheetToTablelist

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

    # Insert the values of a worksheet into a Wikit table file.
    #
    # worksheetId  - Identifier of the worksheet.
    # wikiFileName - Name of the Wikit file.
    # 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.
    #
    # Returns no value.
    #
    # See also: WikitFileToWorksheet GetMatrixValues
    # WorksheetToMediaWikiFile WorksheetToWordTable WorksheetToMatlabFile
    # WorksheetToRawImageFile WorksheetToTablelist

    set numRows [Excel GetLastUsedRow $worksheetId]
    set numCols [Excel GetLastUsedColumn $worksheetId]
    set startRow 1
    set catchVal [catch {open $wikiFileName w} fp]
    if { $catchVal != 0 } {
        error "Could not open file \"$wikiFileName\" for writing."
    }
    if { $useHeader } {
        set headerList [Excel GetMatrixValues $worksheetId $startRow 1 $startRow $numCols]
        set worksheetName [Excel GetWorksheetName $worksheetId]
        Excel::_WriteWikitHeader $fp [lindex $headerList 0] $worksheetName
        incr startRow
    }
    set matrixList [Excel GetMatrixValues $worksheetId $startRow 1 $numRows $numCols]
    Excel::_WriteWikitData $fp $matrixList
    close $fp
}

WorksheetToWordTable [::Excel]Excel, Main

Insert the values of a worksheet into a Word table.

WorksheetToWordTable worksheetId tableId ?useHeader?
worksheetIdIdentifier of the worksheet.
tableIdIdentifier of the Word table.
useHeaderIf set to true, use the first row of the worksheet as the header of the Word table. Otherwise do not generate a Word table header. All worksheet cells are interpreted as data. Optional, default true.

Returns no value.

See also: WordTableToWorksheet, GetMatrixValues, WorksheetToWikitFile, WorksheetToMediaWikiFile, WorksheetToMatlabFile, WorksheetToRawImageFile, WorksheetToTablelist

proc ::Excel::WorksheetToWordTable {worksheetId tableId {useHeader true}} {

    # Insert the values of a worksheet into a Word table.
    #
    # worksheetId - Identifier of the worksheet.
    # tableId     - Identifier of the Word table.
    # useHeader   - If set to true, use the first row of the worksheet as the header of the Word table.
    #               Otherwise do not generate a Word table header. All worksheet cells are interpreted as data.
    #
    # Returns no value.
    #
    # See also: WordTableToWorksheet GetMatrixValues
    # WorksheetToWikitFile WorksheetToMediaWikiFile WorksheetToMatlabFile
    # WorksheetToRawImageFile WorksheetToTablelist

    set numRows [Excel GetLastUsedRow $worksheetId]
    set numCols [Excel GetLastUsedColumn $worksheetId]
    set startRow 1
    set headerList [Excel GetRowValues $worksheetId 1 1 $numCols]
    if { [llength $headerList] < $numCols } {
        set numCols [llength $headerList]
    }
    if { $useHeader } {
        Word SetHeaderRow $tableId $headerList
        incr startRow
    }
    set excelList [Excel GetMatrixValues $worksheetId $startRow 1 $numRows $numCols]
    Word SetMatrixValues $tableId $excelList $startRow 1
}

WriteCsvFile [::Excel]Excel, Main

Write the values of a matrix into a CSV file.

WriteCsvFile matrixList csvFileName
matrixListMatrix with table data.
csvFileNameName of the CSV file.

See SetMatrixValues for the description of a matrix representation.

Returns no value.

See also: ReadCsvFile

proc ::Excel::WriteCsvFile {matrixList csvFileName} {

    # Write the values of a matrix into a `CSV` file.
    #
    # matrixList  - Matrix with table data.
    # csvFileName - Name of the `CSV` file.
    #
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns no value.
    #
    # See also: ReadCsvFile

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

    foreach row $matrixList {
        puts -nonewline $fp [Excel ListToCsvRow $row]
        puts -nonewline $fp "\r\n"
    }
    close $fp
}

WriteHtmlFile [::Excel]Excel, Main

Write the values of a matrix into a Html table file.

WriteHtmlFile matrixList htmlFileName ?useHeader?
matrixListMatrix with table data.
htmlFileNameName of the HTML file.
useHeaderIf set to true, use first row of the matrix as header of the HTML table. Optional, default true.

See SetMatrixValues for the description of a matrix representation.

Returns no value.

See also: WorksheetToHtmlFile

proc ::Excel::WriteHtmlFile {matrixList htmlFileName {useHeader true}} {

    # Write the values of a matrix into a Html table file.
    #
    # matrixList    - Matrix with table data.
    # htmlFileName  - Name of the HTML file.
    # useHeader     - If set to true, use first row of the matrix as header of the
    #                 HTML table.
    #
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns no value.
    #
    # See also: WorksheetToHtmlFile

    set catchVal [catch {open $htmlFileName w} fp]
    if { $catchVal != 0 } {
        error "Could not open file \"$htmlFileName\" for writing."
    }

    Excel::_WriteTableBegin $fp
    set curRow 1
    foreach rowList $matrixList {
        if { $useHeader && $curRow == 1 } {
            Excel::_WriteSimpleTableHeader $fp $rowList
        } else {
            Excel::_WriteSimpleTableRow $fp $rowList
        }
        incr curRow
    }
    Excel::_WriteTableEnd $fp
    close $fp
}

WriteMatlabFile [::Excel]Excel, Main

Write the values of a matrix into a Matlab file.

WriteMatlabFile matrixList matFileName
matrixListFloating point matrix.
matFileNameName of the Matlab file.

Note: Only Matlab Level 4 files are currently supported.

See SetMatrixValues for the description of a matrix representation.

Returns no value.

See also: ReadMatlabFile, WorksheetToMatlabFile

proc ::Excel::WriteMatlabFile {matrixList matFileName} {

    # Write the values of a matrix into a Matlab file.
    #
    # matrixList  - Floating point matrix.
    # matFileName - Name of the Matlab file.
    #
    # **Note:** Only Matlab Level 4 files are currently supported.
    #
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns no value.
    #
    # See also: ReadMatlabFile WorksheetToMatlabFile

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

    set height [llength $matrixList]
    set width  [llength [lindex $matrixList 0]]
    Excel::_PutMatlabHeader $matFp $width $height [file rootname $matFileName]
    for { set col 0 } { $col < $width } { incr col } {
        for { set row 0 } { $row < $height } { incr row } {
            set pix [lindex [lindex $matrixList $row] $col]
            puts -nonewline $matFp [binary format d $pix]
        }
    }
}

WriteMediaWikiFile [::Excel]Excel, Main

Write the values of a matrix into a MediaWiki table file.

WriteMediaWikiFile matrixList wikiFileName ?useHeader? ?tableName?
matrixListMatrix with table data.
wikiFileNameName of the MediaWiki file.
useHeaderIf set to true, use first row of the matrix as header of the MediaWiki table. Otherwise only transfer the table data. Optional, default true.
tableNameTable name (caption) of the generated MediaWiki table. Optional, default "".

See SetMatrixValues for the description of a matrix representation.

Returns no value.

See also: ReadMediaWikiFile, WorksheetToMediaWikiFile

proc ::Excel::WriteMediaWikiFile {matrixList wikiFileName {useHeader true} {tableName {}}} {

    # Write the values of a matrix into a MediaWiki table file.
    #
    # matrixList    - Matrix with table data.
    # wikiFileName  - Name of the MediaWiki file.
    # useHeader     - If set to true, use first row of the matrix as header of the
    #                 MediaWiki table.
    #                 Otherwise only transfer the table data.
    # tableName     - Table name (caption) of the generated MediaWiki table.
    #
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns no value.
    #
    # See also: ReadMediaWikiFile WorksheetToMediaWikiFile

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

    puts $fp "{| class=\"wikitable border=\"1\""
    if { $tableName ne "" } {
        puts $fp "|+ $tableName"
    }
    set curLine 1
    foreach line $matrixList {
        if { $useHeader && $curLine == 1 } {
            puts $fp [Excel::_MediaWikiList2RowString $line "!!"]
        } else {
            puts $fp [Excel::_MediaWikiList2RowString $line "||"]
        }
        incr curLine
    }
    puts $fp "|}"
    close $fp
}

WriteRawImageFile [::Excel]Excel, Main

Write the values of a matrix into a raw photo image file.

WriteRawImageFile matrixList rawImgFile ?pixelType?
matrixListFloating point matrix.
rawImgFileFile name of the image.
pixelTypePixel type: byte, short, float. Optional, default float.

Note: The matrix values are written as 1-channel image with given pixel type.

See SetMatrixValues for the description of a matrix representation.

Returns no value.

See also: ReadRawImageFile, WorksheetToRawImageFile

proc ::Excel::WriteRawImageFile {matrixList rawImgFile {pixelType float}} {

    # Write the values of a matrix into a raw photo image file.
    #
    # matrixList - Floating point matrix.
    # rawImgFile - File name of the image.
    # pixelType  - Pixel type: `byte`, `short`, `float`.
    #
    # **Note:** The matrix values are written as 1-channel image with given pixel type.
    #
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns no value.
    #
    # See also: ReadRawImageFile WorksheetToRawImageFile

    if { $pixelType ne "byte" && $pixelType ne "short" && $pixelType ne "float" } {
        error "Invalid PixelType value: $pixelType (must be byte, short or float)"
    }

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

    set height [llength $matrixList]
    set width  [llength [lindex $matrixList 0]]
    Excel::_PutRawImageHeader $rawFp $width $height $pixelType
    set scanFmt [Excel::_GetScanFormat $pixelType [Excel::_GetNativeByteOrder]]
    set convertToInt true
    if { $pixelType eq "float" } {
        set convertToInt false
    }
    foreach rowList $matrixList {
        foreach pix $rowList {
            if { $convertToInt } {
                puts -nonewline $rawFp [binary format $scanFmt [expr {int ($pix) }]]
            } else {
                puts -nonewline $rawFp [binary format $scanFmt $pix]
            }
        }
    }
}

WriteWikitFile [::Excel]Excel, Main

Write the values of a matrix into a Wikit table file.

WriteWikitFile matrixList wikiFileName ?useHeader?
matrixListMatrix with table data.
wikiFileNameName of the Wikit file.
useHeaderIf set to true, use first row of the matrix as header of the Wikit table. Optional, default true.

See SetMatrixValues for the description of a matrix representation.

Returns no value.

See also: ReadWikitFile, WorksheetToWikitFile

proc ::Excel::WriteWikitFile {matrixList wikiFileName {useHeader true}} {

    # Write the values of a matrix into a Wikit table file.
    #
    # matrixList    - Matrix with table data.
    # wikiFileName  - Name of the Wikit file.
    # useHeader     - If set to true, use first row of the matrix as header of the
    #                 Wikit table.
    #
    # See [SetMatrixValues] for the description of a matrix representation.
    #
    # Returns no value.
    #
    # See also: ReadWikitFile WorksheetToWikitFile

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

    set curLine 1
    foreach line $matrixList {
        if { $useHeader && $curLine == 1 } {
            puts $fp [Excel::_WikitList2RowString $line "%|" "|%"]
        } else {
            puts $fp [Excel::_WikitList2RowString $line "&|" "|&"]
        }
        incr curLine
    }
    close $fp
}
Document generated by Ruff!