CAWT 2.4.7 Reference Manual

# ::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?

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

Show source

    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?

`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. Optional, default `""`.
`yaxisName` | Name of y-axis. Optional, default `Values`.
`markerSize` | Size 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

Show source

    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?

`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. Optional, default `""`.
`yaxisName` | Name of y-axis. Optional, default `Values`.
`markerSize` | Size 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

Show source

    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?

`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. Optional, default `""`.
`markerSize` | Size 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

Show source

    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?

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

Show source

    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?

`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).
`-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

Show source

    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?

`appId` | Identifier of the Excel instance.
`type` | Value 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

Show source

    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?

`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`. Optional, default `xlSheetVisible`.

Returns the identifier of the new worksheet.

See also: GetNumWorksheets, DeleteWorksheet

Show source

    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?

`appId` | Identifier of the Excel instance.
`arrangeStyle` | Value of enumeration type Enum::XlArrangeStyle. Typical values are: `xlArrangeStyleHorizontal`, `xlArrangeStyleTiled`, `xlArrangeStyleVertical`. Optional, default `xlArrangeStyleVertical`.

Returns no value.

See also: Open, Visible, SetWindowState

Show source

    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

`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

Show source

    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

`chartId` | Not documented.

Show source

    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?

`sepChar` | The 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

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`startRow` | Row number. Row numbering starts with 1. Optional, default `1`.
`startCol` | Column number. Column numbering starts with 1. Optional, default `1`.
`sepChar` | The 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

Show source

    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

`workbookId` | Identifier of the workbook.

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

Returns no value.

See also: SaveAs, OpenWorkbook

Show source

    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

`colChar` | Column string.

Example:

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

Returns the corresponding column number.

See also: GetColumnNumber, ColumnIntToChar

Show source

    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

`col` | Column number.

Example:

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

Returns the corresponding column string.

See also: ColumnCharToInt

Show source

    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?

`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. Optional, default `1`.
`toRow` | Start row of destination column. Optional, default `1`.
`pasteType` | Value 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

Show source

    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?

`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`. Optional, default `xlPasteAll`.

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

Returns no value.

See also: SelectAll, CopyWorksheet, CopyColumn

Show source

    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

`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

Show source

    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?

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

Show source

    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?

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

Show source

    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

`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

Show source

    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?

`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

Show source

    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

`rowStr` | `CSV` encoded row as string.

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

See also: ListToCsvRow

Show source

    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

`csvString` | `CSV` encoded table as string.

Returns the matrix from the `CSV` encoded table string.

See also: MatrixToCsvString, CsvRowToList

Show source

    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

`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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`workbookId` | Identifier of the workbook containing the worksheet.
`index` | Index 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

Show source

    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?

`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

Show source

    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

`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

Show source

    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

`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

Show source

    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?

`excelFileName` | Name of the Excel input file.
`htmlFileName` | Name of the HTML output file.
`args` | Options 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

Show source

    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?

`excelFileName` | Name of the Excel input file.
`matFileName` | Name of the Matlab output file.
`worksheetNameOrIndex` | Worksheet name or index to convert. Optional, default `0`.
`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. Optional, default `true`.
`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. 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

Show source

    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?

`excelFileName` | Name of the Excel input file.
`wikiFileName` | Name of the MediaWiki output file.
`worksheetNameOrIndex` | Worksheet name or index to convert. Optional, default `0`.
`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. Optional, default `true`.
`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. 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

Show source

    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?

`excelFileName` | Name of the Excel input file.
`rawFileName` | Name of the image output file.
`worksheetNameOrIndex` | Worksheet name or index to convert. Optional, default `0`.
`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. Optional, default `true`.
`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. Optional, default `true`.
`pixelType` | Pixel 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

Show source

    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?

`excelFileName` | Name of the Excel input file.
`wikiFileName` | Name of the Wikit output file.
`worksheetNameOrIndex` | Worksheet name or index to convert. Optional, default `0`.
`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. Optional, default `true`.
`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. 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

Show source

    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

`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

Show source

    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?

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

Show source

    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

`appId` | Identifier of the Excel instance.

Returns the identifier of the active workbook.

See also: OpenWorkbook

Show source

    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

`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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`worksheetId` | Identifier of the worksheet.

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

Show source

    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?

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

Show source

    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

`chartId` | Identifier of the chart.

Returns the number of series of the chart.

See also: GetChartSeries, CreateChart

Show source

    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

`chartId` | Identifier of the chart.
`index` | Index of the series. Index numbering starts with 1.

Returns the series identifier.

See also: GetChartNumSeries, CreateChart, SetSeriesAttributes

Show source

    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

`colStrOrInt` | Column string.

Returns the corresponding column number.

See also: ColumnCharToInt

Show source

    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

`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

Show source

    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?

`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. Optional, default `0`.
`numVals` | If 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

Show source

    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.

Show source

    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?

