Word UDF: Difference between revisions

From AutoIt Wiki
Jump to navigation Jump to search
No edit summary
m (replacing uppercase text)
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{WIP}}
The Word UDF offers functions to control and manipulate Microsoft Word documents.<br />
The Word UDF offers functions to control and manipulate Microsoft Word documents.<br />
This page describes the Word UDF that comes with AutoIt 3.3.8.1 or later.
This page describes the Word UDF that comes with AutoIt 3.3.10.0 or later.


== Features ==
== Features ==
Line 12: Line 11:
* Supports reading/writing of tables
* Supports reading/writing of tables
* Support for every file format Word supports
* Support for every file format Word supports
<br />
The UDF only covers basic user needs. Single line functions (like getting document properties) or functions with too many parameters (like running a macro) are not covered by this UDF. You need to use the Word COM yourself.


== Concepts ==
== Concepts ==
Good reading: [http://www.add-in-express.com/creating-addins-blog/2013/08/07/word-document-content-objects/ Working with Word document content objects]
=== Range ===
=== Range ===
A Range is a block made of one or more characters that Word treats as a unit. The functions of the UDF mainly work with ranges. A range - unlike a selection - is not visible on the screen.
A Range is a block made of one or more characters that Word treats as a unit. The functions of the UDF mainly work with ranges. A range - unlike a selection - is not visible on the screen.
 
Example:<syntaxhighlight lang="autoit">
== Features not covered by the UDF ==
Global $oWord = _Word_Create()
The UDF only covers basic user needs. Single line functions (like getting document properties) or functions with too many parameters (like running a macro) are not covered by this UDF. You need to use the Word COM yourself.<br />
Global $oDoc = _Word_DocAdd($oWord)
I will give a few examples here. The rest can be found on [http://msdn.microsoft.com/en-us/library/ff846392.aspx MSDN].
Global $oRange = _Word_DocRangeSet($oDoc, 0) ; Use current selection
 
$oRange.Insertafter("INSERTED TEXT") ; Insert Text
=== Format a range ===
$oRange = _Word_DocRangeSet($oDoc, $oRange, $WdCollapseEnd) ; Collapse the start of the range to the end position (create an insertion mark)
==== Alignment ====
<syntaxhighlight lang="autoit">
; Horizontal alignment
; Enumeration for Excel 2010: http://msdn.microsoft.com/en-us/library/ff840772%28v=office.14%29.aspx
$oRange.HorizontalAlignment = $XlHAlign ; Can be xlCenter, xlDistributed, xlJustify, xlLeft or xlRight of the XlHAlign enumeration.
 
; Vertical alignment
; Enumeration for Excel 2010: http://msdn.microsoft.com/en-us/library/ff835305%28v=office.14%29.aspx
$oRange.VerticalAlignment = $XlVAlign ; Can be xlBottom, xlCenter, xlDistributed, xlJustify or xlTop of the XlVAlign enumeration.
</syntaxhighlight>
</syntaxhighlight>


==== Background ====
== Functions ==
...
=== _Word_DocFindReplace ===
==== Border ====
This function supports wildcards.
...
The following [http://wordmvp.com/FAQs/General/UsingWildcards.htm document] is a good reading regarding wildcards.<br /><br />
==== Color ====
To find and replace a string not only in the main text but everywhere in the document (including headers, footnotes etc.) please have a look at this [https://wordmvp.com/FAQs/MacrosVBA/FindReplaceAllWithVBA.htm article]<br /><br />
...
Microsoft limits the replacement text to 255 characters. How to overcome this limitation (and how to do it in AutoIt) is described [https://www.autoitscript.com/forum/topic/196814-_word_docfindreplace-max-replacement-text-length/ here].<br /><br />
==== Font ====
When replacing uppercase text you might get some unexpected results. More details can be found [https://www.autoitscript.com/forum/topic/208720-_word_docfindreplace-help-example-adds-replaced-text-as-all-caps/ here].
===== Bold etc. =====
True if the font is bold. Read/write.
<syntaxhighlight lang="autoit">$oRange.Font.Bold = True</syntaxhighlight>
This works similar for ''Italic'', ''Strikethrough'', ''Subscript'', ''Superscript'' and ''Underline''.
 
===== Color, ColorIndex =====
Color: Returns or sets the primary color of the object. Use the RGB function to create a color value.<br />
ColorIndex: Returns or sets a variant value that represents the color of the font.
The color is specified as an index value into the current color palette.
{| class="wikitable"
|-
! Object !! Color
|-
| Border || The color of the border.
|-
| Borders || The color of all four borders of a range. If they're not all the same color, Color returns 0 (zero).
|-
| Font || The color of the font.
|-
| Interior || The cell shading color or the drawing object fill color.
|-
| Tab || The color of the tab.
|}
 
<syntaxhighlight lang="autoit">$oRange.Font.Color = 5 ; Set the color of the font
$oRange.Borders.ColorIndex = 5 ; Set the color of all four borders
</syntaxhighlight>
 
===== Name =====
Returns or sets a variant value that represents the name of the font.
<syntaxhighlight lang="autoit">$oRange.Font.Name = "Arial"</syntaxhighlight>
 
===== Size =====
Returns or sets the size of the font specified in units of points.
<syntaxhighlight lang="autoit">$oRange.Font.Size = 12</syntaxhighlight>
 
===== Underline =====
Returns or sets the type of underline applied to the font. Can be one of the XlUnderlineStyle constants xlUnderlineStyleNone, xlUnderlineStyleSingle, xlUnderlineStyleDouble,
xlUnderlineStyleSingleAccounting or xlUnderlineStyleDoubleAccounting. Read/write.
<syntaxhighlight lang="autoit">$oRange.Font.Underline = $xlUnderlineStyleSingle</syntaxhighlight>
 
==== Height/Width ====
...
==== Number Format ====
Returns or sets a variant value that represents the format code for the object.<br />
This property returns Null if all cells in the specified range don't have the same number format.<br />
The format code is the same string as the Format Codes option in the Format Cells dialog box. The Format function uses different format code strings than do the NumberFormat and NumberFormatLocal properties.
<syntaxhighlight lang="autoit">$oRange.NumberFormat = "General"
$oRange.NumberFormat = "hh:mm:ss"
$oRange.NumberFormat = "$#,##0.00_);[Red]($#,##0.00)"</syntaxhighlight>


###################
The Word UDF offers functions to control and manipulate Microsoft Word documents.
== Script breaking changes after AutoIt version 3.3.8.1 ==
== Script breaking changes after AutoIt version 3.3.8.1 ==
New versions of Microsoft Office have been released since the last changes were made to the Word UDF. New file types and new functions needed to be supported, hence the UDF was complete rewritten.
New versions of Microsoft Office have been released since the last changes were made to the Word UDF. New file types and new functions needed to be supported, hence the UDF was complete rewritten.

Latest revision as of 06:19, 28 August 2022

The Word UDF offers functions to control and manipulate Microsoft Word documents.
This page describes the Word UDF that comes with AutoIt 3.3.10.0 or later.

Features

New versions of Microsoft Office have been released since the last changes were made to the Word UDF. The new extensions (e.g. docx) were not (fully) supported, new functions were missing etc. The current version of the Word UDF lifts this limitations.

  • Works with as many instances of Word as you like - not just one
  • Works with any document - not just the active one
  • Only does what you tell it to do - no implicit "actions"
  • Works with ranges and lets you move the insert marker
  • Supports reading/writing of tables
  • Support for every file format Word supports


The UDF only covers basic user needs. Single line functions (like getting document properties) or functions with too many parameters (like running a macro) are not covered by this UDF. You need to use the Word COM yourself.

Concepts

Good reading: Working with Word document content objects

Range

A Range is a block made of one or more characters that Word treats as a unit. The functions of the UDF mainly work with ranges. A range - unlike a selection - is not visible on the screen.

Example:

Global $oWord = _Word_Create() 
Global $oDoc = _Word_DocAdd($oWord) 
Global $oRange = _Word_DocRangeSet($oDoc, 0) ; Use current selection
$oRange.Insertafter("INSERTED TEXT") ; Insert Text
$oRange = _Word_DocRangeSet($oDoc, $oRange, $WdCollapseEnd) ; Collapse the start of the range to the end position (create an insertion mark)

Functions

_Word_DocFindReplace

This function supports wildcards. The following document is a good reading regarding wildcards.

To find and replace a string not only in the main text but everywhere in the document (including headers, footnotes etc.) please have a look at this article

Microsoft limits the replacement text to 255 characters. How to overcome this limitation (and how to do it in AutoIt) is described here.

When replacing uppercase text you might get some unexpected results. More details can be found here.

Script breaking changes after AutoIt version 3.3.8.1

New versions of Microsoft Office have been released since the last changes were made to the Word UDF. New file types and new functions needed to be supported, hence the UDF was complete rewritten.

Some functions/parameters have been removed or renamed, new functions/parameters have been added. A detailed list of changes can be found here.

General

All function names have been changed from _Word* to _Word_*.

@extended no longer contains the number of the invalid parameter. The code returned in @error tells exactly what went wrong.

The following list shows the old/new function/parameter name (a "-" is shown if the function/parameter has been removed) and some example scripts how to mimic the behaviour of the "old" UDF. If there is no entry for a removed function/parameter then there is no need for this functionality.

Function _WordCreate/_Word_Create

It's mandatory now to call function _Word_Create before any other function. You could have used _WordCreate or _WordAttach in the old Word UDF. @extended is set if Word was already running.

Parameter $s_FilePath/-

Optional parameter to specify the file to open upon creation. Use _Word_DocOpen or _Word_DocAdd now.

Function _WordDocPropertyGet/-

Retrieves builtin document properties.

Word object model reference on MSDN for Word 2010:

Example code:

Global $oWord = _Word_Create() 
Global $oDoc = _Word_DocOpen($oWord, @ScriptDir & "\test.doc") 
Global $wdPropertyAuthor = 3 
Global $sAuthor = $oDoc.BuiltInDocumentProperties($wdPropertyAuthor).Value ; Retrieves the Author of the document

Function _WordDocPropertySet/-

Sets builtin document properties.

For links to the Word object model reference on MSDN see function _WordDocPropertyGet.

Example code:

Global $oWord = _Word_Create() 
Global $oDoc = _Word_DocOpen($oWord, @ScriptDir & "\test.doc") 
Global $wdPropertyAuthor = 3 
$oDoc.BuiltInDocumentProperties($wdPropertyAuthor).Value = "PowerUser" ; Sets the Author of the document

Function _WordErrorHandlerDeRegister/_DebugCOMError

The default COM error handler has been moved to the Debug UDF. See _WordErrorHandlerRegister for details.

Function _WordErrorHandlerRegister/_DebugCOMError

The default COM error handler has been moved to the Debug UDF. But you can still create a custom COM error handler by using ObjEvent.

Example code:

#include <Debug.au3>
_DebugSetup("Word Debug Window", True, 1, "", True)
_DebugCOMError(1) ; Register a default COM error handler to grab Word COM errors and write the messages to the Debug window
; Do Word processing here
_DebugCOMError(0) ; DeRegister the default COM error handler

Function _WordErrorNotify/-

The Word UDF no longer creates text error messages and writes them to the Console.

You need to check the macros @error and @extended after you called a function. The returned values are documented in the help file.

Function _WordMacroRun/-

A macro can now be run by a single line.

Example code:

Global $oWord = _Word_Create() 
Global $oDoc = _Word_DocOpen($oWord, @ScriptDir & "\test.doc") 
$oWord.Run("macro_name")

Function _WordPropertyGet/-

Retrieves application and document properties. Many of the properties for the Options object correspond to items in the Options dialog box.

Word object model reference on MSDN for Word 2010:

Example code:

Global $oWord = _Word_Create() 
$bVisible = $oWord.Visible ; Returns True when the Word application is visible, else False
$bUpdatePrint = $oWord.Options.UpdateFieldsAtPrint ; True if Microsoft Word updates fields automatically before printing a document

Function _WordPropertySet/-

Sets application and document properties. Many of the properties for the Options object correspond to items in the Options dialog box.

For links to the Word object model reference on MSDN see function _WordPropertyGet.

Example code:

Global $oWord = _Word_Create() 
$bVisible = $oWord.Options.SaveInterval = 5 ; Sets Word to save AutoRecover information for all open documents every five minutes