CAWT 2.5.0 Reference Manual

# ::OfficeTop, Main

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

## CommandsOffice, Top, Main

#### AddMacro [::Office]Office, Top, Main

Add macros or functions to an Office document.

AddMacro appId ?args?

`appId` | The application identifier.
`args` | Options described below.
`-code <string>` | Use macros stored in specified string.
`-file <fileName>` | Use macros stored in specified file.

Returns no value. An error is thrown, if no option or an invalid option is specified, if the file does not exist or if the VBA project object model is not enabled in the trust center.

See also: RunMacro

Show source

    proc ::Office::AddMacro {appId args} {

        # Add macros or functions to an Office document.
        #
        # appId - The application identifier.
        # args  - Options described below.
        #
        # -file <fileName> - Use macros stored in specified file.
        # -code <string>   - Use macros stored in specified string.
        #
        # Returns no value.
        # An error is thrown, if no option or an invalid option is specified,
        # if the file does not exist or if the VBA project object model
        # is not enabled in the trust center.
        #
        # See also: RunMacro

        set fileName ""
        set codeStr  ""
        foreach { key value } $args {
            if { $value eq "" } {
                error "AddMacro: No value specified for key \"$key\""
            }
            switch -exact -nocase -- $key {
                "-file" {
                    set fileName [file nativename [file normalize $value]]
                    if { ! [file exists $fileName] } {
                        error "AddMacro: File $fileName does not exist."
                    }
                }
                "-code" {
                    set codeStr $value
                }
                default {
                    error "AddMacro: Unknown key \"$key\" specified"
                }
            }
        }

        if { $fileName ne "" } {
            set catchVal [catch { $appId -with { VBE ActiveVBProject VBComponents } -call Import $fileName }]
            if { $catchVal } {
                error "AddMacro: Trust Access to the VBA project object model must be enabled."
            }
        } elseif { $codeStr ne "" } {
            set vbext_ct_StdModule [expr int(1)]
            set catchVal [catch { $appId -with { VBE ActiveVBProject VBComponents } -call Add $vbext_ct_StdModule } module]
            if { $catchVal } {
                error "AddMacro: Trust Access to the VBA project object model must be enabled."
            }
            $module -with { CodeModule } AddFromString $codeStr
        } else {
            error "AddMacro: Neither \"-file\" nor \"-code\" option specified."
        }
    }

#### AddProperty [::Office]Office, Top, Main

Add a custom document property.

AddProperty objId propertyName ?args?

`objId` | The identifier of an Office object (Workbook, Document, Presentation).
`propertyName` | The name of the new custom property.
`args` | Options described below.
`-overwrite <bool>` | If a property with given name already exists, the property is either replaced (`-overwrite true`) or an error is thrown (`-overwrite false`). If not specified, overwriting is disabled.
`-type <enum>` | The type (string, int, bool, date, float) of the property. Enumeration of type Enum::MsoDocProperties. If not specified, the property is of type `msoPropertyTypeString`.
`-value <val>` | Value of the new property. The specified value must match the specified type. If not specified, the value is set to the empty string for string properties and to zero for all other property types.

Returns the identifier of the new property or an error depending on the setting of option `-overwrite`.

See also: SetDocumentProperty, GetDocumentProperty, GetProperty, GetDocumentProperties, GetPropertyName, GetPropertyType, GetPropertyValue, SetPropertyValue, DeleteProperty