`appId` | Identifier of the Excel instance.
`currency` | String identifying the currency symbol.
`pre` | Number of digits before the decimal point. Optional, default `0`.
`post` | Number of digits after the decimal point. Optional, default `00`.
`floatSep` | Specify 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

Show source

    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

`appId` | Identifier of the Excel instance.

Returns the decimal separator used by Excel.

See also: GetVersion, GetThousandsSeparator

Show source

    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

`enumOrString` | Enumeration name

Returns the numeric value of an enumeration.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnumNames

Show source

    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

`enumType` | Enumeration type
`enumVal` | Enumeration numeric value.

Returns the list of names of a given enumeration type.

See also: GetEnumNames, GetEnumTypes, GetEnumVal, GetEnum

Show source

    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

`enumType` | Enumeration type

Returns the list of names of a given enumeration type.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnum

Show source

    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

Show source

    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

`enumName` | Enumeration name

Returns the numeric value of an enumeration name.

See also: GetEnumName, GetEnumTypes, GetEnumNames, GetEnum

Show source

    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

`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

Show source

    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

`worksheetId` | Identifier of the worksheet.

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

See also: GetNumColumns, GetNumUsedColumns, GetLastUsedColumn, GetNumUsedRows

Show source

    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

`worksheetId` | Identifier of the worksheet.

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

See also: GetNumRows, GetNumUsedRows, GetLastUsedRow, GetNumUsedColumns

Show source

    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

Show source

    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

`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

Show source

    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

`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

Show source

    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?

`pre` | Number of digits before the decimal point.
`post` | Number of digits after the decimal point.
`floatSep` | Specify 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

Show source

    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

`worksheetId` | Identifier of the worksheet.

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

See also: GetNumColumns, GetNumUsedColumns, GetFirstUsedColumn, GetNumUsedRows

Show source

    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

`worksheetId` | Identifier of the worksheet.

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

See also: GetNumRows, GetNumUsedRows, GetFirstUsedRow, GetNumUsedColumns

Show source

    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

`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

Show source

    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

`appId` | Identifier of the Excel instance.

Returns the maximum number of columns of an Excel table.

See also: GetNumColumns

Show source

    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

`appId` | Identifier of the Excel instance.

Returns the maximum number of rows of an Excel table.

See also: GetNumRows

Show source

    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

`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

Show source

    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

`objId` | Identifier of a workbook or worksheet.

Returns a sorted list of all names.

See also: GetNamedRange, SetNamedRange

Show source

    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?

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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`workbookId` | Identifier of the workbook.

Returns the number of worksheets in the workbook.

See also: AddWorksheet, OpenWorkbook

Show source

    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

`rangeId` | Identifier 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

Show source

    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

`rangeId` | Identifier of the cell range.

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

See also: SelectRangeByString, GetCellRange

Show source

    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?

`rangeId` | Identifier of the cell range.
`start` | Start of the character range. Optional, default `1`.
`length` | The 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

Show source

    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

`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

Show source

    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

`rangeId` | Identifier of the cell range.

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

See also: SetRangeFontBold, SelectRangeByIndex

Show source

    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

`rangeId` | Identifier of the cell range.

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

See also: SetRangeFontItalic, SelectRangeByIndex

Show source

    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

`rangeId` | Identifier of the cell range.

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

See also: SetRangeFontName, SelectRangeByIndex

Show source

    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

`rangeId` | Identifier of the cell range.

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

See also: SetRangeFontSize, SelectRangeByIndex

Show source

    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

`rangeId` | Identifier of the cell range.

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

See also: SetRangeFontSubscript, SelectRangeByIndex

Show source

    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

`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

Show source

    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

`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

Show source

    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

`rangeId` | Identifier of the cell range.

Returns the number format in Excel style.

See also: SetRangeFormat, SelectRangeByIndex, SelectRangeByString

Show source

    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

`rangeId` | Identifier of the cell range.

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

See also: SetRangeHorizontalAlignment, SelectRangeByIndex, SelectRangeByString

Show source

    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

`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

Show source

    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

`rangeId` | Identifier of the cell range.

Returns the range values as a matrix.

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

Show source

    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

`rangeId` | Identifier of the cell range.

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

See also: SetRangeVerticalAlignment, SelectRangeByIndex, SelectRangeByString

Show source

    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

`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

Show source

    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?

`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. Optional, default `0`.
`numVals` | If 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

Show source

    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

`tableId` | Identifier of the tablelist.

Returns the header line of the tablelist as a list.

See also: TablelistToWorksheet, WorksheetToTablelist, SetTablelistHeader, GetTablelistValues

Show source

    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

`tableId` | Identifier of the tablelist.

Returns the values of the tablelist as a matrix.

See also: TablelistToWorksheet, WorksheetToTablelist, SetTablelistValues, GetTablelistHeader

Show source

    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

`appId` | Identifier of the Excel instance.

Returns the thousands separator used by Excel.

See also: GetVersion, GetDecimalSeparator

Show source

    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?

`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`). 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

Show source

    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

`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

