CAWT 2.4.7 Reference Manual

# ::OfficeMain

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

## CommandsOffice, Main

#### ColorToRgb [::Office]Office, 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]
    }

#### GetActivePrinter [::Office]Office, 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, 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, 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, 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, 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 (`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: GetDocumentProperty, SetDocumentProperty

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 (`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: GetDocumentProperty SetDocumentProperty

        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, 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: GetDocumentProperties, SetDocumentProperty

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: GetDocumentProperties SetDocumentProperty

        set properties [Office GetDocumentProperties $objId]
        if { [lsearch $properties $propertyName] >= 0 } {
            set propsBuiltin [$objId BuiltinDocumentProperties]
            set retVal [catch {$propsBuiltin -get Item $propertyName} property]
            Cawt Destroy $propsBuiltin
            if { $retVal != 0 } {
                set propsCustom  [$objId CustomDocumentProperties]
                set retVal [catch {$propsCustom -get Item $propertyName} property]
                Cawt Destroy $propsCustom
                if { $retVal != 0 } {
                    set propertyValue "N/A"
                } else {
                    set propertyValue [_GetPropertyValue $property]
                    Cawt Destroy $property
                }
            } else {
                set propertyValue [_GetPropertyValue $property]
                Cawt Destroy $property
            }
        } else {
            error "GetDocumentProperty: \"$propertyName\" is not a valid property name."
        }
        return $propertyValue
    }

#### GetEnum [::Office]Office, 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, 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, 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, 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, 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, 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, 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 [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 ""
        }
    }

#### GetStartupPath [::Office]Office, 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, 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, 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, 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, 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, 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, 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]
    }

#### SetDocumentProperty [::Office]Office, 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 as string.

If the property name is a builtin property, it's value is set. Otherwise either a new custom property is generated and it's value set or, if the custom property already exists, only it's value is set.

Returns no value.

See also: GetDocumentProperties, GetDocumentProperty

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 as string.
        #
        # Returns no value.
        #
        # If the property name is a builtin property, it's value is set.
        # Otherwise either a new custom property is generated and it's value set or,
        # if the custom property already exists, only it's value is set.
        #
        # See also: GetDocumentProperties GetDocumentProperty

        set properties [Office GetDocumentProperties $objId "Builtin"]
        if { [lsearch -exact $properties $propertyName] >= 0 } {
            set propsBuiltin [$objId BuiltinDocumentProperties]
            $propsBuiltin -set Item $propertyName $propertyValue
            Cawt Destroy $propsBuiltin
        } else {
            set properties [Office GetDocumentProperties $objId "Custom"]
            set propsCustom [$objId CustomDocumentProperties]
            if { [lsearch -exact $properties $propertyName] >= 0 } {
                $propsCustom -set Item $propertyName $propertyValue
            } else {
                $propsCustom Add $propertyName [Cawt TclBool false] 4 $propertyValue
            }
            Cawt Destroy $propsCustom
        }
    }

#### SetPrinterCommunication [::Office]Office, 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 PrintCommunication [Cawt TclBool $onOff]}
            Cawt Destroy $appId
        } else {
            catch {$objId PrintCommunication [Cawt TclBool $onOff]}
        }
    }

#### ShowAlerts [::Office]Office, 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 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

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

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

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

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

#### SetPrinterCommunication Enable or disable printer communication.

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

Document generated by Ruff!