CAWT 2.6.0 Reference Manual

# ::CawtTop, Main

The `Cawt` namespace provides commands for basic automation functionality.

## CommandsCawt, Top, Main

#### CentiMetersToPoints [::Cawt]Cawt, Top, Main

Convert centimeter value into points.

CentiMetersToPoints cm

`cm` | Floating point centimeter value to be converted to points.

Returns the corresponding value in points.

See also: SetDotsPerInch, InchesToPoints, PointsToCentiMeters

Show source

    proc ::Cawt::CentiMetersToPoints {cm} {

        # Convert centimeter value into points.
        #
        # cm - Floating point centimeter value to be converted to points.
        #
        # Returns the corresponding value in points.
        #
        # See also: SetDotsPerInch InchesToPoints PointsToCentiMeters

        variable dotsPerInch

        return [expr {$cm / 2.54 * double($dotsPerInch)}]
    }

#### CheckBoolean [::Cawt]Cawt, Top, Main

Check, if two boolean values are identical.

CheckBoolean expected value msg ?printCheck?

`expected` | Expected boolean value.
`value` | Test boolean value.
`msg` | Message for test case.
`printCheck` | Print message for successful test case. Optional, default `true`.

Returns true, if both boolean values are identical. If `$printCheck` is set to true, a line prepended with `"Check:`" and the message supplied in `$msg` is printed to standard output. If the check fails, return false and print message prepended with `"Error:`".

See also: CheckComObjects, CheckNumber, CheckList, CheckMatrix, CheckString

Show source

    proc ::Cawt::CheckBoolean {expected value msg {printCheck true}} {

        # Check, if two boolean values are identical.
        #
        # expected   - Expected boolean value.
        # value      - Test boolean value.
        # msg        - Message for test case.
        # printCheck - Print message for successful test case.
        #
        # Returns true, if both boolean values are identical.
        # If $printCheck is set to true, a line prepended with `"Check:`" and the
        # message supplied in $msg is printed to standard output.
        # If the check fails, return false and print message prepended with `"Error:`".
        #
        # See also: CheckComObjects CheckNumber CheckList CheckMatrix CheckString

        if { [expr bool($expected)] != [expr bool($value)] } {
            puts "Error: $msg (Expected: $expected Have: $value)"
            return false
        }
        if { $printCheck } {
            puts "Check: $msg (Expected: $expected Have: $value)"
        }
        return true
    }

#### CheckComObjects [::Cawt]Cawt, Top, Main

Check, if the number of COM objects fits expected value.

CheckComObjects expected msg ?printCheck?

`expected` | Expected number of COM objects.
`msg` | Message for test case.
`printCheck` | Print message for successful test case. Optional, default `true`.

Returns true, if the number of COM objects fits expected value. If `$printCheck` is set to true, a line prepended with `"Check:"` and the message supplied in `$msg` is printed to standard output. If the check fails, return false and print message prepended with `"Error:"`.

See also: CheckList, CheckMatrix, CheckBoolean, CheckNumber, CheckString, GetNumComObjects

Show source

    proc ::Cawt::CheckComObjects {expected msg {printCheck true}} {

        # Check, if the number of COM objects fits expected value.
        #
        # expected   - Expected number of COM objects.
        # msg        - Message for test case.
        # printCheck - Print message for successful test case.
        #
        # Returns true, if the number of COM objects fits expected value.
        # If $printCheck is set to true, a line prepended with `"Check:"` and the
        # message supplied in $msg is printed to standard output.
        # If the check fails, return false and print message prepended with `"Error:"`.
        #
        # See also: CheckList CheckMatrix CheckBoolean CheckNumber CheckString GetNumComObjects

        set value [Cawt::GetNumComObjects]
        if { $expected != $value } {
            puts "Error: $msg (Expected: $expected Have: $value)"
            return false
        }
        if { $printCheck } {
            puts "Check: $msg (Expected: $expected Have: $value)"
        }
        return true
    }

#### CheckFile [::Cawt]Cawt, Top, Main

Check, if two files are identical.

CheckFile fileName1 fileName2 msg ?printCheck?

`fileName1` | First file name.
`fileName2` | Second file name.
`msg` | Message for test case.
`printCheck` | Print message for successful test case. Optional, default `true`.

Returns true, if both files are identical. If "printCheck" is set to true, a line prepended with `"Check:"` and the message supplied in "msg" is printed to standard output. If the check fails, return false and print message prepended with `"Error:"`.

See also: CheckComObjects, CheckList, CheckMatrix, CheckBoolean, CheckNumber

Show source

    proc ::Cawt::CheckFile {fileName1 fileName2 msg {printCheck true}} {

        # Check, if two files are identical.
        #
        # fileName1  - First file name.
        # fileName2  - Second file name.
        # msg        - Message for test case.
        # printCheck - Print message for successful test case.
        #
        # Returns true, if both files are identical.
        # If "printCheck" is set to true, a line prepended with `"Check:"` and the
        # message supplied in "msg" is printed to standard output.
        # If the check fails, return false and print message prepended with `"Error:"`.
        #
        # See also: CheckComObjects CheckList CheckMatrix CheckBoolean CheckNumber

        if { ! [file isfile $fileName1] } {
            puts "Error: $msg (File not existent: \"$fileName1\")"
            return false
        }
        if { ! [file isfile $fileName2] } {
            puts "Error: $msg (File not existent: \"$fileName2\")"
            return false
        }

        if { [file size $fileName1] != [file size $fileName2] } {
            puts "Error: $msg (Expected size: [file size $fileName1] Have: [file size $fileName2])"
            return false
        }

        set fp1 [open $fileName1 "r"]
        set fp2 [open $fileName2 "r"]

        fconfigure $fp1 -translation binary
        fconfigure $fp2 -translation binary

        set retVal  0
        set bufSize 2048

        set str1 [read $fp1 $bufSize]
        while { 1 } {
            set str2 [read $fp2 $bufSize]
            if { $str1 ne $str2 } {
                # Files differ
                set retVal 0
                break
            }
            set str1 [read $fp1 $bufSize]
            if { $str1 eq "" } {
                # Files are identical
                set retVal 1
                break
            }
        }
        close $fp1
        close $fp2

        if { $retVal == 0 } {
            puts "Error: $msg (Files differ: \"[file tail $fileName1]\" \"[file tail $fileName2]\")"
            return false
        } else {
            if { $printCheck } {
                puts "Check: $msg (Files are identical: \"[file tail $fileName1]\" \"[file tail $fileName2]\")"
            }
        }
        return true
    }

#### CheckList [::Cawt]Cawt, Top, Main

Check, if two lists are identical.

CheckList expected value msg ?printCheck?

`expected` | Expected list.
`value` | Test list.
`msg` | Message for test case.
`printCheck` | Print message for successful test case. Optional, default `true`.

Returns true, if both lists are identical. If `$printCheck` is set to true, a line prepended with `"Check:"` and the message supplied in `$msg` is printed to standard output. If the check fails, return false and print message prepended with `"Error:"`.

See also: CheckComObjects, CheckMatrix, CheckBoolean, CheckNumber, CheckString

Show source

    proc ::Cawt::CheckList {expected value msg {printCheck true}} {

        # Check, if two lists are identical.
        #
        # expected   - Expected list.
        # value      - Test list.
        # msg        - Message for test case.
        # printCheck - Print message for successful test case.
        #
        # Returns true, if both lists are identical.
        # If $printCheck is set to true, a line prepended with `"Check:"` and the
        # message supplied in $msg is printed to standard output.
        # If the check fails, return false and print message prepended with `"Error:"`.
        #
        # See also: CheckComObjects CheckMatrix CheckBoolean CheckNumber CheckString

        if { [llength $expected] != [llength $value] } {
            puts "Error: $msg (List length differ. Expected: [llength $expected] Have: [llength $value])"
            return false
        }
        set index 0
        foreach exp $expected val $value {
            if { $exp != $val } {
                puts "Error: $msg (Values differ at index $index. Expected: $exp Have: $val)"
                return false
            }
            incr index
        }
        if { $printCheck } {
            if { [llength $value] <= 4 } {
                puts "Check: $msg (Expected: $expected Have: $value)"
            } else {
                puts "Check: $msg (Lists are identical. List length: [llength $value])"
            }
        }
        return true
    }

#### CheckMatrix [::Cawt]Cawt, Top, Main

Check, if two matrices are identical.

CheckMatrix expected value msg ?printCheck?

`expected` | Expected matrix.
`value` | Test matrix.
`msg` | Message for test case.
`printCheck` | Print message for successful test case. Optional, default `true`.

Returns true, if both matrices are identical. If `$printCheck` is set to true, a line prepended with `"Check:"` and the message supplied in `$msg` is printed to standard output. If the check fails, return false and print message prepended with `"Error:"`.