Show source

    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

`workbookId` | Identifier of the workbook.

Returns the name of the workbook.

See also: AddWorkbook

Show source

    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

`worksheetId` | Identifier of the worksheet.

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

See also: SetMatrixValues, GetMatrixValues, GetFirstUsedRow, GetLastUsedRow

Show source

    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?

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

Show source

    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?

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

Show source

    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?

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

Show source

    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

`worksheetId` | Identifier of the worksheet.

Returns the name of the worksheet.

See also: SetWorksheetName, AddWorksheet

Show source

    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?

`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. Optional, default `true`.

Returns no value.

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

Show source

    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?

`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. Optional, default `true`.

Returns no value.

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

Show source

    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?

`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. Optional, default `1`.
`col` | Column number of the top-left corner of the image. Column numbering starts with 1. Optional, default `1`.
`rowHeight` | Row height. Optional, default `9`.
`colWidth` | Column 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

Show source

    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?

`rangeId` | Identifier of the cell range.
`fileName` | File name of the data source.
`args` | Options 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

Show source

    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

`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

Show source

    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?

`worksheetId` | Identifier of the worksheet where the image is inserted.
`imgFileName` | File name of the image.
`row` | Row number. Row numbering starts with 1. Optional, default `1`.
`col` | Column number. Column numbering starts with 1. Optional, default `1`.
`linkToFile` | Insert a link to the image file. Optional, default `false`.
`saveWithDoc` | Embed 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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`workbookId` | Identifier of the workbook to be checked.

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

See also: OpenWorkbook, IsWorkbookOpen

Show source

    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

`worksheetId` | Identifier of the worksheet to be checked.

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

See also: GetNumUsedRows, GetNumUsedColumns, GetFirstUsedRow, GetLastUsedRow

Show source

    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

`worksheetId` | Identifier of the worksheet to be checked.

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

See also: AddWorksheet

Show source

    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

`worksheetId` | Identifier of the worksheet to be checked.

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

See also: AddWorksheet

Show source

    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

`rowList` | List of column values.

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

See also: CsvRowToList

Show source

    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?

`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. Optional, default `true`.
`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. 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

Show source

    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?

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

Show source

    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?

`matrixList` | Matrix with table data.
`sepChar` | The 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

Show source

    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

`matrixList` | Matrix with table data.

Returns the `CSV` encoded table string from a matrix list.

See also: CsvStringToMatrix, ListToCsvRow

Show source

    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?

`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. Optional, default `true`.
`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. 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

Show source

    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?

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

Show source

    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?

`visible` | If set to true, show the application window. Otherwise hide the application window. Optional, default `true`.
`width` | Width of the application window. If negative, open with last used width. Optional, default `-1`.
`height` | Height 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

Show source

    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?

`visible` | If set to true, show the application window. Otherwise hide the application window. Optional, default `true`.
`width` | Width of the application window. If negative, open with last used width. Optional, default `-1`.
`height` | Height 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

Show source

    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?

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

Show source

    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

`chartId` | Identifier of the chart.
`worksheetId` | Identifier of the worksheet.

Returns the ChartObject identifier of the placed chart.

See also: CreateChart, SetChartObjSize, SetChartObjPosition

Show source

    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?

`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. Optional, default `true`.

Returns no value.

See also: Open, OpenNew

Show source

    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?

`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. Optional, default `true`.
`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. 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

Show source

    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?

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

Show source

    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?

`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. Optional, default `true`.
`numHeaderRows` | Number 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

Show source

    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

`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

Show source

    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

`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

Show source

    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?

`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. Optional, default `true`.

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

See also: WriteMediaWikiFile, MediaWikiFileToWorksheet

Show source

    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

`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

Show source

    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

`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

Show source

    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?

`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. Optional, default `true`.

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

See also: WriteWikitFile, WikitFileToWorksheet

Show source

    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

`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

Show source

    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?

`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. Optional, default `""`.
`backup` | If 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

Show source

    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?

`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. Optional, default `xlCSV`.

Returns no value.

See also: SaveAs, Close, OpenWorkbook

Show source

    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?

`chartId` | Not documented.
`fileName` | Not documented.
`filterType` | Not documented. Optional, default `GIF`.

Show source

    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?

`chartObjId` | Identifier of the chart object.
`fileName` | Image file name.
`filterType` | Name of graphic filter. Possible values: `GIF`, `JPEG`, `PNG`. Optional, default `GIF`.

Returns no value.

See also: ChartObjToClipboard, CreateChart

Show source

    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

`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

Show source

    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

`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

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`str` | Search string.
`row1` | Row number of upper-left corner of the cell range. Optional, default `1`.
`col1` | Column number of upper-left corner of the cell range. Optional, default `1`.
`row2` | Row number of lower-right corner of the cell range. Optional, default `-1`.
`col2` | Column 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.

Show source

    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

`worksheetId` | Identifier of the worksheet.

Returns the cells collection of the selected cells.

See also: CopyWorksheet

Show source

    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?

`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. Optional, default `false`.

