::CawtMain

The Cawt namespace provides commands for basic automation functionality.

CommandsCawt, Main

CentiMetersToPoints [::Cawt]Cawt, Main

Convert centimeter value into points.

CentiMetersToPoints cm
cmFloating point centimeter value to be converted to points.

Returns the corresponding value in points.

See also: SetDotsPerInch, InchesToPoints, PointsToCentiMeters

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, Main

Check, if two boolean values are identical.

CheckBoolean expected value msg ?printCheck?
expectedExpected boolean value.
valueTest boolean value.
msgMessage for test case.
printCheckPrint 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

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, Main

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

CheckComObjects expected msg ?printCheck?
expectedExpected number of COM objects.
msgMessage for test case.
printCheckPrint 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

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, Main

Check, if two files are identical.

CheckFile fileName1 fileName2 msg ?printCheck?
fileName1First file name.
fileName2Second file name.
msgMessage for test case.
printCheckPrint 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

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, Main

Check, if two lists are identical.

CheckList expected value msg ?printCheck?
expectedExpected list.
valueTest list.
msgMessage for test case.
printCheckPrint 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

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, Main

Check, if two matrices are identical.

CheckMatrix expected value msg ?printCheck?
expectedExpected matrix.
valueTest matrix.
msgMessage for test case.
printCheckPrint 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

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, Main

Check, if two numerical values are identical.

CheckNumber expected value msg ?printCheck?
expectedExpected numeric value.
valueTest numeric value.
msgMessage for test case.
printCheckPrint 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

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, Main

Check, if two string values are identical.

CheckString expected value msg ?printCheck?
expectedExpected string value.
valueTest string value.
msgMessage for test case.
printCheckPrint 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

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

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, Main

Concatenates files into one file.

ConcatFiles outFile ?args?
outFileOutput file name.
argsList 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

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, Main

Count words contained in a string.

CountWords str ?args?
strString to be searched.
argsOptions 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

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, Main

Destroy one or all COM objects.

Destroy ?comObj?
comObjThe 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

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, Main

Convert a color representation into an Office color number.

GetColor ?args?
argsA valid color representation.

Colors can be specified in one of the following representations:

NameA valid Tcl color name string, ex. black.
HexadecimalA valid Tcl hexadecimal string, ex. #00FFAA.
RGB3 integer values in the range 0 .. 255.
Office numberAn integer number with encoded RGB values.

Returns the color as an Office color number.

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

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, Main

Get all supported Tcl color names.

GetColorNames

Returns a sorted list of all supported Tcl color names.

See also: IsNameColor

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

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, Main

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

GetDotsPerInch

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

See also: SetDotsPerInch

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

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, Main

Use or create an instance of an application.

GetOrCreateApp appName useExistingFirst
appNameThe name of the application to be created or used.
useExistingFirstPrefer 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

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, Main

Get the version of a CAWT sub-package.

GetPkgVersion pkgName
pkgNameThe 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

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, Main

Get path to program for a given file extension.

GetProgramByExtension extension
extensionThe extension string (including a dot, ex. .pdf).

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

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

HavePkg [::Cawt]Cawt, Main

Check, if a CAWT sub-package is available.

HavePkg pkgName
pkgNameThe name of the sub-package.

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

See also: GetPkgVersion

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, Main

Copy a photo image into the clipboard.

ImgToClipboard phImg
phImgThe 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

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, Main

Convert inch value into points.

InchesToPoints inches
inchesFloating point inch value to be converted to points.

Returns the corresponding value in points.

See also: SetDotsPerInch, CentiMetersToPoints, PointsToInches

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, Main

Check, if a COM object is valid.

IsComObject comObj
comObjThe COM object.

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

See also: GetComObjects, GetNumComObjects, PrintNumComObjects

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, Main

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

IsHexColor color
colorThe 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

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, Main

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

IsNameColor color
colorThe 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

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, Main

Return ISO date string as Office date.

IsoDateToOfficeDate isoDate
isoDateDate 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

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, Main

Obsolete: Replaced with IsoDateToOfficeDate in version 2.4.4

IsoDateToOutlookDate isoDate
isoDateDate 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

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, Main

Return ISO date string as seconds.

IsoDateToSeconds isoDate
isoDateDate string in format %Y-%m-%d %H:%M:%S.

Returns corresponding seconds as integer.

See also: SecondsToIsoDate, XmlDateToSeconds, OfficeDateToSeconds

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, Main

Return ISO date string as XML date string.

IsoDateToXmlDate isoDate
isoDateDate string in format %Y-%m-%d %H:%M:%S.

Returns corresponding date as XML date string.

See also: XmlDateToIsoDate, IsoDateToSeconds, IsoDateToOfficeDate

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, Main

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

IsOfficeColor color
colorThe Office color number.

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

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

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, Main

Check, if specified color is a valid RGB representation.

IsRgbColor r g b
rThe red component of the color.
gThe green component of the color.
bThe 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

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, Main

Check, if a file is encoded in Unicode.