See also: CheckComObjects, CheckList, CheckBoolean, CheckNumber, CheckString

Show source

    proc ::Cawt::CheckMatrix {expected value msg {printCheck true}} {

        # Check, if two matrices are identical.
        #
        # expected   - Expected matrix.
        # value      - Test matrix.
        # msg        - Message for test case.
        # printCheck - Print message for successful test case.
        #
        # Returns true, if both matrices are identical.
        # If $printCheck is set to true, a line prepended with `"Check:"` and the
        # message supplied in $msg is printed to standard output.
        # If the check fails, return false and print message prepended with `"Error:"`.
        #
        # See also: CheckComObjects CheckList CheckBoolean CheckNumber CheckString

        if { [llength $expected] != [llength $value] } {
            puts "Error: $msg (Matrix rows differ. Expected: [llength $expected] Have: [llength $value])"
            return false
        }
        set row 0
        foreach expRow $expected valRow $value {
            set col 0
            foreach exp $expRow val $valRow {
                if { $exp != $val } {
                    puts "Error: $msg (Values differ at row/col $row/$col. Expected: $exp Have: $val)"
                    return false
                }
                incr col
            }
            incr row
        }
        if { $printCheck } {
            puts "Check: $msg (Matrices are identical. Matrix rows: [llength $value])"
        }
        return true
    }

#### CheckNumber [::Cawt]Cawt, Top, Main

Check, if two numerical values are identical.

CheckNumber expected value msg ?printCheck?

`expected` | Expected numeric value.
`value` | Test numeric value.
`msg` | Message for test case.
`printCheck` | Print message for successful test case. Optional, default `true`.

Returns true, if both numeric values are identical. If `$printCheck` is set to true, a line prepended with `"Check:"` and the message supplied in `$msg` is printed to standard output. If the check fails, return false and print message prepended with `"Error:"`.

See also: CheckComObjects, CheckBoolean, CheckList, CheckMatrix, CheckString

Show source

    proc ::Cawt::CheckNumber {expected value msg {printCheck true}} {

        # Check, if two numerical values are identical.
        #
        # expected   - Expected numeric value.
        # value      - Test numeric value.
        # msg        - Message for test case.
        # printCheck - Print message for successful test case.
        #
        # Returns true, if both numeric values are identical.
        # If $printCheck is set to true, a line prepended with `"Check:"` and the
        # message supplied in $msg is printed to standard output.
        # If the check fails, return false and print message prepended with `"Error:"`.
        #
        # See also: CheckComObjects CheckBoolean CheckList CheckMatrix CheckString

        if { $expected != $value } {
            puts "Error: $msg (Expected: $expected Have: $value)"
            return false
        }
        if { $printCheck } {
            puts "Check: $msg (Expected: $expected Have: $value)"
        }
        return true
    }

#### CheckString [::Cawt]Cawt, Top, Main

Check, if two string values are identical.

CheckString expected value msg ?printCheck?

`expected` | Expected string value.
`value` | Test string value.
`msg` | Message for test case.
`printCheck` | Print message for successful test case. Optional, default `true`.

Returns true, if both string values are identical. If "printCheck" is set to true, a line prepended with `"Check:"` and the message supplied in "msg" is printed to standard output. If the check fails, return false and print message prepended with `"Error:"`.

See also: CheckComObjects, CheckList, CheckMatrix, CheckBoolean, CheckNumber

Show source

    proc ::Cawt::CheckString {expected value msg {printCheck true}} {

        # Check, if two string values are identical.
        #
        # expected   - Expected string value.
        # value      - Test string value.
        # msg        - Message for test case.
        # printCheck - Print message for successful test case.
        #
        # Returns true, if both string values are identical.
        # If "printCheck" is set to true, a line prepended with `"Check:"` and the
        # message supplied in "msg" is printed to standard output.
        # If the check fails, return false and print message prepended with `"Error:"`.
        #
        # See also: CheckComObjects CheckList CheckMatrix CheckBoolean CheckNumber

        if { $expected ne $value } {
            puts "Error: $msg (Expected: \"$expected\" Have: \"$value\")"
            return false
        }
        if { $printCheck } {
            puts "Check: $msg (Expected: \"$expected\" Have: \"$value\")"
        }
        return true
    }

#### ClipboardToImg [::Cawt]Cawt, Top, Main

Copy the clipboard content into a photo image.

ClipboardToImg

The photo image identifier is returned, if the clipboard content could be read correctly. Otherwise an error is thrown.

Note: The image data in the clipboard must be in `BMP` format. Therefore it needs the `Img` extension. The image must be freed by the caller with `image delete`, if not needed anymore.

Returns the photo image identifier.

See also: ImgToClipboard

Show source

    proc ::Cawt::ClipboardToImg {} {

        # Copy the clipboard content into a photo image.
        #
        # The photo image identifier is returned, if the clipboard
        # content could be read correctly. Otherwise an error is thrown.
        #
        # **Note:**
        # The image data in the clipboard must be in `BMP` format.
        # Therefore it needs the `Img` extension.
        # The image must be freed by the caller with `image delete`,
        # if not needed anymore.
        #
        # Returns the photo image identifier.
        #
        # See also: ImgToClipboard

        variable sBmpHeaderSize

        set retVal [catch { package require Img } version]
        if { $retVal != 0 } {
            error "ClipboardToImg: Package Img not available."
        }

        twapi::open_clipboard

        # Assume clipboard content is in format 8 (CF_DIB)
        set retVal [catch { twapi::read_clipboard 8 } clipData]
        if { $retVal != 0 } {
            error "ClipboardToImg: Invalid or no content in clipboard"
        }

        # First parse the bitmap data to collect header information
        binary scan $clipData "iiissiiiiii"  size width height planes bitcount compression sizeimage  xpelspermeter ypelspermeter clrused clrimportant

        # We only handle BITMAPINFOHEADER right now (size must be 40)
        if { $size != 40 } {
            error "ClipboardToImg: Unsupported bitmap format. Header size=$size"
        }

        # We need to figure out the offset to the actual bitmap data
        # from the start of the file header. For this we need to know the
        # size of the color table which directly follows the BITMAPINFOHEADER
        if { $bitcount == 0 } {
            error "ClipboardToImg: Unsupported format: implicit JPEG or PNG"
        } elseif { $bitcount == 1 } {
            set color_table_size 2
        } elseif { $bitcount == 4 } {
            # TBD - Not sure if this is the size or the max size
            set color_table_size 16
        } elseif { $bitcount == 8 } {
            # TBD - Not sure if this is the size or the max size
            set color_table_size 256
        } elseif { $bitcount == 16 || $bitcount == 32 } {
            if { $compression == 0 } {
                # BI_RGB
                set color_table_size $clrused
            } elseif { $compression == 3 } {
                # BI_BITFIELDS
                set color_table_size 3
            } else {
                error "ClipboardToImg: Unsupported compression type '$compression' for bitcount value $bitcount"
            }
        } elseif { $bitcount == 24 } {
            set color_table_size $clrused
        } else {
            error "ClipboardToImg: Unsupported value '$bitcount' in bitmap bitcount field"
        }

        set phImg [image create photo]
        set bitmap_file_offset [expr {$sBmpHeaderSize + $size + ($color_table_size * 4)}]
        set filehdr [binary format "a2 i x2 x2 i"  "BM" [expr {$sBmpHeaderSize + [string length $clipData]}]  $bitmap_file_offset]

        append filehdr $clipData
        $phImg put $filehdr -format bmp

        twapi::close_clipboard
        return $phImg
    }

#### ConcatFiles [::Cawt]Cawt, Top, Main

Concatenates files into one file.

ConcatFiles outFile ?args?

`outFile` | Output file name.
`args` | List of input files.

Concatenate the contents of the files specified in `$args` into one file `$outFile`.

Returns no value. If the output file could not be opened for writing or any of the input files could not be openend for reading, an error is thrown.

See also: IsUnicodeFile, SplitFile