Returns the identifier of the cell as a range identifier.

See also: SelectRangeByIndex, AddWorksheet

Show source

    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?

`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. Optional, default `false`.

Returns the range identifier of the cell range.

See also: SelectCellByIndex, GetCellRange

Show source

    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?

`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. Optional, default `false`.

Returns the range identifier of the cell range.

See also: SelectRangeByIndex, GetCellRange

Show source

    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?

`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`. Optional, default `text`.
`subFmt` | Formatting 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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`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

Show source

    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

`worksheetId` | Not documented.
`chartId` | Not documented.
`width` | Not documented.
`height` | Not documented.

Show source

    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?

`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. Optional, default `xlColumns`.

Returns no value.

See also: CreateChart, SetChartTitle, SetChartScale

Show source

    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?

`chartId` | Identifier of the chart.
`axisName` | Name of axis. Possible values: `x` or `y`.
`tickMarkSpacing` | Spacing of tick marks. Optional, default `""`.
`tickLabelSpacing` | Spacing 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

Show source

    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

`chartId` | Identifier of the chart.
`title` | Name of the chart title.

Returns no value.

See also: SetChartMinScale, SetChartScale, CreateChart

Show source

    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?

`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. Optional, default `0`.

Returns no value.

See also: SetColumnWidth, ColumnCharToInt

Show source

    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?

`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. Optional, default `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). Optional, default `0`.

Returns no value.

See also: GetColumnValues, SetRowValues, SetCellValue, ColumnCharToInt

Show source

    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?

`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. Optional, default `0`.

Returns no value.

See also: SetColumnsWidth, ColumnCharToInt

Show source

    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?

`appId` | Identifier of the Excel instance.
`showComment` | If set to true, show the comments. Otherwise do not show the comments. Optional, default `false`.
`showIndicator` | If 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

Show source

    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

`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

Show source

    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?

`separatorChar` | The character used as the column separator. Optional, default `;`.

Returns no value.

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`headerList` | List of values to be inserted as header.
`row` | Row number. Row numbering starts with 1. Optional, default `1`.
`startCol` | Column 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

Show source

    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?

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

Show source

    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?

`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. Optional, default `""`.

Returns no value.

See also: AddWorksheet, SetHyperlinkToFile, SetHyperlink, SetLinkToCell

Show source

    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?

`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. Optional, default `""`.

Returns no value.

See also: AddWorksheet, SetHyperlinkToCell, SetHyperlink, SetLinkToCell

Show source

    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

`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

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`matrixList` | Matrix with table data.
`startRow` | Row number of insertion start. Row numbering starts with 1. Optional, default `1`.
`startCol` | Column 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

Show source

    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?

`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. Optional, default `true`.

Returns no value.

See also: GetNamedRange, GetNamedRangeNames

Show source

    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?

`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`. Optional, default `xlThin`.
`lineStyle` | Value of enumeration type Enum::XlLineStyle. Typical values: `xlContinuous`, `xlDash`, `xlDot`. Optional, default `xlContinuous`.
`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

Show source

    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?

`rangeId` | Identifier of the cell range.
`weight` | Value of enumeration type Enum::XlBorderWeight. Typical values: `xlThin`, `xlMedium`, `xlThick`. Optional, default `xlThin`.
`lineStyle` | Value of enumeration type Enum::XlLineStyle. Typical values: `xlContinuous`, `xlDash`, `xlDot`. Optional, default `xlContinuous`.
`r` | Red component of the border color. Optional, default `0`.
`g` | Green component of the border color. Optional, default `0`.
`b` | Blue 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

Show source

    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?

`rangeId` | Identifier of the cell range.
`comment` | Comment text.
`imgFileName` | File name of an image used as comment background. Optional, default `""`.
`addUserName` | Automatically add user name before comment text. Optional, default `true`.
`visible` | If 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

Show source

    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?

`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

Show source

    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?

`rangeId` | Identifier of the cell range.
`onOff` | If 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

Show source

    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?

`rangeId` | Identifier of the cell range.
`onOff` | If 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

Show source

    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

`rangeId` | Identifier of the cell range.
`fontName` | Name of the font as a string.

Returns no value.

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

Show source

    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

`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

Show source

    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?

`rangeId` | Identifier of the cell range.
`onOff` | If set to true, set subscript style on. Otherwise set subscript style off. Optional, default `true`.

Returns no value.

See also: SetRangeFontName, SetRangeFontSuperscript, SelectRangeByIndex

Show source

    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?

`rangeId` | Identifier of the cell range.
`onOff` | If set to true, set superscript style on. Otherwise set superscript style off. Optional, default `true`.

Returns no value.

See also: SetRangeFontName, SetRangeFontSubscript, SelectRangeByIndex, GetRangeCharacters

Show source

    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?

