The Office
namespace provides commands for basic Office automation functionality.
Add macros or functions to an Office document.
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
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 $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 } 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 } 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." } }
Obsolete: Replaced with ::Cawt::OfficeColorToRgb in version 2.2.0
color | Not documented. |
proc ::Office::ColorToRgb {color} { # Obsolete: Replaced with [::Cawt::OfficeColorToRgb] in version 2.2.0 return [Cawt OfficeColorToRgb $color] }
Get the name of the active printer.
appId | The 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" } }
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
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] }
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
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] } }
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
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 }
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. 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] }
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
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 }
Get numeric value of an enumeration.
enumOrString | Enumeration 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] } }
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
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 }
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
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] } }
Get available enumeration types.
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]] }
Get numeric value of an enumeration name.
enumName | Enumeration 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 "" }
Get the Office installation pathname.
appId | The 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" } }
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
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 "" } }
Get the Office startup pathname.
appId | The 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" } }
Get the Office templates pathname.
appId | The 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" } }
Get the Office user library pathname.
appId | The 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" } }
Get the name of the Office application user.
appId | The 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" } }
Get the Office user folder's pathname.
appId | The 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" } }
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
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 } }
Obsolete: Replaced with ::Cawt::RgbToOfficeColor in version 2.2.0
r | Not documented. |
g | Not documented. |
b | Not documented. |
proc ::Office::RgbToColor {r g b} { # Obsolete: Replaced with [::Cawt::RgbToOfficeColor] in version 2.2.0 return [Cawt RgbToOfficeColor $r $g $b] }
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
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 Run $macroName {*}$args } val] if { $retVal == 0 } { return $val } else { error "RunMacro: $val" } }
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. |
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 } }
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
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]} } }
Obsolete: Replaced with module specific procedures in version 2.4.3
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.
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 }