IsUnicodeFile fileName
fileNameFile 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

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, Main

Obsolete: Replaced with IsComObject in version 2.0.0

IsValidId comObj
comObjNot documented.
proc ::Cawt::IsValidId {comObj} {

    # Obsolete: Replaced with [IsComObject] in version 2.0.0

    return [IsComObject $comObj]
}

KillApp [::Cawt]Cawt, Main

Kill all running instances of an application.

KillApp progName
progNameThe application's program name, as shown in the task manager.

Returns no value.

See also: GetOrCreateApp

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, Main

Convert an Office color number into a RGB color list.

OfficeColorToRgb color
colorThe 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

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, Main

Return Office date as ISO date string.

OfficeDateToIsoDate officeDate
officeDateFloating point number representing days since 1900/01/01.

Returns corresponding date as ISO date string.

See also: IsoDateToOfficeDate, OfficeDateToSeconds

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, Main

Return Office date as seconds.

OfficeDateToSeconds officeDate
officeDateFloating point number representing days since 1900/01/01.

Returns corresponding seconds as integer.

See also: SecondsToOfficeDate, IsoDateToSeconds, XmlDateToSeconds

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, Main

Obsolete: Replaced with OfficeDateToIsoDate in version 2.4.4

OutlookDateToIsoDate outlookDate
outlookDateFloating point number representing days since 1900/01/01.

Returns corresponding date as ISO date string.

See also: IsoDateToOutlookDate, OutlookDateToSeconds

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, Main

Obsolete: Replaced with OfficeDateToSeconds in version 2.4.4

OutlookDateToSeconds outlookDate
outlookDateFloating point number representing days since 1900/01/01.

Returns corresponding seconds as integer.

See also: SecondsToOutlookDate, IsoDateToSeconds, XmlDateToSeconds

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, Main

Convert value in points into centimeters.

PointsToCentiMeters points
pointsFloating point value to be converted to centimeters.

Returns the corresponding value in centimeters.

See also: SetDotsPerInch, InchesToPoints, CentiMetersToPoints

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, Main

Convert value in points into inches.

PointsToInches points
pointsFloating point value to be converted to inches.

Returns the corresponding value in inches.

See also: SetDotsPerInch, CentiMetersToPoints, InchesToPoints

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, Main

Pop last entry from COM objects stack.

PopComObjects ?printStack?
printStackPrint 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

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, Main

Print the number of currently available COM objects to stdout.

PrintNumComObjects

Returns no value.

See also: IsComObject, GetComObjects, GetNumComObjects, Destroy

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, Main

Push current list of COM objects onto a stack.

PushComObjects ?printStack?
printStackPrint stack content after pushing onto stdout. Optional, default false.

Returns no value.

See also: PopComObjects

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, Main

Convert a RGB color into an Office color number.

RgbToOfficeColor r g b
rThe red component of the color.
gThe green component of the color.
bThe 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

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, Main

Return date in seconds as ISO date string.

SecondsToIsoDate sec
secDate in seconds as returned by clock seconds.

Returns corresponding date as ISO date string.

See also: IsoDateToSeconds, SecondsToXmlDate, SecondsToOfficeDate

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, Main

Return date in seconds as Office date.

SecondsToOfficeDate sec
secDate 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

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, Main

Obsolete: Replaced with SecondsToOfficeDate in version 2.4.4

SecondsToOutlookDate sec
secDate 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

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, Main

Return date in seconds as XML date string.

SecondsToXmlDate sec
secDate in seconds as returned by clock seconds.

Returns corresponding date as XML date string.

See also: XmlDateToSeconds, SecondsToIsoDate, SecondsToOfficeDate

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, Main

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

SetDotsPerInch dpi
dpiInteger 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

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
}

SplitFile [::Cawt]Cawt, Main

Split a file into several output files.

SplitFile inFile ?maxFileSize? ?outFilePrefix?
inFileInput file name.
maxFileSizeMaximum size of output files in bytes. Optional, default 2048.
outFilePrefixPrefix 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

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, Main

Cast a value to a boolean.

TclBool val
valThe value to be casted.

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

See also: TclInt, TclString

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, Main

Cast a value to an integer with boolean range.

TclInt val
valThe value to be casted.

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

See also: TclBool, TclString

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, Main

Cast a value to a string.

TclString val
valThe value to be casted.

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

See also: TclInt, TclBool

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, Main

Convert a value into points.

ValueToPoints value
valueFloating 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

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, Main

Return XML date string as ISO date string.

XmlDateToIsoDate xmlDate
xmlDateDate string in format %Y-%m-%dT%H:%M:%S.000Z.

Returns corresponding date as ISO date string.

See also: IsoDateToXmlDate, XmlDateToSeconds

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, Main

Return XML date string as seconds.

XmlDateToSeconds xmlDate
xmlDateDate string in format %Y-%m-%dT%H:%M:%S.000Z.

Returns corresponding seconds as integer.

See also: SecondsToXmlDate, IsoDateToSeconds, OfficeDateToSeconds

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}]
}
Document generated by Ruff!