`rangeId` | Identifier of the cell range.
`style` | Value of enumeration type Enum::XlUnderlineStyle. Optional, default `xlUnderlineStyleSingle`.

Returns no value.

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

Show source

    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?

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

Show source

    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

`rangeId` | Identifier of the cell range.
`align` | Value of enumeration type Enum::XlHAlign.

Returns no value.

See also: GetRangeHorizontalAlignment, SetRangeVerticalAlignment, SelectRangeByIndex, SelectRangeByString

Show source

    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?

`rangeId` | Identifier of the cell range.
`onOff` | If set to true, set cell merge on. Otherwise set cell merge off. Optional, default `true`.

Returns no value.

See also: SetRangeVerticalAlignment, SelectRangeByIndex, SelectRangeByString

Show source

    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?

`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

Show source

    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?

`rangeId` | Identifier of the cell range.
`tooltipMessage` | The tooltip message string.
`tooltipTitle` | The 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

Show source

    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

`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

Show source

    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

`rangeId` | Identifier of the cell range.
`align` | Value of enumeration type Enum::XlVAlign.

Returns no value.

See also: SetRangeHorizontalAlignment, SelectRangeByIndex, SelectRangeByString

Show source

    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?

`rangeId` | Identifier of the cell range.
`onOff` | If set to true, set text wrapping on. Otherwise set text wrapping off. Optional, default `true`.

Returns no value.

See also: GetRangeWrapText, SetRangeHorizontalAlignment, SetRangeTextColor, SelectRangeByIndex

Show source

    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?

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

Show source

    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?

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

Show source

    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?

`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. Optional, default `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). Optional, default `0`.

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

See also: GetRowValues, SetColumnValues, SetCellValue, ColumnCharToInt

Show source

    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?

`seriesId` | Identifier of the series.
`args` | Options 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

Show source

    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

`seriesId` | Identifier of the series.
`width` | Line width.

Returns no value.

See also: GetChartNumSeries, GetChartSeries, AddSeriesTrendLine

Show source

    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

`tableId` | Identifier of the tablelist.
`headerList` | List with table header data.

Returns no value.

See also: TablelistToWorksheet, WorksheetToTablelist, SetTablelistValues, GetTablelistHeader

Show source

    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

`tableId` | Identifier of the tablelist.
`matrixList` | Matrix with table data.

Returns no value.

See also: TablelistToWorksheet, WorksheetToTablelist, SetTablelistHeader, GetTablelistValues

Show source

    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?

`appId` | Identifier of the Excel instance.
`windowState` | Value of enumeration type Enum::XlWindowState. Typical values are: `xlMaximized`, `xlMinimized`, `xlNormal`. Optional, default `xlNormal`.

Returns no value.

See also: Open, Visible, ArrangeWindows

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`wide` | The number of pages in horizontal direction. Optional, default `1`.
`tall` | The 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

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`args` | Options 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

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`args` | Options 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

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`args` | Options 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

Show source

    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

`worksheetId` | Identifier of the worksheet.
`name` | Name of the worksheet.

Returns no value.

See also: GetWorksheetName, AddWorksheet

Show source

    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

`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

Show source

    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

`worksheetId` | Identifier of the worksheet.
`paperSize` | Value of enumeration type Enum::XlPaperSize.

Returns no value.

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

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`args` | Options 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

Show source

    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?

`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

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`zoom` | The 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

Show source

    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

`appId` | The application identifier.
`onOff` | Switch the alerts on or off.

Returns no value.

Show source

    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

`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

Show source

    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

`worksheetId` | Identifier of the worksheet.

See also: GetNumWorksheets, GetWorksheetIdByName, AddWorksheet

Show source

    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?

`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. Optional, default `true`.
`startRow` | Row 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

Show source

    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

`rangeId` | Identifier of the cell range.

Returns no value.

See also: SelectRangeByIndex, SelectRangeByString

Show source

    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

`worksheetId` | Identifier of the worksheet.

If the worksheet is hidden, it is made visible.

Returns no value.

See also: SetWorksheetTabColor, IsWorksheetVisible

Show source

    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

`onOff` | Not documented.

Only valid for ImgToWorksheet and WorksheetToImg procedures.

See also: ImgToWorksheet, WorksheetToImg

Show source

    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?

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

Show source

    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?

`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. Optional, default `true`.
`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. 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

Show source

    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?

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

Show source

    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?

`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. Optional, default `true`.

Returns no value.

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

Show source

    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?

`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. Optional, default `;`.

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

Returns no value.

See also: ClipboardToWorksheet, MatrixToClipboard

Show source

    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?

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

Show source

    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?

`worksheetId` | Identifier of the worksheet.
`startRow` | Row number of the top-left corner of the image. Optional, default `1`.
`startCol` | Column number of the top-left corner of the image. Optional, default `1`.
`endRow` | Row number of the bottom-right corner of the image. Optional, default `end`.
`endCol` | Column 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

Show source

    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?