Show source

    proc ::Office::AddProperty {objId propertyName args} {

        # Add a custom document property.
        #
        # objId        - The identifier of an Office object (Workbook, Document, Presentation).
        # propertyName - The name of the new custom property.
        # args         - Options described below.
        #
        # -type <enum> -      The type (string, int, bool, date, float) of the property.
        #                     Enumeration of type [Enum::MsoDocProperties].
        #                     If not specified, the property is of type `msoPropertyTypeString`.
        # -value <val>      - Value of the new property. The specified value must match the
        #                     specified type. If not specified, the value is set to the empty
        #                     string for string properties and to zero for all other property types.
        # -overwrite <bool> - If a property with given name already exists, the property is either
        #                     replaced (`-overwrite true`) or an error is thrown
        #                     (`-overwrite false`). If not specified, overwriting is disabled.
        #
        # Returns the identifier of the new property or an error depending on the setting of
        # option `-overwrite`.
        #
        # See also: SetDocumentProperty GetDocumentProperty GetProperty GetDocumentProperties
        #           GetPropertyName GetPropertyType GetPropertyValue SetPropertyValue DeleteProperty

        set propertyType [Office GetEnum msoPropertyTypeString]
        set overwrite    false
        foreach { key value } $args {
            if { $value eq "" } {
                error "AddProperty: No value specified for key \"$key\""
            }
            switch -exact -nocase -- $key {
                "-type"      { set propertyType [Office GetEnum $value] }
                "-value"     { set propertyValue $value }
                "-overwrite" { set overwrite $value }
                default  { error "AddProperty: Unknown key \"$key\" specified" }
            }
        }

        if { ! [info exists propertyValue] } {
            if { $propertyType == $::Office::msoPropertyTypeString } {
                set propertyValue ""
            } else {
                set propertyValue 0
            }
        }
        switch -- [Office GetEnumName "MsoDocProperties" $propertyType] {
            "msoPropertyTypeBoolean" { set val [Cawt TclBool $propertyValue] }
            "msoPropertyTypeString"  { set val [Cawt TclString $propertyValue] }
            "msoPropertyTypeNumber"  { set val [expr { int ($propertyValue) }] }
            "msoPropertyTypeDate"    { set val [expr { double ($propertyValue) }] }
            "msoPropertyTypeFloat"   { set val [expr { double ($propertyValue) }] }
            default { error "AddProperty: Unknown property type \"$propertyType\"" }
        }
        set retVal [catch {Office GetProperty $objId $propertyName -type "Custom"} propertyId]
        if { $retVal == 0 } {
            if { $overwrite } {
                Office DeleteProperty $propertyId
            } else {
                error "AddProperty: Property \"$propertyName\" already exists"
            }
        }
        set propsCustom [$objId CustomDocumentProperties]
        set propertyId [$propsCustom -call Add $propertyName [Cawt TclBool false] $propertyType $propertyValue]
        Cawt Destroy $propsCustom
        return $propertyId
    }

#### ColorToRgb [::Office]Office, Top, Main

Obsolete: Replaced with ::Cawt::OfficeColorToRgb in version 2.2.0

ColorToRgb color

`color` | Not documented.

Show source

    proc ::Office::ColorToRgb {color} {

        # Obsolete: Replaced with [::Cawt::OfficeColorToRgb] in version 2.2.0

        return [Cawt OfficeColorToRgb $color]
    }

#### DeleteProperty [::Office]Office, Top, Main

Delete a document property.

DeleteProperty propertyId

`propertyId` | Identifier of the Office property.

Returns no value.

See also: SetDocumentProperty, GetDocumentProperty, AddProperty, GetProperty, GetPropertyName, GetPropertyType, GetPropertyValue, SetPropertyValue, GetDocumentProperties

Show source

    proc ::Office::DeleteProperty {propertyId} {

        # Delete a document property.
        #
        # propertyId - Identifier of the Office property.
        #
        # Returns no value.
        #
        # See also: SetDocumentProperty GetDocumentProperty AddProperty GetProperty GetPropertyName
        #           GetPropertyType GetPropertyValue SetPropertyValue GetDocumentProperties

        $propertyId -call Delete
        Cawt Destroy $propertyId
    }

#### GetActivePrinter [::Office]Office, Top, Main

Get the name of the active printer.

GetActivePrinter appId

`appId` | The application identifier.

Returns the name of the active printer as a string.

See also: SetPrinterCommunication

Show source

    proc ::Office::GetActivePrinter {appId} {

        # Get the name of the active printer.
        #
        # appId - The application identifier.
        #
        # Returns the name of the active printer as a string.
        #
        # See also: SetPrinterCommunication

        set retVal [catch {$appId ActivePrinter} val]
        if { $retVal == 0 } {
            return $val
        } else {
            return "Method not available"
        }
    }

#### GetApplicationId [::Office]Office, Top, Main

Get the application identifier of an Office object.

GetApplicationId objId

`objId` | The identifier of an Office object.

Office object are Workbooks, Worksheets, ...

Returns the application identifier of the Office object.

See also: GetApplicationName, IsApplicationId

Show source

    proc ::Office::GetApplicationId {objId} {

        # Get the application identifier of an Office object.
        #
        # objId - The identifier of an Office object.
        #
        # Office object are Workbooks, Worksheets, ...
        #
        # Returns the application identifier of the Office object.
        #
        # See also: GetApplicationName IsApplicationId

        return [$objId Application]
    }

#### GetApplicationName [::Office]Office, Top, Main

Get the name of an Office application.

GetApplicationName objId

`objId` | The identifier of an Office object.

