::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
colorNot documented.
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
appIdThe application identifier.

Returns the name of the active printer as a string.

See also: SetPrinterCommunication

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
objIdThe identifier of an Office object.

Office object are Workbooks, Worksheets, ...

Returns the application identifier of the Office object.

See also: GetApplicationName, IsApplicationId

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
objIdThe identifier of an Office object.

Returns the name of the application as a string.

See also: GetApplicationId, IsApplicationId

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
objIdThe identifier of an Office object.

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

See also: GetApplicationId, GetApplicationName

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?
objIdThe identifier of an Office object (Workbook, Document, Presentation).
typeType 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

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
objIdThe identifier of an Office object (Workbook, Document, Presentation).
propertyNameThe 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

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
enumOrStringEnumeration name

Returns the numeric value of an enumeration.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnumNames

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
enumTypeEnumeration type
enumValEnumeration numeric value.

Returns the list of names of a given enumeration type.

See also: GetEnumNames, GetEnumTypes, GetEnumVal, GetEnum

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
enumTypeEnumeration type

Returns the list of names of a given enumeration type.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnum

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

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
enumNameEnumeration name

Returns the numeric value of an enumeration name.

See also: GetEnumName, GetEnumTypes, GetEnumNames, GetEnum

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
appIdThe application identifier.

Returns the installation pathname as a string.

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

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
appIdThe application identifier.

Returns the startup pathname as a string.

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
appIdThe application identifier.

Returns the templates pathname as a string.

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
appIdThe application identifier.

Returns the user library pathname as a string.

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
appIdThe application identifier.

Returns the name of the application user as a string.

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
appIdThe application identifier.

Returns the user folder's pathname as a string.

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
objIdThe identifier of an Office object.

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

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

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
rNot documented.
gNot documented.
bNot documented.
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
objIdThe identifier of an Office object (Workbook, Document, Presentation).
propertyNameThe name of the property to set.
propertyValueThe 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

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
objIdThe identifier of an Office object.
onOffIf 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

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
appIdNot documented.
onOffNot documented.

Toggle the display of Office alerts.

appIdThe application identifier.
onOffSwitch the alerts on or off.

Returns no value.

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