`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. Optional, default `true`.

Note: Only Matlab Level 4 files are currently supported.

Returns no value.

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

Show source

    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?

`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. Optional, default `true`.

Returns no value.

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

Show source

    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?

`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. Optional, default `true`.
`pixelType` | Pixel 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

Show source

    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?

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

Show source

    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?

`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. Optional, default `true`.

Returns no value.

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

Show source

    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?

`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. Optional, default `true`.

Returns no value.

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

Show source

    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

`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

Show source

    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?

`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. Optional, default `true`.

See SetMatrixValues for the description of a matrix representation.

Returns no value.

See also: WorksheetToHtmlFile

Show source

    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

`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

Show source

    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?

`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. Optional, default `true`.
`tableName` | Table 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

Show source

    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?

`matrixList` | Floating point matrix.
`rawImgFile` | File name of the image.
`pixelType` | Pixel 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

Show source

    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?

`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. Optional, default `true`.

See SetMatrixValues for the description of a matrix representation.

Returns no value.

See also: ReadWikitFile, WorksheetToWikitFile

Show source

    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
    }

# Start page

# Cawt

# Office

# Excel

# Ppt

# Word

# Outlook

# OneNote

# Office::Enum

# Excel::Enum

# Ppt::Enum

# Word::Enum

# Outlook::Enum

# OneNote::Enum

# Earth

# Explorer

# Ocr

# Reader

# Matlab

# Excel

## Commands

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

#### AddLineChart Add a line chart to a worksheet. Generic case.

#### AddLineChartSimple Add a line chart to a worksheet. Simple case.

#### AddPointChartSimple Add a point chart to a worksheet. Simple case.

#### AddRadarChartSimple Add a radar chart to a worksheet. Simple case.

#### AddSeriesTrendLine Add a trend line to a series.

#### AddWorkbook Add a new workbook with one worksheet.

#### AddWorksheet Add a new worksheet to the end of a workbook.

#### ArrangeWindows Arrange the windows of an Excel application.

#### ChartObjToClipboard Copy a chart object to the clipboard.

#### ChartToClipboard Obsolete: Replaced with ChartObjToClipboard in version 1.0.1

#### ClipboardToMatrix Return the matrix values contained in the clipboard.

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

#### Close Close a workbook without saving changes.

#### ColumnCharToInt Return an Excel column string as a column number.

#### ColumnIntToChar Return a column number as an Excel column string.

#### CopyColumn Copy the contents of a column into another column.

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

#### CopyWorksheet Copy the contents of a worksheet into another worksheet.

#### CopyWorksheetAfter Copy the contents of a worksheet after another worksheet.

#### CopyWorksheetBefore Copy the contents of a worksheet before another worksheet.

#### CreateChart Create a new empty chart in a worksheet.

#### CreateRangeString Create a range string in A1 notation.

#### CsvRowToList Return a `CSV` encoded row as a list of column values.

#### CsvStringToMatrix Return a matrix from a `CSV` encoded table string.

#### DeleteColumn Delete a column.

#### DeleteRow Delete a row.

#### DeleteWorksheet Delete a worksheet.

#### DeleteWorksheetByIndex Delete a worksheet identified by its index.

#### DiffExcelFiles Compare two Excel files visually.

#### DuplicateColumn Duplicate a column.

#### DuplicateRow Duplicate a row.

#### ExcelFileToHtmlFile Convert an Excel file to a HTML table file.

#### ExcelFileToMatlabFile Convert an Excel file to a Matlab table file.

#### ExcelFileToMediaWikiFile Convert an Excel file to a MediaWiki table file.

#### ExcelFileToRawImageFile Convert an Excel file to a raw photo image file.

#### ExcelFileToWikitFile Convert an Excel file to a Wikit table file.

#### FormatHeaderRow Format a row as a header row.

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

#### GetActiveWorkbook Return the active workbook of an application.

#### GetCellComment Return the comment text of a cell.

#### GetCellIdByIndex Return a cell of a worksheet.

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

#### GetCellsId Return the cells identifier of a worksheet.

#### GetCellValue Return the value of a cell.

#### GetChartNumSeries Return the number of series of a chart.

#### GetChartSeries Get a specific series of a chart.

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

#### GetColumnRange Return a numeric column range as an Excel range string.

#### GetColumnValues Return column values as a Tcl list.

#### GetCsvSeparatorChar Returns the column separator character.

#### GetCurrencyFormat Return an Excel number format string for currencies.

#### GetDecimalSeparator Return the decimal separator used by Excel.

#### GetEnum Get numeric value of an enumeration.

#### GetEnumName Get name of a given enumeration type and numeric value.

#### GetEnumNames Get names of a given enumeration type.

#### GetEnumTypes Get available enumeration types.

#### GetEnumVal Get numeric value of an enumeration name.

#### GetExtString Return the default extension of an Excel file.

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

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

#### GetFloatSeparator Obsolete: Replaced with GetDecimalSeparator in version 2.1.0