Returns the name of the application as a string.

See also: GetApplicationId, IsApplicationId

Show source

    proc ::Office::GetApplicationName {objId} {

        # Get the name of an Office application.
        #
        # objId - The identifier of an Office object.
        #
        # Returns the name of the application as a string.
        #
        # See also: GetApplicationId IsApplicationId

        if { ! [Office IsApplicationId $objId] } {
            set appId [Office GetApplicationId $objId]
            set name [$appId Name]
            Cawt Destroy $appId
            return $name
        } else {
            return [$objId Name]
        }
    }

#### GetApplicationVersion [::Office]Office, Top, Main

Get the version number of an Office application.

GetApplicationVersion objId

`objId` | The identifier of an Office object.

Returns the version of the application as a floating point number.

See also: GetApplicationId, GetApplicationName

Show source

    proc ::Office::GetApplicationVersion {objId} {

        # Get the version number of an Office application.
        #
        # objId - The identifier of an Office object.
        #
        # Returns the version of the application as a floating point number.
        #
        # See also: GetApplicationId GetApplicationName

        if { ! [Office IsApplicationId $objId] } {
            set appId [Office GetApplicationId $objId]
            set version [$appId Version]
            Cawt Destroy $appId
        } else {
            set version [$objId Version]
        }
        return $version
    }

#### GetDocumentProperties [::Office]Office, Top, Main

Get document property names as a list.

GetDocumentProperties objId ?type?

`objId` | The identifier of an Office object (Workbook, Document, Presentation).
`type` | Type of document properties as string: `Builtin` or `Custom`. If `type` is not specified or the empty string, both types of document properties are included in the list. Optional, default `""`.

Returns a sorted Tcl list containing the names of all properties of the specified type.

See also: SetDocumentProperty, GetDocumentProperty, AddProperty, GetProperty, DeleteProperty, GetPropertyName, GetPropertyType, GetPropertyValue, SetPropertyValue

Show source

    proc ::Office::GetDocumentProperties {objId {type {}}} {

        # Get document property names as a list.
        #
        # objId - The identifier of an Office object (Workbook, Document, Presentation).
        # type  - Type of document properties as string: `Builtin` or `Custom`.
        #         If `type` is not specified or the empty string, both types
        #         of document properties are included in the list.
        #
        # Returns a sorted Tcl list containing the names of all properties
        # of the specified type.
        #
        # See also: SetDocumentProperty GetDocumentProperty AddProperty GetProperty DeleteProperty
        #           GetPropertyName GetPropertyType GetPropertyValue SetPropertyValue

        set propsBuiltin [$objId BuiltinDocumentProperties]
        set propsCustom  [$objId CustomDocumentProperties]

        set propList [list]
        if { $type eq "Builtin" || $type eq "" } {
            $propsBuiltin -iterate prop {
                lappend propList [$prop Name]
                Cawt Destroy $prop
            }
        }
        if { $type eq "Custom" || $type eq "" } {
            $propsCustom -iterate prop {
                lappend propList [$prop Name]
                Cawt Destroy $prop
            }
        }
        Cawt Destroy $propsBuiltin
        Cawt Destroy $propsCustom
        return [lsort -dictionary $propList]
    }

#### GetDocumentProperty [::Office]Office, Top, Main

Get the value of a document property.

GetDocumentProperty objId propertyName

`objId` | The identifier of an Office object (Workbook, Document, Presentation).
`propertyName` | The name of the property.

Returns the value of specified property. If the property value is not set or an invalid property name is given, the string `N/A` is returned.

See also: SetDocumentProperty, AddProperty, GetProperty, GetDocumentProperties, GetPropertyName, GetPropertyType, GetPropertyValue, SetPropertyValue, DeleteProperty

Show source

    proc ::Office::GetDocumentProperty {objId propertyName} {

        # Get the value of a document property.
        #
        # objId        - The identifier of an Office object (Workbook, Document, Presentation).
        # propertyName - The name of the property.
        #
        # Returns the value of specified property.
        # If the property value is not set or an invalid property name is given,
        # the string `N/A` is returned.
        #
        # See also: SetDocumentProperty AddProperty GetProperty GetDocumentProperties
        #           GetPropertyName GetPropertyType GetPropertyValue SetPropertyValue DeleteProperty

        set propertyValue "N/A"
        set retVal [catch {Office GetProperty $objId $propertyName} propertyId]
        if { $retVal == 0 } {
            set propertyValue [Office GetPropertyValue $propertyId]
            Cawt Destroy $propertyId
        }
        return $propertyValue
    }