Show source

    proc ::Cawt::ConcatFiles {outFile args} {

        # Concatenates files into one file.
        #
        # outFile - Output file name.
        # args    - List of input files.
        #
        # Concatenate the contents of the files specified in $args into one
        # file $outFile.
        #
        # Returns no value.
        # If the output file could not be opened for writing
        # or any of the input files could not be openend for reading, an error
        # is thrown.
        #
        # See also: IsUnicodeFile SplitFile

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

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

#### CountWords [::Cawt]Cawt, Top, Main

Count words contained in a string.

CountWords str ?args?

`str` | String to be searched.
`args` | Options described below.
`-maxlength <int>` | Only count words having less than maxlength characters. Default: No limit.
`-minlength <int>` | Only count words having more than minlength characters. Default: No limit.
`-shownumbers <bool>` | If set to false, only count words which are no numbers.
`-sortmode <string>` | Sorting mode of output list. Default: length. Possible values: dictionary, length.

Count words contained in a string.

Notes:

- The definition of a word is like in Tcl command `string wordend`.
- This procedure can be called as a coroutine. It yields every 1000 bytes processed. The yield return value is the number of bytes already processed. See test script `Core-04_String.tcl` for an usage example.

Returns a key-value list containing the found words and their corresponding count.

See also: ::Word::CountWords

Show source

    proc ::Cawt::CountWords {str args} {

        # Count words contained in a string.
        #
        # str  - String to be searched.
        # args - Options described below.
        #
        # -sortmode <string>  - Sorting mode of output list.
        #                       Default: length. Possible values: dictionary, length.
        # -minlength <int>    - Only count words having more than minlength characters.
        #                       Default: No limit.
        # -maxlength <int>    - Only count words having less than maxlength characters.
        #                       Default: No limit.
        # -shownumbers <bool> - If set to false, only count words which are no numbers.
        #
        # Returns a key-value list containing the found words and their
        # corresponding count.
        #
        # Count words contained in a string.
        #
        # Notes:
        #  * The definition of a word is like in Tcl command `string wordend`.
        #  * This procedure can be called as a coroutine. It yields
        #    every 1000 bytes processed. The yield return value is the
        #    number of bytes already processed.
        #    See test script `Core-04_String.tcl` for an usage example.
        #
        # See also: ::Word::CountWords

        set opts [dict create  -sortmode    "length"  -minlength   -1  -maxlength   -1  -shownumbers true  ]
        foreach { key value } $args {
            if { $value eq "" } {
                error "CountWords: No value specified for key \"$key\""
            }
            if { [dict exists $opts $key] } {
                dict set opts $key $value
            } else {
                error "CountWords: Unknown option \"$key\" specified"
            }
        }

        set wordStart 0
        set wordEnd   0

        set strLen [string length $str]
        set percent 0
        if { [info coroutine] ne "" } {
            yield 0
        }
        set thousands 1000
        set minLength [dict get $opts "-minlength"]
        set maxLength [dict get $opts "-maxlength"]
        while { $wordEnd < $strLen } {
            set wordEnd   [string wordend $str $wordStart]
            set foundWord [string trim [string range $str $wordStart [expr { $wordEnd - 1}]]]
            set wordStart $wordEnd
            set wordLen [string length $foundWord]
            if { ( $minLength < 0 || $wordLen >= $minLength ) &&  ( $maxLength < 0 || $wordLen <= $maxLength ) } {
                if { ! [dict get $opts "-shownumbers"] && [string is digit $foundWord] } {
                    continue
                }
                incr wordHash($foundWord)
            }
            if { $wordEnd > $thousands } {
                incr thousands 1000
                if { [info coroutine] ne "" } {
                    yield $wordEnd
                }
            }
        }
        if { [info coroutine] ne "" } {
            yield $strLen
        }

        set sortedList [lsort -dictionary [array names wordHash]]
        if { [dict get $opts "-sortmode"] eq "length" } {
            set sortedList [lsort -command Cawt::_StringLenCompare $sortedList]
        }

        set keyValueList [list]
        foreach word $sortedList {
            lappend keyValueList $word $wordHash($word)
        }
        return $keyValueList
    }

#### Destroy [::Cawt]Cawt, Top, Main

Destroy one or all COM objects.

Destroy ?comObj?

`comObj` | The COM object to be destroyed. Optional, default `""`.

If `$comObj` is an empty string, all existing COM objects are destroyed. Otherwise only the specified COM object is destroyed.

Note:

- Twapi does not clean up generated COM object identifiers, so you have to put a call to Destroy at the end of your CAWT script. For further details about COM objects and their lifetime see the Twapi documentation.

Returns no value.

See also: PushComObjects, PopComObjects

Show source

    proc ::Cawt::Destroy {{comObj {}}} {

        # Destroy one or all COM objects.
        #
        # comObj - The COM object to be destroyed.
        #
        # If $comObj is an empty string, all existing COM objects are destroyed.
        # Otherwise only the specified COM object is destroyed.
        #
        # **Note:**
        #   * Twapi does not clean up generated COM object identifiers, so you
        #     have to put a call to Destroy at the end of your CAWT script.
        #     For further details about COM objects and their lifetime see the Twapi
        #     documentation.
        #
        # Returns no value.
        #
        # See also: PushComObjects PopComObjects

        if { $comObj ne "" } {
            $comObj -destroy
        } else {
            foreach obj [Cawt::GetComObjects] {
                $obj -destroy
            }
        }
    }

#### GetColor [::Cawt]Cawt, Top, Main

Convert a color representation into an Office color number.

GetColor ?args?

`args` | A valid color representation.

Colors can be specified in one of the following representations:

Name | A valid Tcl color name string, ex. `black`.
Hexadecimal | A valid Tcl hexadecimal string, ex. `#00FFAA`.
RGB | 3 integer values in the range 0 .. 255.
Office number | An integer number with encoded RGB values.

Returns the color as an Office color number.

See also: GetColor, GetColorNames, IsHexColor, IsNameColor, IsRgbColor, IsOfficeColor

Show source

    proc ::Cawt::GetColor {args} {

        # Convert a color representation into an Office color number.
        #
        # args - A valid color representation.
        #
        # Colors can be specified in one of the following representations:
        # Name          - A valid Tcl color name string, ex. `black`.
        # Hexadecimal   - A valid Tcl hexadecimal string, ex. `#00FFAA`.
        # RGB           - 3 integer values in the range 0 .. 255.
        # Office number - An integer number with encoded RGB values.
        #
        # Returns the color as an Office color number.
        #
        # See also: GetColor GetColorNames IsHexColor IsNameColor IsRgbColor IsOfficeColor

        variable sColorNameList

        if { [llength $args] == 1 } {
            set color [lindex $args 0]
            if { [Cawt IsNameColor $color] } {
                set rgbList $sColorNameList($color)
                return [Cawt RgbToOfficeColor  [lindex $rgbList 0]  [lindex $rgbList 1]  [lindex $rgbList 2]]
            } elseif { [Cawt IsHexColor $color] } {
                scan $color "#%2x%2x%2x" r g b
                return [Cawt RgbToOfficeColor $r $g $b]
            } elseif { [Cawt IsOfficeColor $color] } {
                return $color
            }
        } elseif { [llength $args] == 3 } {
            return [Cawt RgbToOfficeColor {*}$args]
        }
        error "GetColor: Invalid color representation \"$args\" specified."
    }

#### GetColorNames [::Cawt]Cawt, Top, Main

Get all supported Tcl color names.

GetColorNames

Returns a sorted list of all supported Tcl color names.

See also: IsNameColor

Show source

    proc ::Cawt::GetColorNames {} {

        # Get all supported Tcl color names.
        #
        # Returns a sorted list of all supported Tcl color names.
        #
        # See also: IsNameColor

        variable sColorNameList

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

#### GetComObjects [::Cawt]Cawt, Top, Main

Get the COM objects currently in use as a list.

GetComObjects

Returns the COM objects currently in use as a list.

See also: IsComObject, GetNumComObjects, PrintNumComObjects, Destroy

Show source

    proc ::Cawt::GetComObjects {} {

        # Get the COM objects currently in use as a list.
        #
        # Returns the COM objects currently in use as a list.
        #
        # See also: IsComObject GetNumComObjects PrintNumComObjects Destroy

        return [twapi::comobj_instances]
    }

#### GetDotsPerInch [::Cawt]Cawt, Top, Main

Get the dots-per-inch value used for conversions.

GetDotsPerInch

Returns the dots-per-inch value used for conversions.

See also: SetDotsPerInch

Show source

    proc ::Cawt::GetDotsPerInch {} {

        # Get the dots-per-inch value used for conversions.
        #
        # Returns the dots-per-inch value used for conversions.
        #
        # See also: SetDotsPerInch

        variable dotsPerInch

        return $dotsPerInch
    }

#### GetNumComObjects [::Cawt]Cawt, Top, Main

Get the number of COM objects currently in use.

GetNumComObjects

Returns the number of COM objects currently in use.

See also: IsComObject, GetComObjects, PrintNumComObjects, Destroy

Show source

    proc ::Cawt::GetNumComObjects {} {

        # Get the number of COM objects currently in use.
        #
        # Returns the number of COM objects currently in use.
        #
        # See also: IsComObject GetComObjects PrintNumComObjects Destroy

        return [llength [Cawt::GetComObjects]]
    }

#### GetOrCreateApp [::Cawt]Cawt, Top, Main

Use or create an instance of an application.

GetOrCreateApp appName useExistingFirst

`appName` | The name of the application to be created or used.
`useExistingFirst` | Prefer an already running application.

Application names supported and tested with CAWT are:

- `Excel.Application`
- `GoogleEarth.ApplicationGE`
- `InternetExplorer.Application`
- `Matlab.Application`
- `MODI.Document`
- `Outlook.Application`
- `PowerPoint.Application`
- `Word.Application`

Note:

- There are higher level functions `Open` and `OpenNew` for the CAWT sub-packages.

If `$useExistingFirst` is set to true, it is checked, if an application instance is already running. If true, this instance is used. If no running application is available, a new instance is started.

Returns the application identifier.

See also: KillApp

Show source

    proc ::Cawt::GetOrCreateApp {appName useExistingFirst} {

        # Use or create an instance of an application.
        #
        # appName          - The name of the application to be created or used.
        # useExistingFirst - Prefer an already running application.
        #
        # Application names supported and tested with CAWT are:
        #   * `Excel.Application`
        #   * `GoogleEarth.ApplicationGE`
        #   * `InternetExplorer.Application`
        #   * `Matlab.Application`
        #   * `MODI.Document`
        #   * `Outlook.Application`
        #   * `PowerPoint.Application`
        #   * `Word.Application`
        #
        # **Note:**
        #   * There are higher level functions `Open` and `OpenNew` for the
        #     CAWT sub-packages.
        #
        # If $useExistingFirst is set to true, it is checked, if an application
        # instance is already running. If true, this instance is used.
        # If no running application is available, a new instance is started.
        #
        # Returns the application identifier.
        #
        # See also: KillApp

        set foundApp false
        if { ! [HavePkg "twapi"] } {
            error "Cannot use $appName. No Twapi extension available."
        }
        if { $useExistingFirst } {
            set retVal [catch {twapi::comobj $appName -active} appId]
            if { $retVal == 0 } {
                set foundApp true
            }
        }
        if { $foundApp == false } {
            set retVal [catch {twapi::comobj $appName} appId]
        }
        if { $foundApp == true || $retVal == 0 } {
            return $appId
        }
        error "Cannot get or create $appName object."
    }

#### GetPkgVersion [::Cawt]Cawt, Top, Main

Get the version of a CAWT sub-package.

GetPkgVersion pkgName

`pkgName` | The name of the sub-package

Returns the version of the CAWT sub-package as a string. If the package is not available, an empty string is returned.

See also: HavePkg

Show source

    proc ::Cawt::GetPkgVersion {pkgName} {

        # Get the version of a CAWT sub-package.
        #
        # pkgName - The name of the sub-package
        #
        # Returns the version of the CAWT sub-package as a string.
        # If the package is not available, an empty string is returned.
        #
        # See also: HavePkg

        variable pkgInfo

        set retVal ""
        if { [HavePkg $pkgName] } {
            set retVal $pkgInfo($pkgName,version)
        }
        return $retVal
    }

#### GetProgramByExtension [::Cawt]Cawt, Top, Main

Get path to program for a given file extension.

GetProgramByExtension extension

`extension` | The extension string (including a dot, ex. `.pdf`).

Returns the path to the program which is associated in the Windows registry with the file extension.

Show source

    proc ::Cawt::GetProgramByExtension {extension} {

        # Get path to program for a given file extension.
        #
        # extension - The extension string (including a dot, ex. `.pdf`).
        #
        # Returns the path to the program which is associated in the Windows registry
        # with the file extension.

        set retVal [catch { package require registry } version]
        if { $retVal != 0 } {
            return ""
        }
        # Read the type name.
        set type [registry get HKEY_CLASSES_ROOT\\$extension {}]
        # Work out where to look for the program.
        set path "HKEY_CLASSES_ROOT\\$type\\Shell\\Open\\command"
        # Read the program name.
        set prog [registry get $path {}]

        set lastSpaceIndex [expr {[string last " " $prog] - 1}]
        set progName [string trim [string range $prog 0 $lastSpaceIndex] "\""]
        if { [file executable $progName] } {
            return $progName
        }
        return ""
    }

#### GetTmpDir [::Cawt]Cawt, Top, Main

GetTmpDir

Show source

    proc ::Cawt::GetTmpDir {} {

        global tcl_platform env

        set tmpDir ""
        # Try different environment variables.
        if { [info exists env(TMP)] && [file isdirectory $env(TMP)] } {
            set tmpDir $env(TMP)
        } elseif { [info exists env(TEMP)] && [file isdirectory $env(TEMP)] } {
            set tmpDir $env(TEMP)
        } elseif { [info exists env(TMPDIR)] && [file isdirectory $env(TMPDIR)] } {
            set tmpDir $env(TMPDIR)
        } else {
            # Last resort. These directories should be available at least.
            switch $tcl_platform(platform) {
                unix {
                    if { [file isdirectory "/tmp"] } {
                        set tmpDir "/tmp"
                    }
                }
            }
        }
        return [file nativename $tmpDir]
    }

#### HavePkg [::Cawt]Cawt, Top, Main

Check, if a CAWT sub-package is available.

HavePkg pkgName

`pkgName` | The name of the sub-package.

Returns true, if sub-package pkgName was loaded successfully. Otherwise returns false.

See also: GetPkgVersion

Show source

    proc ::Cawt::HavePkg {pkgName} {

        # Check, if a CAWT sub-package is available.
        #
        # pkgName - The name of the sub-package.
        #
        # Returns true, if sub-package pkgName was loaded successfully.
        # Otherwise returns false.
        #
        # See also: GetPkgVersion

        variable pkgInfo

        if { [info exists pkgInfo($pkgName,avail)] } {
            return $pkgInfo($pkgName,avail)
        }
        return false
    }

#### ImgToClipboard [::Cawt]Cawt, Top, Main

Copy a photo image into the clipboard.

ImgToClipboard phImg

`phImg` | The photo image identifier.

If the image could not be copied to the clipboard correctly, an error is thrown.

Note: The image data is copied to the clipboard in `BMP` format. Therefore it needs the `Img` and `base64` extensions.

Returns no value.

See also: ClipboardToImg

Show source

    proc ::Cawt::ImgToClipboard {phImg} {

        # Copy a photo image into the clipboard.
        #
        # phImg - The photo image identifier.
        #
        # If the image could not be copied to the clipboard correctly,
        # an error is thrown.
        #
        # **Note:**
        # The image data is copied to the clipboard in `BMP` format.
        # Therefore it needs the `Img` and `base64` extensions.
        #
        # Returns no value.
        #
        # See also: ClipboardToImg

        variable sBmpHeaderSize

        set retVal [catch {package require Img} version]
        if { $retVal != 0 } {
            error "ImgToClipboard: Package Img not available."
        }
        set retVal [catch {package require base64} version]
        if { $retVal != 0 } {
            error "ImgToClipboard: Package Base64 not available."
        }

        # First 14 bytes are bitmapfileheader.
        set data [string range [base64::decode [$phImg data -format bmp]] $sBmpHeaderSize end]
        twapi::open_clipboard
        twapi::empty_clipboard
        twapi::write_clipboard 8 $data
        twapi::close_clipboard
    }

#### InchesToPoints [::Cawt]Cawt, Top, Main

Convert inch value into points.

InchesToPoints inches

`inches` | Floating point inch value to be converted to points.

Returns the corresponding value in points.

See also: SetDotsPerInch, CentiMetersToPoints, PointsToInches

Show source

    proc ::Cawt::InchesToPoints {inches} {

        # Convert inch value into points.
        #
        # inches - Floating point inch value to be converted to points.
        #
        # Returns the corresponding value in points.
        #
        # See also: SetDotsPerInch CentiMetersToPoints PointsToInches

        variable dotsPerInch

        return [expr {$inches * double($dotsPerInch)}]
    }

#### IsComObject [::Cawt]Cawt, Top, Main

Check, if a COM object is valid.

IsComObject comObj

`comObj` | The COM object.

Returns true, if `$comObj` is a valid object. Otherwise returns false.

See also: GetComObjects, GetNumComObjects, PrintNumComObjects

Show source

    proc ::Cawt::IsComObject {comObj} {

        # Check, if a COM object is valid.
        #
        # comObj - The COM object.
        #
        # Returns true, if $comObj is a valid object.
        # Otherwise returns false.
        #
        # See also: GetComObjects GetNumComObjects PrintNumComObjects

        return [expr { [twapi::comobj? $comObj] && ! [$comObj -isnull] } ]
    }

#### IsHexColor [::Cawt]Cawt, Top, Main

Check, if specified color is a valid Tcl hexadecimal color string.

IsHexColor color

`color` | The Tcl color string as hexadecimal representation, ex. `#0ACCF0`.

Returns true, if supplied string is a valid color string, otherwise false.

See also: GetColor, GetColorNames, IsNameColor, IsRgbColor, IsOfficeColor

Show source

    proc ::Cawt::IsHexColor {color} {

        # Check, if specified color is a valid Tcl hexadecimal color string.
        #
        # color - The Tcl color string as hexadecimal representation, ex. `#0ACCF0`.
        #
        # Returns true, if supplied string is a valid color string, otherwise false.
        #
        # See also: GetColor GetColorNames IsNameColor IsRgbColor IsOfficeColor

        if { [string index $color 0] eq "#" } {
            scan $color "#%2x%2x%2x" r g b
            return [Cawt::_IsValidRgb $r $g $b]
        }
        return false
    }

#### IsNameColor [::Cawt]Cawt, Top, Main

Check, if specified color is a valid Tcl color name.

IsNameColor color

`color` | The Tcl color name as a string, ex. `black`.

Returns true, if supplied string is a valid color name, otherwise false.

See also: GetColor, GetColorNames, IsHexColor, IsRgbColor, IsOfficeColor

Show source

    proc ::Cawt::IsNameColor {color} {

        # Check, if specified color is a valid Tcl color name.
        #
        # color - The Tcl color name as a string, ex. `black`.
        #
        # Returns true, if supplied string is a valid color name, otherwise false.
        #
        # See also: GetColor GetColorNames IsHexColor IsRgbColor IsOfficeColor

        variable sColorNameList

        return [info exists sColorNameList($color)]
    }

#### IsoDateToOfficeDate [::Cawt]Cawt, Top, Main

Return ISO date string as Office date.

IsoDateToOfficeDate isoDate

`isoDate` | Date string in format `%Y-%m-%d %H:%M:%S`.

Returns corresponding date as floating point number representing days since 1900/01/01.

See also: OfficeDateToIsoDate, IsoDateToSeconds, IsoDateToXmlDate

Show source

    proc ::Cawt::IsoDateToOfficeDate {isoDate} {

        # Return ISO date string as Office date.
        #
        # isoDate - Date string in format `%Y-%m-%d %H:%M:%S`.
        #
        # Returns corresponding date as floating point number
        # representing days since 1900/01/01.
        #
        # See also: OfficeDateToIsoDate IsoDateToSeconds IsoDateToXmlDate

        return [Cawt::SecondsToOfficeDate [Cawt::IsoDateToSeconds $isoDate]]
    }

#### IsoDateToOutlookDate [::Cawt]Cawt, Top, Main

Obsolete: Replaced with IsoDateToOfficeDate in version 2.4.4

IsoDateToOutlookDate isoDate

`isoDate` | Date string in format `%Y-%m-%d %H:%M:%S`.

Returns corresponding date as floating point number representing days since `1900/01/01`.

See also: OutlookDateToIsoDate, IsoDateToSeconds, IsoDateToXmlDate

Show source

    proc ::Cawt::IsoDateToOutlookDate {isoDate} {

        # Obsolete: Replaced with [IsoDateToOfficeDate] in version 2.4.4
        #
        # isoDate - Date string in format `%Y-%m-%d %H:%M:%S`.
        #
        # Returns corresponding date as floating point number
        # representing days since `1900/01/01`.
        #
        # See also: OutlookDateToIsoDate IsoDateToSeconds IsoDateToXmlDate

        return [Cawt::SecondsToOfficeDate [Cawt::IsoDateToSeconds $isoDate]]
    }

#### IsoDateToSeconds [::Cawt]Cawt, Top, Main

Return ISO date string as seconds.

IsoDateToSeconds isoDate

`isoDate` | Date string in format `%Y-%m-%d %H:%M:%S`.

Returns corresponding seconds as integer.

See also: SecondsToIsoDate, XmlDateToSeconds, OfficeDateToSeconds

Show source

    proc ::Cawt::IsoDateToSeconds {isoDate} {

        # Return ISO date string as seconds.
        #
        # isoDate - Date string in format `%Y-%m-%d %H:%M:%S`.
        #
        # Returns corresponding seconds as integer.
        #
        # See also: SecondsToIsoDate XmlDateToSeconds OfficeDateToSeconds

        return [clock scan $isoDate -format {%Y-%m-%d %H:%M:%S}]
    }

#### IsoDateToXmlDate [::Cawt]Cawt, Top, Main

Return ISO date string as XML date string.

IsoDateToXmlDate isoDate

`isoDate` | Date string in format `%Y-%m-%d %H:%M:%S`.

Returns corresponding date as XML date string.

See also: XmlDateToIsoDate, IsoDateToSeconds, IsoDateToOfficeDate

Show source

    proc ::Cawt::IsoDateToXmlDate {isoDate} {

        # Return ISO date string as XML date string.
        #
        # isoDate - Date string in format `%Y-%m-%d %H:%M:%S`.
        #
        # Returns corresponding date as XML date string.
        #
        # See also: XmlDateToIsoDate IsoDateToSeconds IsoDateToOfficeDate

        return [Cawt::SecondsToXmlDate [Cawt::IsoDateToSeconds $isoDate]]
    }

#### IsOfficeColor [::Cawt]Cawt, Top, Main

Check, if specified color is a valid Office color number.

IsOfficeColor color

`color` | The Office color number.

Returns true, if supplied string is a valid color string, otherwise false.

See also: GetColor, GetColorNames, IsHexColor, IsNameColor, IsRgbColor

Show source

    proc ::Cawt::IsOfficeColor {color} {

        # Check, if specified color is a valid Office color number.
        #
        # color - The Office color number.
        #
        # Returns true, if supplied string is a valid color string, otherwise false.
        #
        # See also: GetColor GetColorNames IsHexColor IsNameColor IsRgbColor

        if { [string is integer $color] } {
            set r [expr { (int ($color))       & 0xFF }]
            set g [expr { (int ($color) >>  8) & 0xFF }]
            set b [expr { (int ($color) >> 16) & 0xFF }]
            return [Cawt::_IsValidRgb $r $g $b]
        }
        return false
    }

#### IsRgbColor [::Cawt]Cawt, Top, Main

Check, if specified color is a valid RGB representation.

IsRgbColor r g b

`r` | The red component of the color.
`g` | The green component of the color.
`b` | The blue component of the color.

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

Returns true, if supplied values are in the supported range, otherwise false.

See also: GetColor, GetColorNames, IsHexColor, IsNameColor, IsOfficeColor

Show source

    proc ::Cawt::IsRgbColor {r g b} {

        # Check, if specified color is a valid RGB representation.
        #
        # r - The red component of the color.
        # g - The green component of the color.
        # b - The blue component of the color.
        #
        # The r, g and b values are specified as integers in the
        # range 0 .. 255.
        #
        # Returns true, if supplied values are in the supported range, otherwise false.
        #
        # See also: GetColor GetColorNames IsHexColor IsNameColor IsOfficeColor

        return [Cawt::_IsValidRgb $r $g $b]
    }

#### IsUnicodeFile [::Cawt]Cawt, Top, Main

Check, if a file is encoded in Unicode.

IsUnicodeFile fileName

`fileName` | File to check encoding.

Unicode encoding is detected by checking the BOM. If the first two bytes are `FF FE`, the file seems to be a Unicode file.

Returns true, if file is encoded in Unicode, otherwise false.

See also: SplitFile, ConcatFiles

Show source

    proc ::Cawt::IsUnicodeFile {fileName} {

        # Check, if a file is encoded in Unicode.
        #
        # fileName - File to check encoding.
        #
        # Unicode encoding is detected by checking the BOM.
        # If the first two bytes are `FF FE`, the file seems to be
        # a Unicode file.
        #
        # Returns true, if file is encoded in Unicode, otherwise false.
        #
        # See also: SplitFile ConcatFiles

        set catchVal [catch {open $fileName r} fp]
        if { $catchVal != 0 } {
            error "Could not open file \"$fileName\" for reading."
        }
        fconfigure $fp -translation binary
        set bom [read $fp 2]
        close $fp
        binary scan $bom "cc" bom1 bom2
        set bom1 [expr {$bom1 & 0xFF}]
        set bom2 [expr {$bom2 & 0xFF}]
        if { [format "%02X%02X" $bom1 $bom2] eq "FFFE" } {
            return true
        }
        return false
    }

#### IsValidId [::Cawt]Cawt, Top, Main

Obsolete: Replaced with IsComObject in version 2.0.0

IsValidId comObj

`comObj` | Not documented.

Show source

    proc ::Cawt::IsValidId {comObj} {

        # Obsolete: Replaced with [IsComObject] in version 2.0.0

        return [IsComObject $comObj]
    }

#### KillApp [::Cawt]Cawt, Top, Main

Kill all running instances of an application.

KillApp progName

`progName` | The application's program name, as shown in the task manager.

Returns no value.

See also: GetOrCreateApp

Show source

    proc ::Cawt::KillApp {progName} {

        # Kill all running instances of an application.
        #
        # progName - The application's program name, as shown in the task manager.
        #
        # Returns no value.
        #
        # See also: GetOrCreateApp

        set pids [concat [twapi::get_process_ids -name $progName]  [twapi::get_process_ids -path $progName]]
        foreach pid $pids {
            # Catch the error in case process does not exist any more
            catch {twapi::end_process $pid -force}
        }
    }

#### OfficeColorToRgb [::Cawt]Cawt, Top, Main

Convert an Office color number into a RGB color list.

OfficeColorToRgb color

`color` | The Office color number.

Returns the color as a list of r, b and b values. The r, g and b values are returned as integers in the range 0 .. 255.

See also: RgbToOfficeColor, GetColor

Show source

    proc ::Cawt::OfficeColorToRgb {color} {

        # Convert an Office color number into a RGB color list.
        #
        # color - The Office color number.
        #
        # Returns the color as a list of r, b and b values.
        # The r, g and b values are returned as integers in the
        # range 0 .. 255.
        #
        # See also: RgbToOfficeColor GetColor

        set r [expr { (int ($color))       & 0xFF }]
        set g [expr { (int ($color) >>  8) & 0xFF }]
        set b [expr { (int ($color) >> 16) & 0xFF }]
        return [list $r $g $b]
    }

#### OfficeDateToIsoDate [::Cawt]Cawt, Top, Main

Return Office date as ISO date string.

OfficeDateToIsoDate officeDate

`officeDate` | Floating point number representing days since `1900/01/01`.

Returns corresponding date as ISO date string.

See also: IsoDateToOfficeDate, OfficeDateToSeconds

Show source

    proc ::Cawt::OfficeDateToIsoDate {officeDate} {

        # Return Office date as ISO date string.
        #
        # officeDate - Floating point number representing days since `1900/01/01`.
        #
        # Returns corresponding date as ISO date string.
        #
        # See also: IsoDateToOfficeDate OfficeDateToSeconds

        return [Cawt::SecondsToIsoDate [Cawt::OfficeDateToSeconds $officeDate]]
    }

#### OfficeDateToSeconds [::Cawt]Cawt, Top, Main

Return Office date as seconds.

OfficeDateToSeconds officeDate

`officeDate` | Floating point number representing days since `1900/01/01`.

Returns corresponding seconds as integer.

See also: SecondsToOfficeDate, IsoDateToSeconds, XmlDateToSeconds

Show source

    proc ::Cawt::OfficeDateToSeconds {officeDate} {

        # Return Office date as seconds.
        #
        # officeDate - Floating point number representing days since `1900/01/01`.
        #
        # Returns corresponding seconds as integer.
        #
        # See also: SecondsToOfficeDate IsoDateToSeconds XmlDateToSeconds

        variable sOfficeDate

        set diffDays [expr { $officeDate - $sOfficeDate(Day) }]
        return [expr { $sOfficeDate(Sec) + int ($diffDays * 60.0 * 60.0 * 24.0) }]
    }

#### OutlookDateToIsoDate [::Cawt]Cawt, Top, Main

Obsolete: Replaced with OfficeDateToIsoDate in version 2.4.4

OutlookDateToIsoDate outlookDate

`outlookDate` | Floating point number representing days since `1900/01/01`.

Returns corresponding date as ISO date string.

See also: IsoDateToOutlookDate, OutlookDateToSeconds

Show source

    proc ::Cawt::OutlookDateToIsoDate {outlookDate} {

        # Obsolete: Replaced with [OfficeDateToIsoDate] in version 2.4.4
        #
        # outlookDate - Floating point number representing days since `1900/01/01`.
        #
        # Returns corresponding date as ISO date string.
        #
        # See also: IsoDateToOutlookDate OutlookDateToSeconds

        return [Cawt::SecondsToIsoDate [Cawt::OfficeDateToSeconds $outlookDate]]
    }

#### OutlookDateToSeconds [::Cawt]Cawt, Top, Main

Obsolete: Replaced with OfficeDateToSeconds in version 2.4.4

OutlookDateToSeconds outlookDate

`outlookDate` | Floating point number representing days since `1900/01/01`.

Returns corresponding seconds as integer.

See also: SecondsToOutlookDate, IsoDateToSeconds, XmlDateToSeconds

Show source

    proc ::Cawt::OutlookDateToSeconds {outlookDate} {

        # Obsolete: Replaced with [OfficeDateToSeconds] in version 2.4.4
        #
        # outlookDate - Floating point number representing days since `1900/01/01`.
        #
        # Returns corresponding seconds as integer.
        #
        # See also: SecondsToOutlookDate IsoDateToSeconds XmlDateToSeconds

        return [Cawt::OfficeDateToSeconds $outlookDate]
    }

#### PointsToCentiMeters [::Cawt]Cawt, Top, Main

Convert value in points into centimeters.

PointsToCentiMeters points

`points` | Floating point value to be converted to centimeters.

Returns the corresponding value in centimeters.

See also: SetDotsPerInch, InchesToPoints, CentiMetersToPoints

Show source

    proc ::Cawt::PointsToCentiMeters {points} {

        # Convert value in points into centimeters.
        #
        # points - Floating point value to be converted to centimeters.
        #
        # Returns the corresponding value in centimeters.
        #
        # See also: SetDotsPerInch InchesToPoints CentiMetersToPoints

        variable dotsPerInch

        return [expr {$points * 2.54 / double($dotsPerInch)}]
    }

#### PointsToInches [::Cawt]Cawt, Top, Main

Convert value in points into inches.

PointsToInches points

`points` | Floating point value to be converted to inches.

Returns the corresponding value in inches.

See also: SetDotsPerInch, CentiMetersToPoints, InchesToPoints

Show source

    proc ::Cawt::PointsToInches {points} {

        # Convert value in points into inches.
        #
        # points - Floating point value to be converted to inches.
        #
        # Returns the corresponding value in inches.
        #
        # See also: SetDotsPerInch CentiMetersToPoints InchesToPoints

        variable dotsPerInch

        return [expr {$points / double($dotsPerInch)}]
    }

#### PopComObjects [::Cawt]Cawt, Top, Main

Pop last entry from COM objects stack.

PopComObjects ?printStack?

`printStack` | Print stack content after popping onto stdout. Optional, default `false`.

Pop last entry from COM objects stack and remove all COM objects currently in use which are not contained in the popped entry.

Returns no value.

See also: PushComObjects

Show source

    proc ::Cawt::PopComObjects {{printStack false}} {

        # Pop last entry from COM objects stack.
        #
        # printStack - Print stack content after popping onto stdout.
        #
        # Pop last entry from COM objects stack and
        # remove all COM objects currently in use which
        # are not contained in the popped entry.
        #
        # Returns no value.
        #
        # See also: PushComObjects

        variable comObjStack

        set lastEntry [lindex $comObjStack end]
        set comObjStack [lrange $comObjStack 0 end-1]
        foreach comObj [lsort -dictionary [Cawt::GetComObjects]] {
            if { [lsearch -exact $lastEntry $comObj] < 0 } {
                Cawt Destroy $comObj
            }
        }
        if { $printStack } {
            Cawt::_PrintComObjStack "PopComObjects"
        }
    }

#### PrintNumComObjects [::Cawt]Cawt, Top, Main

Print the number of currently available COM objects to stdout.

PrintNumComObjects

Returns no value.

See also: IsComObject, GetComObjects, GetNumComObjects, Destroy

Show source

    proc ::Cawt::PrintNumComObjects {} {

        # Print the number of currently available COM objects to stdout.
        #
        # Returns no value.
        #
        # See also: IsComObject GetComObjects GetNumComObjects Destroy

        puts "Number of COM objects: [Cawt::GetNumComObjects]"
    }

#### PushComObjects [::Cawt]Cawt, Top, Main

Push current list of COM objects onto a stack.

PushComObjects ?printStack?

`printStack` | Print stack content after pushing onto stdout. Optional, default `false`.

Returns no value.

See also: PopComObjects

Show source

    proc ::Cawt::PushComObjects {{printStack false}} {

        # Push current list of COM objects onto a stack.
        #
        # printStack - Print stack content after pushing onto stdout.
        #
        # Returns no value.
        #
        # See also: PopComObjects

        variable comObjStack

        lappend comObjStack [lsort -dictionary [Cawt::GetComObjects]]

        if { $printStack } {
            Cawt::_PrintComObjStack "PushComObjects"
        }
    }

#### RgbToOfficeColor [::Cawt]Cawt, Top, Main

Convert a RGB color into an Office color number.

RgbToOfficeColor r g b

`r` | The red component of the color.
`g` | The green component of the color.
`b` | The blue component of the color.

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

Returns the color as an Office color integer number.

See also: OfficeColorToRgb, GetColor

Show source

    proc ::Cawt::RgbToOfficeColor {r g b} {

        # Convert a RGB color into an Office color number.
        #
        # r - The red component of the color.
        # g - The green component of the color.
        # b - The blue component of the color.
        #
        # The r, g and b values are specified as integers in the
        # range 0 .. 255.
        #
        # Returns the color as an Office color integer number.
        #
        # See also: OfficeColorToRgb GetColor

        return [expr {int ($b) << 16 | int ($g) << 8 | int($r)}]
    }

#### SecondsToIsoDate [::Cawt]Cawt, Top, Main

Return date in seconds as ISO date string.

SecondsToIsoDate sec

`sec` | Date in seconds as returned by `clock seconds`.

Returns corresponding date as ISO date string.

See also: IsoDateToSeconds, SecondsToXmlDate, SecondsToOfficeDate

Show source

    proc ::Cawt::SecondsToIsoDate {sec} {

        # Return date in seconds as ISO date string.
        #
        # sec - Date in seconds as returned by `clock seconds`.
        #
        # Returns corresponding date as ISO date string.
        #
        # See also: IsoDateToSeconds SecondsToXmlDate SecondsToOfficeDate

        return [clock format $sec -format {%Y-%m-%d %H:%M:%S}]
    }

#### SecondsToOfficeDate [::Cawt]Cawt, Top, Main

Return date in seconds as Office date.

SecondsToOfficeDate sec

`sec` | Date in seconds as returned by `clock seconds`.

Returns corresponding date as floating point number representing days since `1900/01/01`.

See also: OfficeDateToSeconds, SecondsToIsoDate, SecondsToXmlDate

Show source

    proc ::Cawt::SecondsToOfficeDate {sec} {

        # Return date in seconds as Office date.
        #
        # sec - Date in seconds as returned by `clock seconds`.
        #
        # Returns corresponding date as floating point number
        # representing days since `1900/01/01`.
        #
        # See also: OfficeDateToSeconds SecondsToIsoDate SecondsToXmlDate

        variable sOfficeDate

        set diffSecs [expr { $sec - $sOfficeDate(Sec) }]
        return [expr { $sOfficeDate(Day) + $diffSecs / 60.0 / 60.0 / 24.0 }]
    }

#### SecondsToOutlookDate [::Cawt]Cawt, Top, Main

Obsolete: Replaced with SecondsToOfficeDate in version 2.4.4

SecondsToOutlookDate sec

`sec` | Date in seconds as returned by `clock seconds`.

Returns corresponding date as floating point number representing days since `1900/01/01`.

See also: OutlookDateToSeconds, SecondsToIsoDate, SecondsToXmlDate

Show source

    proc ::Cawt::SecondsToOutlookDate {sec} {

        # Obsolete: Replaced with [SecondsToOfficeDate] in version 2.4.4
        #
        # sec - Date in seconds as returned by `clock seconds`.
        #
        # Returns corresponding date as floating point number
        # representing days since `1900/01/01`.
        #
        # See also: OutlookDateToSeconds SecondsToIsoDate SecondsToXmlDate

        return [Cawt::SecondsToOfficeDate $sec]
    }

#### SecondsToXmlDate [::Cawt]Cawt, Top, Main

Return date in seconds as XML date string.

SecondsToXmlDate sec

`sec` | Date in seconds as returned by `clock seconds`.

Returns corresponding date as XML date string.

See also: XmlDateToSeconds, SecondsToIsoDate, SecondsToOfficeDate

Show source

    proc ::Cawt::SecondsToXmlDate {sec} {

        # Return date in seconds as XML date string.
        #
        # sec - Date in seconds as returned by `clock seconds`.
        #
        # Returns corresponding date as XML date string.
        #
        # See also: XmlDateToSeconds SecondsToIsoDate SecondsToOfficeDate

        return [clock format $sec -format {%Y-%m-%dT%H:%M:%S.000Z}]
    }

#### SetDotsPerInch [::Cawt]Cawt, Top, Main

Set the dots-per-inch value used for conversions.

SetDotsPerInch dpi

`dpi` | Integer dpi value.

If the dpi value is not explicitely set with this procedure, it's default value is 72.

Returns no value.

See also: GetDotsPerInch

Show source

    proc ::Cawt::SetDotsPerInch {dpi} {

        # Set the dots-per-inch value used for conversions.
        #
        # dpi - Integer dpi value.
        #
        # If the dpi value is not explicitely set with this procedure,
        # it's default value is 72.
        #
        # Returns no value.
        #
        # See also: GetDotsPerInch

        variable dotsPerInch

        set dotsPerInch $dpi
    }

#### SetEventCallback [::Cawt]Cawt, Top, Main

Set an event callback procedure.

SetEventCallback appId callback

`appId` | The application identifier.
`callback` | The event callback procedure.

If `$callback` is the empty string, an existing event callback is disabled.

The `$callback` procedure must have an `args` argument as shown in the following example:

    proc PrintEvent { args } {
        puts $args
    }

    set appId [Excel Open]
    Cawt SetEventCallback $appId PrintEvent

Returns no value.

Show source

    proc ::Cawt::SetEventCallback {appId callback} {

        # Set an event callback procedure.
        #
        # appId    - The application identifier.
        # callback - The event callback procedure.
        #
        # If $callback is the empty string, an existing event
        # callback is disabled.
        #
        # The $callback procedure must have an `args` argument
        # as shown in the following example:
        #     proc PrintEvent { args } {
        #         puts $args
        #     }
        #
        #     set appId [Excel Open]
        #     Cawt SetEventCallback $appId PrintEvent
        #
        # Returns no value.

        variable sBindId

        if { [info exists sBindId] } {
            $appId -unbind $sBindId
        }
        if { $callback ne "" } {
            set sBindId [$appId -bind $callback]
        }
    }

#### SplitFile [::Cawt]Cawt, Top, Main

Split a file into several output files.

SplitFile inFile ?maxFileSize? ?outFilePrefix?

`inFile` | Input file name.
`maxFileSize` | Maximum size of output files in bytes. Optional, default `2048`.
`outFilePrefix` | Prefix for output file names. Optional, default `""`.

Split the content of the file specified in `$inFile` into several output files. The output files have a maximum size of `$maxFileSize` and are named as follows: `$outFilePrefix`.00001, `$outFilePrefix`.00002, ...

Returns the generated file names as a list. If the input file could not be opened for reading or any of the output files could not be openend for writing, an error is thrown.

See also: IsUnicodeFile, ConcatFiles

Show source

    proc ::Cawt::SplitFile {inFile {maxFileSize 2048} {outFilePrefix {}}} {

        # Split a file into several output files.
        #
        # inFile        - Input file name.
        # maxFileSize   - Maximum size of output files in bytes.
        # outFilePrefix - Prefix for output file names.
        #
        # Split the content of the file specified in $inFile into several
        # output files. The output files have a maximum size of $maxFileSize and
        # are named as follows: $outFilePrefix.00001, $outFilePrefix.00002, ...
        #
        # Returns the generated file names as a list.
        # If the input file could not be opened for reading
        # or any of the output files could not be openend for
        # writing, an error is thrown.
        #
        # See also: IsUnicodeFile ConcatFiles

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

        if { $outFilePrefix ne "" } {
            set outFileName $outFilePrefix
        } else {
            set outFileName $inFile
        }
        set count 1
        set fileList [list]
        while { 1 } {
            set str [read $inFp $maxFileSize]
            if { $str ne "" } {
                set fileName [format "%s-%05d" $outFileName $count]
                set catchVal [catch {open $fileName w} outFp]
                if { $catchVal != 0 } {
                    close $inFp
                    error "Could not open file \"$fileName\" for writing."
                }
                fconfigure $outFp -translation binary
                puts -nonewline $outFp $str
                close $outFp
                lappend fileList $fileName
                incr count
            }
            if { [eof $inFp] } {
                break
            }
        }
        close $inFp
        return $fileList
    }

#### TclBool [::Cawt]Cawt, Top, Main

Cast a value to a boolean.

TclBool val

`val` | The value to be casted.

Returns true, if `$val` is not equal to zero or true. Otherwise returns false.

See also: TclInt, TclString

Show source

    proc ::Cawt::TclBool {val} {

        # Cast a value to a boolean.
        #
        # val - The value to be casted.
        #
        # Returns true, if $val is not equal to zero or true.
        # Otherwise returns false.
        #
        # See also: TclInt TclString

        return [twapi::tclcast boolean $val]
    }

#### TclInt [::Cawt]Cawt, Top, Main

Cast a value to an integer with boolean range.

TclInt val

`val` | The value to be casted.

Returns 1, if `$val` is not equal to zero or true. Otherwise returns 0.

See also: TclBool, TclString

Show source

    proc ::Cawt::TclInt {val} {

        # Cast a value to an integer with boolean range.
        #
        # val - The value to be casted.
        #
        # Returns 1, if $val is not equal to zero or true.
        # Otherwise returns 0.
        #
        # See also: TclBool TclString

        set tmp 0
        if { $val } {
            set tmp 1
        }
        return $tmp
    }

#### TclString [::Cawt]Cawt, Top, Main

Cast a value to a string.

TclString val

`val` | The value to be casted.

Returns casted string in a format usable for the COM interface.

See also: TclInt, TclBool

Show source

    proc ::Cawt::TclString {val} {

        # Cast a value to a string.
        #
        # val - The value to be casted.
        #
        # Returns casted string in a format usable for the COM interface.
        #
        # See also: TclInt TclBool

        variable pkgInfo

        if { $pkgInfo(haveStringCast) } {
            return [twapi::tclcast bstr $val]
        } else {
            return [twapi::tclcast string $val]
        }
    }

#### ValueToPoints [::Cawt]Cawt, Top, Main

Convert a value into points.

ValueToPoints value

`value` | Floating point value to be converted to points.

- If the value is followed by `i`, it is interpreted as inches.
- If the value is followed by `c`, it is interpreted as centimeters.
- If the value is a simple floating point number or followed by `p`, it is interpreted as points, i.e. the pure value is returned.

Example:

     ValueToPoints 2c
     ValueToPoints 1.5i

Returns the corresponding value in points.

See also: CentiMetersToPoints, InchesToPoints

Show source

    proc ::Cawt::ValueToPoints {value} {

        # Convert a value into points.
        #
        # value - Floating point value to be converted to points.
        #
        # * If the value is followed by `i`, it is interpreted as inches.
        # * If the value is followed by `c`, it is interpreted as centimeters.
        # * If the value is a simple floating point number or followed by `p`,
        #   it is interpreted as points, i.e. the pure value is returned.
        #
        # Example:
        #      ValueToPoints 2c
        #      ValueToPoints 1.5i
        #
        # Returns the corresponding value in points.
        #
        # See also: CentiMetersToPoints InchesToPoints

        if { [string index $value end] eq "c" } {
            return [Cawt::CentiMetersToPoints [string range $value 0 end-1]]
        } elseif { [string index $value end] eq "i" } {
            return [Cawt::InchesToPoints [string range $value 0 end-1]]
        } elseif { [string index $value end] eq "p" } {
            return [string range $value 0 end-1]
        } elseif { [string is double $value] } {
            return $value
        } else {
            error "Invalid value \"$value\" specified."
        }
    }

#### XmlDateToIsoDate [::Cawt]Cawt, Top, Main

Return XML date string as ISO date string.

XmlDateToIsoDate xmlDate

`xmlDate` | Date string in format `%Y-%m-%dT%H:%M:%S.000Z`.

Returns corresponding date as ISO date string.

See also: IsoDateToXmlDate, XmlDateToSeconds

Show source

    proc ::Cawt::XmlDateToIsoDate {xmlDate} {

        # Return XML date string as ISO date string.
        #
        # xmlDate - Date string in format `%Y-%m-%dT%H:%M:%S.000Z`.
        #
        # Returns corresponding date as ISO date string.
        #
        # See also: IsoDateToXmlDate XmlDateToSeconds

        return [Cawt::SecondsToIsoDate [XmlDateToSeconds $xmlDate]]
    }

#### XmlDateToSeconds [::Cawt]Cawt, Top, Main

Return XML date string as seconds.

XmlDateToSeconds xmlDate

`xmlDate` | Date string in format `%Y-%m-%dT%H:%M:%S.000Z`.

Returns corresponding seconds as integer.

See also: SecondsToXmlDate, IsoDateToSeconds, OfficeDateToSeconds

Show source

    proc ::Cawt::XmlDateToSeconds {xmlDate} {

        # Return XML date string as seconds.
        #
        # xmlDate - Date string in format `%Y-%m-%dT%H:%M:%S.000Z`.
        #
        # Returns corresponding seconds as integer.
        #
        # See also: SecondsToXmlDate IsoDateToSeconds OfficeDateToSeconds

        return [clock scan $xmlDate -format {%Y-%m-%dT%H:%M:%S.000Z}]
    }

# Start page

# Cawt

# Office

# Excel

# Ppt

# Word

# Outlook

# OneNote

# Sapi

# Office::Enum

# Excel::Enum

# Ppt::Enum

# Word::Enum

# Outlook::Enum

# OneNote::Enum

# Sapi::Enum

# Earth

# Explorer

# Ocr

# Reader

# Matlab

# Cawt

## Commands

#### CentiMetersToPoints Convert centimeter value into points.

#### CheckBoolean Check, if two boolean values are identical.

#### CheckComObjects Check, if the number of COM objects fits expected value.

#### CheckFile Check, if two files are identical.

#### CheckList Check, if two lists are identical.

#### CheckMatrix Check, if two matrices are identical.

#### CheckNumber Check, if two numerical values are identical.

#### CheckString Check, if two string values are identical.

#### ClipboardToImg Copy the clipboard content into a photo image.

#### ConcatFiles Concatenates files into one file.

#### CountWords Count words contained in a string.

#### Destroy Destroy one or all COM objects.

#### GetColor Convert a color representation into an Office color number.

#### GetColorNames Get all supported Tcl color names.

#### GetComObjects Get the COM objects currently in use as a list.

#### GetDotsPerInch Get the dots-per-inch value used for conversions.

#### GetNumComObjects Get the number of COM objects currently in use.

#### GetOrCreateApp Use or create an instance of an application.

#### GetPkgVersion Get the version of a CAWT sub-package.

#### GetProgramByExtension Get path to program for a given file extension.

#### GetTmpDir

#### HavePkg Check, if a CAWT sub-package is available.

#### ImgToClipboard Copy a photo image into the clipboard.

#### InchesToPoints Convert inch value into points.

#### IsComObject Check, if a COM object is valid.

#### IsHexColor Check, if specified color is a valid Tcl hexadecimal color string.

#### IsNameColor Check, if specified color is a valid Tcl color name.

#### IsoDateToOfficeDate Return ISO date string as Office date.

#### IsoDateToOutlookDate Obsolete: Replaced with IsoDateToOfficeDate in version 2.4.4

#### IsoDateToSeconds Return ISO date string as seconds.

#### IsoDateToXmlDate Return ISO date string as XML date string.

#### IsOfficeColor Check, if specified color is a valid Office color number.

#### IsRgbColor Check, if specified color is a valid RGB representation.

#### IsUnicodeFile Check, if a file is encoded in Unicode.

#### IsValidId Obsolete: Replaced with IsComObject in version 2.0.0

#### KillApp Kill all running instances of an application.

#### OfficeColorToRgb Convert an Office color number into a RGB color list.

#### OfficeDateToIsoDate Return Office date as ISO date string.

#### OfficeDateToSeconds Return Office date as seconds.

#### OutlookDateToIsoDate Obsolete: Replaced with OfficeDateToIsoDate in version 2.4.4

#### OutlookDateToSeconds Obsolete: Replaced with OfficeDateToSeconds in version 2.4.4

#### PointsToCentiMeters Convert value in points into centimeters.

#### PointsToInches Convert value in points into inches.

#### PopComObjects Pop last entry from COM objects stack.

#### PrintNumComObjects Print the number of currently available COM objects to stdout.

#### PushComObjects Push current list of COM objects onto a stack.

#### RgbToOfficeColor Convert a RGB color into an Office color number.

#### SecondsToIsoDate Return date in seconds as ISO date string.

#### SecondsToOfficeDate Return date in seconds as Office date.

#### SecondsToOutlookDate Obsolete: Replaced with SecondsToOfficeDate in version 2.4.4

#### SecondsToXmlDate Return date in seconds as XML date string.

#### SetDotsPerInch Set the dots-per-inch value used for conversions.

#### SetEventCallback Set an event callback procedure.

#### SplitFile Split a file into several output files.

#### TclBool Cast a value to a boolean.

#### TclInt Cast a value to an integer with boolean range.

#### TclString Cast a value to a string.

#### ValueToPoints Convert a value into points.

#### XmlDateToIsoDate Return XML date string as ISO date string.

#### XmlDateToSeconds Return XML date string as seconds.

Document generated by Ruff!