#### GetHiddenColumns Return the hidden columns of a worksheet.

#### GetHiddenRows Return the hidden rows of a worksheet.

#### GetLangNumberFormat Obsolete: Replaced with GetNumberFormat in version 2.1.0

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

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

#### GetMatrixValues Return worksheet table values as a matrix.

#### GetMaxColumns Return the maximum number of columns of an Excel table.

#### GetMaxRows Return the maximum number of rows of an Excel table.

#### GetNamedRange Get the identifier of a named range.

#### GetNamedRangeNames Get the names of named ranges.

#### GetNumberFormat Return an Excel number format string.

#### GetNumColumns Return the number of columns of a cell range.

#### GetNumRows Return the number of rows of a cell range.

#### GetNumUsedColumns Return the number of used columns of a worksheet.

#### GetNumUsedRows Return the number of used rows of a worksheet.

#### GetNumWorksheets Return the number of worksheets in a workbook.

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

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

#### GetRangeCharacters Return characters of a cell range.

#### GetRangeFillColor Get the fill color of a cell range.

#### GetRangeFontBold Get the bold font style of a cell range.

#### GetRangeFontItalic Get the italic font style of a cell range.

#### GetRangeFontName Get the font name of a cell or character range.

#### GetRangeFontSize Get the font size of a cell range.

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

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

#### GetRangeFontUnderline Get the underline font style of a cell range.

#### GetRangeFormat Get the number format of a cell range.

#### GetRangeHorizontalAlignment Get the horizontal alignment of a cell range.

#### GetRangeTextColor Get the text color of a cell range.

#### GetRangeValues Return range values as a matrix.

#### GetRangeVerticalAlignment Get the vertical alignment of a cell range.

#### GetRangeWrapText Get the wrap text mode of a cell range.

#### GetRowValues Return row values as a Tcl list.

#### GetTablelistHeader Return the header line of a tablelist as a list.

#### GetTablelistValues Return the values of a tablelist as a matrix.

#### GetThousandsSeparator Return the thousands separator used by Excel.

#### GetVersion Return the version of an Excel application.

#### GetWorkbookIdByName Find an open workbook by its name.

#### GetWorkbookName Return the name of a workbook.

#### GetWorksheetAsMatrix Return worksheet table as a matrix.

#### GetWorksheetIdByIndex Find a worksheet by its index.

#### GetWorksheetIdByName Find a worksheet by its name.

#### GetWorksheetIndexByName Find a worksheet index by its name.

#### GetWorksheetName Return the name of a worksheet.

#### HideColumn Hide or unhide a column.

#### HideRow Hide or unhide a row.

#### ImgToWorksheet Put a photo image into a worksheet.

#### Import Import data from an external data source.

#### InsertColumn Insert a new empty column.

#### InsertImage Insert an image into a worksheet.

#### InsertRow Insert a new empty row.

#### IsWorkbookId Check, if Excel object is a workbook identifier.

#### IsWorkbookOpen Check, if a workbook is open.

#### IsWorkbookProtected Check, if a workbook is protected.

#### IsWorksheetEmpty Check, if a worksheet is empty.

#### IsWorksheetProtected Check, if a worksheet is content protected.

#### IsWorksheetVisible Check, if a worksheet is visible.

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

#### MatlabFileToExcelFile Convert a Matlab table file to an Excel file.

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

#### MatrixToClipboard Copy a matrix into the clipboard.

#### MatrixToCsvString Return a `CSV` encoded table string from a matrix list.

#### MediaWikiFileToExcelFile Convert a MediaWiki table file to an Excel file.

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

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

#### OpenNew Open a new Excel instance.

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

#### PlaceChart Place an existing chart into a worksheet.

#### Quit Quit an Excel instance.

#### RawImageFileToExcelFile Convert a raw photo image file to an Excel file.

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

#### ReadCsvFile Read a `CSV` table file into a matrix.

#### ReadMatlabFile Read a Matlab file into a matrix.

#### ReadMatlabHeader Read the header of a Matlab file.

#### ReadMediaWikiFile Read a MediaWiki table file into a matrix.

#### ReadRawImageFile Read a raw photo image into a matrix.

#### ReadRawImageHeader Read the header of a raw photo image.

#### ReadWikitFile Read a Wikit table file into a matrix.

#### ResizeChartObj Set the position and size of a chart object.

#### SaveAs Save a workbook to an Excel file.

#### SaveAsCsv Save a worksheet to file in `CSV` format.

#### SaveChartAsImage Obsolete: Replaced with SaveChartObjAsImage in version 1.0.1

#### SaveChartObjAsImage Save a chart as an image in a file.

#### ScaleImage Scale an image.

#### ScreenUpdate Toggle the screen updating of an Excel application window.

#### Search Find a string in a worksheet cell range.

#### SelectAll Select all cells of a worksheet.

#### SelectCellByIndex Select a cell by its row/column index.