#### GetEnum [::Office]Office, Top, Main

Get numeric value of an enumeration.

GetEnum enumOrString

`enumOrString` | Enumeration name

Returns the numeric value of an enumeration.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnumNames

Show source

    proc ::Office::GetEnum {enumOrString} {

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

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

#### GetEnumName [::Office]Office, Top, Main

Get name of a given enumeration type and numeric value.

GetEnumName enumType enumVal

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

Returns the list of names of a given enumeration type.

See also: GetEnumNames, GetEnumTypes, GetEnumVal, GetEnum

Show source

    proc ::Office::GetEnumName {enumType enumVal} {

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

        variable enums

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

#### GetEnumNames [::Office]Office, Top, Main

Get names of a given enumeration type.

GetEnumNames enumType

`enumType` | Enumeration type

Returns the list of names of a given enumeration type.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnum

Show source

    proc ::Office::GetEnumNames {enumType} {

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

        variable enums

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

#### GetEnumTypes [::Office]Office, Top, Main

Get available enumeration types.

GetEnumTypes

Returns the list of available enumeration types.

See also: GetEnumName, GetEnumNames, GetEnumVal, GetEnum

Show source

    proc ::Office::GetEnumTypes {} {

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

        variable enums

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

#### GetEnumVal [::Office]Office, Top, Main

Get numeric value of an enumeration name.

GetEnumVal enumName

`enumName` | Enumeration name

Returns the numeric value of an enumeration name.

See also: GetEnumName, GetEnumTypes, GetEnumNames, GetEnum

Show source

    proc ::Office::GetEnumVal {enumName} {

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

        variable enums

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

#### GetInstallationPath [::Office]Office, Top, Main

Get the Office installation pathname.

GetInstallationPath appId

`appId` | The application identifier.

Returns the installation pathname as a string.

Show source

    proc ::Office::GetInstallationPath {appId} {

        # Get the Office installation pathname.
        #
        # appId - The application identifier.
        #
        # Returns the installation pathname as a string.

        set retVal [catch {$appId Path} val]
        if { $retVal == 0 } {
            return $val
        } else {
            return "Method not available"
        }
    }

#### GetOfficeType [::Office]Office, Top, Main

Get the Office type of a file.

GetOfficeType fileName

`fileName` | File name.

Returns the Office type of the file. Possible values are: `Excel`, `Ppt`, `Word`. If the file is not an Office file, the return value is the empty string.

See also: ::Excel::GetExtString, ::Ppt::GetExtString, ::Word::GetExtString

Show source

    proc ::Office::GetOfficeType {fileName} {

        # Get the Office type of a file.
        #
        # fileName - File name.
        #
        # Returns the Office type of the file.
        # Possible values are: `Excel`, `Ppt`, `Word`.
        # If the file is not an Office file, the return value
        # is the empty string.
        #
        # See also: ::Excel::GetExtString ::Ppt::GetExtString
        # ::Word::GetExtString

        set ext [string tolower [file extension $fileName]]
        if { $ext eq ".xls"  || $ext eq ".xlsx" ||  $ext eq ".xlt"  || $ext eq ".xltx" ||  $ext eq ".xltm" || $ext eq ".xlsm" } {
            return "Excel"
        } elseif { $ext eq ".doc"  || $ext eq ".docx" ||  $ext eq ".dot"  || $ext eq ".dotx" ||  $ext eq ".docm" || $ext eq ".dotm" } {
            return "Word"
        } elseif { $ext eq ".ppt"  || $ext eq ".pptx" ||  $ext eq ".pot"  || $ext eq ".potx" ||  $ext eq ".pptm" || $ext eq ".potm" } {
            return "Ppt"
        } else {
            return ""
        }
    }

#### GetProperty [::Office]Office, Top, Main

Get a document property.

GetProperty objId propertyName ?args?

`objId` | The identifier of an Office object (Workbook, Document, Presentation).
`propertyName` | The name of the property.
`args` | Options described below.
`-type <string>` | Type of document property (`Builtin` or `Custom`). If not specified, the property is searched in the builtin and custom properties list. If the property name exists in both lists, the builtin property is returned.

Returns the identifier of the specified property. If a property with given name does not exist, an error is thrown.

See also: SetDocumentProperty, GetDocumentProperty, AddProperty, GetDocumentProperties, GetPropertyName, GetPropertyType, GetPropertyValue, SetPropertyValue, DeleteProperty

Show source

    proc ::Office::GetProperty {objId propertyName args} {

        # Get a document property.
        #
        # objId        - The identifier of an Office object (Workbook, Document, Presentation).
        # propertyName - The name of the property.
        # args         - Options described below.
        #
        # -type <string> - Type of document property (`Builtin` or `Custom`).
        #                  If not specified, the property is searched in the builtin and
        #                  custom properties list. If the property name exists in both lists,
        #                  the builtin property is returned.
        #
        # Returns the identifier of the specified property.
        # If a property with given name does not exist, an error is thrown.
        #
        # See also: SetDocumentProperty GetDocumentProperty AddProperty GetDocumentProperties
        #           GetPropertyName GetPropertyType GetPropertyValue SetPropertyValue DeleteProperty

        set type ""
        foreach { key value } $args {
            if { $value eq "" } {
                error "GetProperty: No value specified for key \"$key\""
            }
            switch -exact -nocase -- $key {
                "-type" { set type $value }
                default { error "GetProperty: Unknown key \"$key\" specified" }
            }
        }
        set properties [Office GetDocumentProperties $objId $type]
        if { [lsearch $properties $propertyName] >= 0 } {
            if { $type eq "Builtin" || $type eq "" } {
                set propsBuiltin [$objId BuiltinDocumentProperties]
                set retVal [catch {$propsBuiltin -get Item $propertyName} property]
                Cawt Destroy $propsBuiltin
                if { $retVal == 0 } {
                    return $property
                }
            }
            if { $type eq "Custom" || $type eq "" } {
                set propsCustom  [$objId CustomDocumentProperties]
                set retVal [catch {$propsCustom -get Item $propertyName} property]
                Cawt Destroy $propsCustom
                if { $retVal == 0 } {
                    return $property
                }
            }
        }
        error "GetProperty: \"$propertyName\" is not a valid property name."
    }

#### GetPropertyName [::Office]Office, Top, Main

Get the name of a document property.

GetPropertyName propertyId

`propertyId` | Identifier of the Office property.

Returns the name of the property as string.

See also: SetDocumentProperty, GetDocumentProperty, AddProperty, GetProperty, DeleteProperty, GetPropertyType, GetPropertyValue, SetPropertyValue, GetDocumentProperties

Show source

    proc ::Office::GetPropertyName {propertyId} {

        # Get the name of a document property.
        #
        # propertyId - Identifier of the Office property.
        #
        # Returns the name of the property as string.
        #
        # See also: SetDocumentProperty GetDocumentProperty AddProperty GetProperty DeleteProperty
        #           GetPropertyType GetPropertyValue SetPropertyValue GetDocumentProperties

        set retVal [catch {$propertyId Name} propName]
        if { $retVal == 0 } {
            return $propName
        } else {
            return "N/A"
        }
    }

#### GetPropertyType [::Office]Office, Top, Main

Get the type of a document property.

GetPropertyType propertyId

`propertyId` | Identifier of the Office property.

Returns the type of the property as enumeration string. The enumeration is of type Enum::MsoDocProperties.

See also: SetDocumentProperty, GetDocumentProperty, AddProperty, GetProperty, DeleteProperty, GetPropertyName, GetPropertyValue, SetPropertyValue, GetDocumentProperties

Show source

    proc ::Office::GetPropertyType {propertyId} {

        # Get the type of a document property.
        #
        # propertyId - Identifier of the Office property.
        #
        # Returns the type of the property as enumeration string.
        # The enumeration is of type [Enum::MsoDocProperties].
        #
        # See also: SetDocumentProperty GetDocumentProperty AddProperty GetProperty DeleteProperty
        #           GetPropertyName GetPropertyValue SetPropertyValue GetDocumentProperties

        set retVal [catch {$propertyId Type} propType]
        if { $retVal == 0 } {
            return [Office GetEnumName "MsoDocProperties" $propType]
        } else {
            return "N/A"
        }
    }

#### GetPropertyValue [::Office]Office, Top, Main

Get the value of a document property.

GetPropertyValue propertyId

`propertyId` | Identifier of the Office property.

Returns the value of the property. If the property value is not set, the string `N/A` is returned.

See also: SetDocumentProperty, GetDocumentProperty, AddProperty, GetProperty, DeleteProperty, GetPropertyName, GetPropertyType, SetPropertyValue, GetDocumentProperties

Show source

    proc ::Office::GetPropertyValue {propertyId} {

        # Get the value of a document property.
        #
        # propertyId - Identifier of the Office property.
        #
        # Returns the value of the property.
        # If the property value is not set, the string `N/A` is returned.
        #
        # See also: SetDocumentProperty GetDocumentProperty AddProperty GetProperty DeleteProperty
        #           GetPropertyName GetPropertyType SetPropertyValue GetDocumentProperties

        set retVal [catch {$propertyId Value} propVal]
        if { $retVal == 0 } {
            return $propVal
        } else {
            return "N/A"
        }
    }

#### GetStartupPath [::Office]Office, Top, Main

Get the Office startup pathname.

GetStartupPath appId

`appId` | The application identifier.

Returns the startup pathname as a string.

Show source

    proc ::Office::GetStartupPath {appId} {

        # Get the Office startup pathname.
        #
        # appId - The application identifier.
        #
        # Returns the startup pathname as a string.

        set retVal [catch {$appId StartupPath} val]
        if { $retVal == 0 } {
            return $val
        } else {
            return "Method not available"
        }
    }

#### GetTemplatesPath [::Office]Office, Top, Main

Get the Office templates pathname.

GetTemplatesPath appId

`appId` | The application identifier.

Returns the templates pathname as a string.

Show source

    proc ::Office::GetTemplatesPath {appId} {

        # Get the Office templates pathname.
        #
        # appId - The application identifier.
        #
        # Returns the templates pathname as a string.

        set retVal [catch {$appId TemplatesPath} val]
        if { $retVal == 0 } {
            return $val
        } else {
            return "Method not available"
        }
    }

#### GetUserLibraryPath [::Office]Office, Top, Main

Get the Office user library pathname.

GetUserLibraryPath appId

`appId` | The application identifier.

Returns the user library pathname as a string.

Show source

    proc ::Office::GetUserLibraryPath {appId} {

        # Get the Office user library pathname.
        #
        # appId - The application identifier.
        #
        # Returns the user library pathname as a string.

        set retVal [catch {$appId UserLibraryPath} val]
        if { $retVal == 0 } {
            return $val
        } else {
            return "Method not available"
        }
    }

#### GetUserName [::Office]Office, Top, Main

Get the name of the Office application user.

GetUserName appId

`appId` | The application identifier.

Returns the name of the application user as a string.

Show source

    proc ::Office::GetUserName {appId} {

        # Get the name of the Office application user.
        #
        # appId - The application identifier.
        #
        # Returns the name of the application user as a string.

        set retVal [catch {$appId UserName} val]
        if { $retVal == 0 } {
            return $val
        } else {
            return "Method not available"
        }
    }

#### GetUserPath [::Office]Office, Top, Main

Get the Office user folder's pathname.

GetUserPath appId

`appId` | The application identifier.

Returns the user folder's pathname as a string.

Show source

    proc ::Office::GetUserPath {appId} {

        # Get the Office user folder's pathname.
        #
        # appId - The application identifier.
        #
        # Returns the user folder's pathname as a string.

        set retVal [catch {$appId DefaultFilePath} val]
        if { $retVal == 0 } {
            return $val
        } else {
            return "Method not available"
        }
    }

#### IsApplicationId [::Office]Office, Top, Main

Check, if Office object is an application identifier.

IsApplicationId objId

`objId` | The identifier of an Office object.

Returns true, if `$objId` is a valid Office application identifier. Otherwise return false.

See also: ::Cawt::IsComObject, GetApplicationId, GetApplicationName

Show source

    proc ::Office::IsApplicationId {objId} {

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

        set retVal [catch {$objId Version} errMsg]
        # Version is a property of all Office application classes.
        if { $retVal == 0 } {
            return true
        } else {
            return false
        }
    }

#### RgbToColor [::Office]Office, Top, Main

Obsolete: Replaced with ::Cawt::RgbToOfficeColor in version 2.2.0

RgbToColor r g b

`r` | Not documented.
`g` | Not documented.
`b` | Not documented.

Show source

    proc ::Office::RgbToColor {r g b} {

        # Obsolete: Replaced with [::Cawt::RgbToOfficeColor] in version 2.2.0

        return [Cawt RgbToOfficeColor $r $g $b]
    }

#### RunMacro [::Office]Office, Top, Main

Run a macro or function contained in an Office document.

RunMacro appId macroName ?args?

`appId` | The application identifier.
`macroName` | The name of the macro or function.
`args` | Up to 30 macro or function parameters.

Returns an empty string, if the macro is a procedure (Sub). If the macro is a Function, the return value of the function is returned. An error is thrown, if the macro does not exist or the execution of the macro fails.

See also: AddMacro

Show source

    proc ::Office::RunMacro {appId macroName args} {

        # Run a macro or function contained in an Office document.
        #
        # appId     - The application identifier.
        # macroName - The name of the macro or function.
        # args      - Up to 30 macro or function parameters.
        #
        # Returns an empty string, if the macro is a procedure (Sub).
        # If the macro is a Function, the return value of the function is returned.
        # An error is thrown, if the macro does not exist or the execution of the
        # macro fails.
        #
        # See also: AddMacro

        set retVal [catch { $appId -call Run $macroName {*}$args } val]
        if { $retVal == 0 } {
            return $val
        } else {
            error "RunMacro: $val"
        }
    }

#### SetDocumentProperty [::Office]Office, Top, Main

Set the value of a document property.

SetDocumentProperty objId propertyName propertyValue

`objId` | The identifier of an Office object (Workbook, Document, Presentation).
`propertyName` | The name of the property to set.
`propertyValue` | The value for the property. The specified value must match the type of the property, see GetPropertyType.

If the property name is a builtin property, its value is set. Otherwise either a new custom property is created and its value set or, if the custom property already exists, only its value is set.

Note:

- Some builtin properties are read-only. If trying to set the value of a read-only property, no error is generated by an Office application.
- Custom properties created with this procedure are string properties. If you need other property types, use AddProperty.

Returns no value.

See also: GetDocumentProperty, AddProperty, GetProperty, GetDocumentProperties, GetPropertyName, GetPropertyType, GetPropertyValue, SetPropertyValue, DeleteProperty

Show source

    proc ::Office::SetDocumentProperty {objId propertyName propertyValue} {

        # Set the value of a document property.
        #
        # objId         - The identifier of an Office object (Workbook, Document, Presentation).
        # propertyName  - The name of the property to set.
        # propertyValue - The value for the property.
        #                 The specified value must match the type of the property,
        #                 see [GetPropertyType].
        #
        # Returns no value.
        #
        # If the property name is a builtin property, its value is set.
        # Otherwise either a new custom property is created and its value set or,
        # if the custom property already exists, only its value is set.
        #
        # **Note:**
        #  * Some builtin properties are read-only. If trying to set the value of
        #    a read-only property, no error is generated by an Office application.
        #  * Custom properties created with this procedure are string properties.
        #    If you need other property types, use [AddProperty].
        #
        # See also: GetDocumentProperty AddProperty GetProperty GetDocumentProperties
        #           GetPropertyName GetPropertyType GetPropertyValue SetPropertyValue DeleteProperty

        set retVal [catch {Office GetProperty $objId $propertyName} propertyId]
        if { $retVal != 0 } {
            set propertyId [Office AddProperty $objId $propertyName]
        }
        Office SetPropertyValue $propertyId $propertyValue
        Cawt Destroy $propertyId
    }

#### SetPrinterCommunication [::Office]Office, Top, Main

Enable or disable printer communication.

SetPrinterCommunication objId onOff

`objId` | The identifier of an Office object.
`onOff` | If set to true, printer communication is enabled. Otherwise printer communication is disabled.

Disable the printer communication to speed up the execution of code that sets PageSetup properties, ex. ::Excel::SetWorksheetPrintOptions. Enable the printer communication after setting properties to commit all cached PageSetup commands.

Note: This method is only available in Office 2010 or newer.

Returns no value.

See also: GetActivePrinter

Show source

    proc ::Office::SetPrinterCommunication {objId onOff} {

        # Enable or disable printer communication.
        #
        # objId - The identifier of an Office object.
        # onOff - If set to true, printer communication is enabled.
        #         Otherwise printer communication is disabled.
        #
        # Disable the printer communication to speed up the execution of code
        # that sets PageSetup properties, ex. [::Excel::SetWorksheetPrintOptions].
        # Enable the printer communication after setting properties to commit
        # all cached PageSetup commands.
        #
        # **Note:** This method is only available in Office 2010 or newer.
        #
        # Returns no value.
        #
        # See also: GetActivePrinter

        if { ! [Office IsApplicationId $objId] } {
            set appId [Office GetApplicationId $objId]
            catch {$appId -call PrintCommunication [Cawt TclBool $onOff]}
            Cawt Destroy $appId
        } else {
            catch {$objId -call PrintCommunication [Cawt TclBool $onOff]}
        }
    }

#### SetPropertyValue [::Office]Office, Top, Main

Set the value of a document property.

SetPropertyValue propertyId propertyValue

`propertyId` | Identifier of the Office property.
`propertyValue` | The value for the property. The specified value must match the type of the property, see GetPropertyType.

Returns no value.

See also: SetDocumentProperty, GetDocumentProperty, AddProperty, GetProperty, DeleteProperty, GetPropertyName, GetPropertyType, GetPropertyValue, GetDocumentProperties

Show source

    proc ::Office::SetPropertyValue {propertyId propertyValue} {

        # Set the value of a document property.
        #
        # propertyId    - Identifier of the Office property.
        # propertyValue - The value for the property.
        #                 The specified value must match the type of the property,
        #                 see [GetPropertyType].
        #
        # Returns no value.
        #
        # See also: SetDocumentProperty GetDocumentProperty AddProperty GetProperty DeleteProperty
        #           GetPropertyName GetPropertyType GetPropertyValue GetDocumentProperties

        set propertyType [Office GetPropertyType $propertyId]
        switch -- $propertyType {
            "msoPropertyTypeBoolean" { set val [Cawt TclBool $propertyValue] }
            "msoPropertyTypeString"  { set val [Cawt TclString $propertyValue] }
            "msoPropertyTypeNumber"  { set val [expr { int ($propertyValue) }] }
            "msoPropertyTypeDate"    { set val [expr { double ($propertyValue) }] }
            "msoPropertyTypeFloat"   { set val [expr { double ($propertyValue) }] }
            default { error "SetPropertyValue: Unknown property type \"$propertyType\"" }
        }
        $propertyId Value $val
    }

#### ShowAlerts [::Office]Office, Top, Main

Obsolete: Replaced with module specific procedures in version 2.4.3

ShowAlerts appId onOff

`appId` | Not documented.
`onOff` | Not documented.

Toggle the display of Office alerts.

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

Returns no value.

Show source

    proc ::Office::ShowAlerts {appId onOff} {

        # Obsolete: Replaced with module specific procedures in version 2.4.3
        #
        # Toggle the display of Office alerts.
        #
        # appId - The application identifier.
        # onOff - Switch the alerts on or off.
        #
        # Returns no value.

        if { $onOff } {
            if { [Office GetApplicationName $appId] eq "Microsoft Word" } {
                set alertLevel [expr $Word::wdAlertsAll]
            } else {
                set alertLevel [expr 1]
            }
        } else {
            set alertLevel [expr 0]
        }
        $appId -call DisplayAlerts $alertLevel
    }

# Start page

# Cawt

# Office

# Excel

# Ppt

# Word

# Outlook

# OneNote

# Office::Enum

# Excel::Enum

# Ppt::Enum

# Word::Enum

# Outlook::Enum

# OneNote::Enum

# Earth

# Explorer

# Ocr

# Reader

# Matlab

# Office

## Commands

#### AddMacro Add macros or functions to an Office document.

#### AddProperty Add a custom document property.

#### ColorToRgb Obsolete: Replaced with ::Cawt::OfficeColorToRgb in version 2.2.0

#### DeleteProperty Delete a document property.

#### GetActivePrinter Get the name of the active printer.

#### GetApplicationId Get the application identifier of an Office object.

#### GetApplicationName Get the name of an Office application.

#### GetApplicationVersion Get the version number of an Office application.

#### GetDocumentProperties Get document property names as a list.

#### GetDocumentProperty Get the value of a document property.

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

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

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

#### GetEnumTypes Get available enumeration types.

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

#### GetInstallationPath Get the Office installation pathname.

#### GetOfficeType Get the Office type of a file.

#### GetProperty Get a document property.

#### GetPropertyName Get the name of a document property.

#### GetPropertyType Get the type of a document property.

#### GetPropertyValue Get the value of a document property.

#### GetStartupPath Get the Office startup pathname.

#### GetTemplatesPath Get the Office templates pathname.

#### GetUserLibraryPath Get the Office user library pathname.

#### GetUserName Get the name of the Office application user.

#### GetUserPath Get the Office user folder's pathname.

#### IsApplicationId Check, if Office object is an application identifier.

#### RgbToColor Obsolete: Replaced with ::Cawt::RgbToOfficeColor in version 2.2.0

#### RunMacro Run a macro or function contained in an Office document.

#### SetDocumentProperty Set the value of a document property.

#### SetPrinterCommunication Enable or disable printer communication.

#### SetPropertyValue Set the value of a document property.

#### ShowAlerts Obsolete: Replaced with module specific procedures in version 2.4.3

Document generated by Ruff!