#### SelectRangeByIndex Select a range by specifying a numeric cell range.

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

#### SetCellValue Set the value of a cell.

#### SetChartMaxScale Set the maximum scale of an axis of a chart.

#### SetChartMinScale Set the minimum scale of an axis of a chart.

#### SetChartObjPosition Set the position of a chart object.

#### SetChartObjSize Set the size of a chart object.

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

#### SetChartSize Obsolete: Replaced with SetChartObjSize in version 1.0.1

#### SetChartSourceByIndex Set the cell range for the source of a chart.

#### SetChartTicks Set the tick spacing of an axis of a chart.

#### SetChartTitle Set the title of a chart.

#### SetColumnsWidth Set the width of a range of columns.

#### SetColumnValues Insert column values from a Tcl list.

#### SetColumnWidth Set the width of a column.

#### SetCommentDisplayMode Set the global display mode of comments.

#### SetCommentSize Set the shape size of a comment.

#### SetCsvSeparatorChar Set the column separator character.

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

#### SetHyperlink Insert a hyperlink into a cell.

#### SetHyperlinkToCell Insert a hyperlink to a cell into another cell.

#### SetHyperlinkToFile Insert a hyperlink to a file into a cell.

#### SetLinkToCell Insert an internal link to a cell into another cell.

#### SetMatrixValues Insert matrix values into a worksheet.

#### SetNamedRange Set the name of a cell range.

#### SetRangeBorder Set the attributes of one border of a cell range.

#### SetRangeBorders Set the attributes of all borders of a cell range.

#### SetRangeComment Set the comment text of a cell range.

#### SetRangeFillColor Set the fill color of a cell range.

#### SetRangeFontBold Set the bold font style of a cell range.

#### SetRangeFontItalic Set the italic font style of a cell range.

#### SetRangeFontName Set the font name of a cell or character range.

#### SetRangeFontSize Set the font size of a cell range.

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

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

#### SetRangeFontUnderline Set the underline font style of a cell range.

#### SetRangeFormat Set the number format of a cell range.

#### SetRangeHorizontalAlignment Set the horizontal alignment of a cell range.

#### SetRangeMergeCells Merge/Unmerge a range of cells.

#### SetRangeTextColor Set the text color of a cell range.

#### SetRangeTooltip Set a selection based tooltip for a cell range.

#### SetRangeValues Set range values from a matrix.

#### SetRangeVerticalAlignment Set the vertical alignment of a cell range.

#### SetRangeWrapText Set the text wrapping mode of a cell range.

#### SetRowHeight Set the height of a row.

#### SetRowsHeight Set the height of a range of rows.

#### SetRowValues Insert row values from a Tcl list.

#### SetSeriesAttributes Set the attributes of a series.

#### SetSeriesLineWidth Set the line width of a series.

#### SetTablelistHeader Insert header values into a tablelist.

#### SetTablelistValues Insert matrix values into a tablelist.

#### SetWindowState Set the window state of an Excel application.

#### SetWorksheetFitToPages Adjust a worksheet to fit onto given number of pages.

#### SetWorksheetFooter Set the texts of the footer of a worksheet.

#### SetWorksheetHeader Set the texts of the header of a worksheet.

#### SetWorksheetMargins Set the margins of a worksheet.

#### SetWorksheetName Set the name of a worksheet.

#### SetWorksheetOrientation Set the orientation of a worksheet.

#### SetWorksheetPaperSize Set the paper size of a worksheet.

#### SetWorksheetPrintOptions Set printing options of a worksheet.

#### SetWorksheetTabColor Set the color of the tab of a worksheet.

#### SetWorksheetZoom Set the zoom factor for printing of a worksheet.

#### ShowAlerts Toggle the display of Excel application alerts.

#### ShowCellByIndex Show a cell identified by its row/column index.

#### ShowWorksheet Show a worksheet.

#### TablelistToWorksheet Insert the values of a tablelist into a worksheet.

#### ToggleAutoFilter Toggle the AutoFilter switch of a cell range.

#### UnhideWorksheet Unhide a worksheet, if it is hidden.

#### UseImgTransparency Toggle usage of transparency channel of an image.

#### Visible Set or query the visibility of an Excel application window.

#### WikitFileToExcelFile Convert a Wikit table file to an Excel file.

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

#### WordTableToWorksheet Insert the values of a Word table into a worksheet.

#### WorksheetToClipboard Copy worksheet data into the clipboard.

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

#### WorksheetToImg Put worksheet background colors into a photo image.

#### WorksheetToMatlabFile Insert the values of a worksheet into a Matlab file.

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

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

#### WorksheetToTablelist Insert the values of a worksheet into a tablelist.

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

#### WorksheetToWordTable Insert the values of a worksheet into a Word table.

#### WriteCsvFile Write the values of a matrix into a `CSV` file.

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

#### WriteMatlabFile Write the values of a matrix into a Matlab file.

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

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

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

Document generated by Ruff!