Copyright: Copyright (c) 1996-2003 Rainier Software Solutions


Contents

What is WordController Plus?

Installation and Use

Objects, Properties and Methods

Word Templates and Data Sources

Error Handling

WordController In Action - Creating A Form Letter

Sample Visual Basic Code

Technical Support


What is WordController Plus?

WordController Plus is an is an ActiveX component which allows Developers to quickly and easily integrate their applications with multiple versions of Microsoft Word™.

Developers who wish to integrate with Word face a major problem with regard to the different behaviour of different Word versions. Applications which are written for one version of Word do not necessarily work when run on a workstation which has a different version installed.

Developers do not want to have to specify that their Users have a particular version, nor do they want to revisit their applications when the next version of Word is released. WordController Plus addresses these issues by adding a layer on top of the functionality exposed by Word, detecting what version is present at runtime and executing code that will work with that version. It is now possible to write one set of code which can be deployed to users without worrying what version of Word they have. And when the next version of Word is released let us worry about testing its behaviour and making any changes necessary to ensure that the WordController functions behave in a manner as consistent as possible with the earlier versions.

Further, WordController aggregates some very complex Word functionality into high level new functions which allow the Developer to do the most commonly required tasks: open documents; generate form letters; build tables; do mail merges etc. with just one or two lines of code and without any need to understand the complex Word object model. An example of this is the wdcBuildTemplateDocument function which does all the processing associated with generating (and optionally printing) a template-based form letter or report with a single function call.

With the help of WordController Plus a client application can

•	determine if Word is running and return the Word window handle

•	launch Word in any state (hidden, normal, minimized, maximized)

•	open Word documents (optionally with password and/or read only) and create new documents (optionally from templates)

•	build form letters based on Word templates

•	perform Word MailMerges to produce merge documents or labels based on templates

•	create documents from data in text files

•	move within and between documents, insert text, files and graphics. Apply styles and formatting

•	create Word tables from data contained in text files. If desired the tables can be embedded in Word template documents.

•	replace all occurrences of a string in an open document with another string

•	retrieve and set document properties

•	protect and unprotect sections or complete documents

•	print, save, convert and close documents

•	make use of Word's spellchecking functionality

•	run Word macros

•	close Word

Using combinations of the WordController functions the Developer can do most of the things he or she would normally need to do without needing to learn the old WordBasic or the newer Word object model. But WordController also provides access to the native Word.Basic and Word.Application objects exposed by Word itself so you can code additional functionality if you wish.

WordController also offers sophisticated error handling. Many things can go wrong when working with a 3rd party application on a machine over which you have no control. WordController allows you to trap errors in a professional manner and return friendly error codes and text to the calling application to be acted upon as the Developer chooses. For more information on this see Error Handling.

When the WordController component is installed on the workstation, a Developer building an application with a product which supports the use of ActiveX components (such as Visual Basic or Delphi) can access any of the WordController methods (functions) and properties from within their code.

WordController is a 32-bit in-process OLE server DLL which may be used on any 32-bit Windows platform (NT/2000 or 95/98/Me). ). It can be used with Word versions 6.0, 95, 97, 2000, 2002 (Office XP) or 2003. A few WordController functions do not work with the pre-97 versions as they offer functionality which was not available in these versions but where this is the case it is clearly pointed out in the documentation (see individual function descriptions for details) and the functions do not fail  instead they return a trappable error indicating that that version of Word does not support that functionality. This allows the Developer to handle the exception smoothly and avoid unpleasant application failures.

WordController includes a sample Visual Basic project which demonstrates how to call the component functions.


Installation and Use

To use the WordController Plus component during development it is first necessary to install it on the developer workstation. This is done by executing the supplied installation program. The setup program installs the DLL and makes the appropriate entries in the system registry. It is NOT sufficient merely to copy the DLL onto the workstation. Note that, as with any other ActiveX component or custom control, it will also be necessary to deploy the component with any application which uses its functions.

Once the component has been installed on the developer workstation, it can be referenced by any development tool that supports the containment of ActiveX controls. This document contains example code for Microsoft Visual Basic or VBA (Visual Basic for Applications, as supported by Microsoft Excel, Access and Word itself).

If the development tool supports object references then the component reference should be added to the project. In Visual Basic this is done by selecting Project…References and choosing the WordController Plus component from the list supplied. In the Microsoft Office Visual Basic Editor the appropriate menu item is Tools…References.

If the development tool does not support project references then it will usually offer a CreateObject command or equivalent which will load the DLL into memory and make its methods and properties available for use. The CreateObject statement requires a string class identifier parameter which is resolved through the Windows registry to obtain the physical location of the DLL to load. An example CreateObject in Visual Basic would be

Dim wdcObj as Object

Set wdcObj = CreateObject("WordController.WordControl5")

Note: The above code is for WordController v5.x, earlier versions used

Set wdcObj = CreateObject("WordController.WordControl")

This would load the component into memory and establish a reference to it so that its functions and properties could be manipulated. Such a statement would not be required if a project reference had been defined. In this case it would simply be necessary to use the New keyword when declaring the object variable:

Dim wdcObj as New WordController.WordControl5

or simply

Dim wdcObj as New WordControl5

Now the component methods and properties can be accessed by making reference to the declared object variable. For example:

to launch Word

RetCode = wdcObj.wdcLaunch

to set error display on

wdcObj.DisplayErrors = True


Objects, Properties and Methods

WordController exposes a single object named WordControl5. This section defines the Properties and Methods of this object.

All example code shown is Visual Basic. In the examples wdcObj refers to a WordControl5 object that has been previously declared with

Dim wdcObj as New WordControl5

Properties

DisplayErrors

ErrorText

IsV2000OrLater

IsV2002OrLater

IsV2003OrLater

IsV97OrLater

ResultValue

ReturnCode

WordApp

WordBasic

WordVersion

Methods

wdcActivateDocumentWindow

wdcApplyStyle

wdcApplyTableAutoFormat

wdcApplyTableStyle

wdcBookmarkExists

wdcBuildDocumentFromTemplate

wdcBuildDocumentFromTemplateRTF

wdcClearSelection

wdcClose

wdcCloseAllDocuments

wdcCloseDocument

wdcConvertTextToTable

wdcCopy

wdcCut

wdcFormatParagraph

wdcFreeze

wdcGetActiveDocumentName

wdcGetBookmarkNames

wdcGetDocumentProperty

wdcGetDocumentWindowCount

wdcGetDocumentWindowName

wdcGetSelectedText

wdcGetWordWindowHandle

wdcGoTo

wdcInsertBookmark

wdcInsertContentAtBookmark

wdcInsertFile

wdcInsertPageBreak

wdcInsertPicture

wdcInsertSectionBreak

wdcInsertTable

wdcInsertText

wdcLaunch

wdcLaunchNewInstance

wdcMailMergeDocument

wdcMailMergeDocWithOptions

wdcMailMergeLabels

wdcMailMergeLblWithOptions

wdcNewDocument

wdcOpenDocument

wdcPaste

wdcPrintDocument

wdcProtectDocument

wdcReplaceAll

wdcReplaceBookmarkWithText

wdcRunMacro

wdcRunMacroWithParameters

wdcSaveDocument

wdcSaveDocumentAs

wdcSaveDocumentAsType

wdcSelectTable

wdcSelectTableCell

wdcSelectTableColumn

wdcSelectTableRow

wdcSetDocumentProperty

wdcSetFont

wdcSetSectionProtection

wdcSetTableColumnWidth

wdcSetTableRowHeight

wdcSetWindowViewType

wdcTextFileToDocument

wdcTextFileToTable

wdcUnFreeze

wdcUnprotectDocument


DisplayErrors Property

wdcObj.DisplayErrors

Determines whether error messages are automatically displayed by the component. Set to True to turn error messages on. Default value is False.

See also Error Handling


ReturnCode Property

wdcObj.ReturnCode

Returns the numeric return code from the most recent function/method call. This value is used to determine whether or not the method completed successfully. Negative values for ReturnCode indicate that an error has occurred. A ReturnCode of zero indicates success. Occasionally a non-zero positive return code can also indicate success so the best way to test for an error condition is to use

If wdcObj.ReturnCode < 0 Then …

See also ResultValue


ResultValue Property

wdcObj.ResultValue

Returns the result value from the most recent function/method call. Where methods do not return any value and in these cases ResultValue is set to an empty string.

See also ReturnCode


ErrorText Property

wdcObj.ErrorText

Returns the error text (if any) from the most recent function/method call.

See also Error Handling


IsV2000OrLater Property

wdcObj.IsV2000OrLater

Returns True (-1) if the version of Word currently being managed by WordController is Word 2000 or later, otherwise returns False (0). Word must have been previously been launched with wdcLaunch or wdcLaunchNewInstance.

See also IsV97OrLater, IsV2002OrLater, IsV2003OrLater


IsV2002OrLater Property

wdcObj.IsV2002OrLater

Returns True (-1) if the version of Word currently being managed by WordController is Word 2002 or later, otherwise returns False (0). Word must have been previously been launched with wdcLaunch or wdcLaunchNewInstance.

See also IsV97OrLater, IsV2000OrLater, IsV2003OrLater


IsV2003OrLater Property

wdcObj.IsV2003OrLater

Returns True (-1) if the version of Word currently being managed by WordController is Word 2003 or later, otherwise returns False (0). Word must have been previously been launched with wdcLaunch or wdcLaunchNewInstance.

See also IsV97OrLater, IsV2000OrLater, IsV2002OrLater


IsV97OrLater Property

wdcObj.IsV97OrLater

Returns True (-1) if the version of Word currently being managed by WordController is Word 97 or later, otherwise returns False (0). Word must have been previously been launched with wdcLaunch or wdcLaunchNewInstance.

See also IsV2000OrLater, IsV2002OrLater, IsV2003OrLater


WordVersion Property

wdcObj.WordVersion

Returns the version of Word currently being managed by WordController. Word must have been previously been launched with wdcLaunch or wdcLaunchNewInstance.

The version is returned as a string. The version for the first release of Word 2000, for example, is "9.0".

See also ReturnCode, wdcLaunch, wdcLaunchNewInstance.


WordApp Property

wdcObj.WordApp

Returns the Word.Application object for the instance of Word being managed by WordController. This is provided so that the Developer can make additional calls to Word to perform any required functions supported by Word but not supported directly by WordController.

For information on the objects, properties and methods associated with the Word.Application object see the Microsoft Word Visual Basic Reference for Word 97 or later.

Word Version Note: The Word.Application object is only supported by Word 97 and later versions. If the version of Word installed is an earlier version this object will be set to Nothing. Use property IsV97OrLater to test for this. For earlier versions see the WordBasic property.

See also WordBasic, IsV97OrLater.


WordBasic Property

wdcObj.WordBasic

Returns the Word.Basic object for the instance of Word being managed by WordController. This is provided so that the Developer can make additional calls to Word to perform any required functions supported by Word but not supported directly by WordController.

For information on the objects, properties and methods associated with the Word.Basic object see the Microsoft WordBasic Reference for Word 95 or earlier.

Word Version Note: The functionality provided by the Word.Basic object was superseded in Word 97 by the Word.Application object. However Word.Basic is still supported (at least up to Word 2003).

See also WordApp, IsV97OrLater.


wdcActivateDocumentWindow

wdcObj.wdcActivateDocumentWindow(WindowCaption)

Purpose:

Activates an open Word document window given the title of the document window. It is intended for use when more than one document window may be open.

WindowCaption is the caption of the document window to activate. It must match exactly the caption as shown by Word, including any additional text such as "(Read-Only)". The wdcGetActiveDocumentName function may be used to retrieve a window title for later use by this function.

See also wdcGetDocumentWindowName, wdcGetActiveDocumentName, wdcGetDocumentWindowCount

Returns:

0 on success.

-504 if document window not found

-9001 if Word is not open.

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

WindowCaption = "MyDocumentName"

RetCode = wdcObj.wdcActivateDocumentWindow(WindowCaption)


wdcApplyStyle

wdcObj.wdcApplyStyle(StyleName)

Purpose:

Applies a Word style to the current selection

StyleName is the name of the Word style to apply to the selected paragraph(s).

This function will normally be used when a document has been created from a template containing the style.

See also wdcFormatParagraph, wdcSetFont, wdcApplyTableStyle

Returns:

0 on success.

-24 if style is not found

-9001 if Word is not open.

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

StyleName = "Heading 2"

RetCode = wdcObj.wdcApplyStyle(StyleName)


wdcApplyTableAutoFormat

wdcObj.wdcApplyTableAutoFormat(TableFormatCode [, ToFirstColumn] [, ToHeadingRows] [, ToLastColumn] [, ToLastRow] [, AutoFit])

Purpose:

Applies a Word built in AutoFormat to the table.

TableFormatCode is the integer representing the Word built in AutoFormat to apply to the table. These integers are WdTableFormat values (see Word documentation for the full set of values). Example values (there are more):

1	wdTableFormatSimple1

4	wdTableFormatClassic1

5	wdTableFormatClassic2

6	wdTableFormatClassic3

7	wdTableFormatClassic4

8	wdTableFormatColorful1

11	wdTableFormatColumns1

16	wdTableFormatGrid1

24	wdTableFormatList1

32	wdTableFormat3DEffects1

36	wdTableFormatElegant

40	wdTableFormatWeb1

ToFirstColumn (optional) indicates whether to apply the style to the first column of the table.

ToHeadingRows (optional) indicates whether to apply the style to the heading rows of the table.

ToLastColumn (optional) indicates whether to apply the style to the last column of the table.

ToLastRow (optional) indicates whether to apply the style to the last row of the table.

AutoFit (optional) indicates that the size of the rows and columns should be automatically adjusted to best fit the data contained within it.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

See also wdcApplyTableStyle, wdcApplyStyle

Returns:

0 on success.

-509 command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

StyleName = "Table Grid"

apply the wdTableFormatClassic1 AutoFormat to the table

RetCode = wdcObj.wdcApplyTableAutoFormat(4)


wdcApplyTableStyle

wdcObj.wdcApplyTableStyle(StyleName)

Purpose:

Applies a Word style to the table in the desired way.

StyleName is the name of the Word style to apply to the selected paragraph(s).

ToFirstColumn (optional) indicates whether to apply the style to the first column of the table.

ToHeadingRows (optional) indicates whether to apply the style to the heading rows of the table.

ToLastColumn (optional) indicates whether to apply the style to the last column of the table.

ToLastRow (optional) indicates whether to apply the style to the last row of the table.

This function will normally be used when a document has been created from a template containing the style.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

See also wdcApplyTableAutoFormat, wdcApplyStyle

Returns:

0 on success.

-509 command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

StyleName = "Table Grid"

apply the style to all but the first column of the table

RetCode = wdcObj.wdcApplyTableStyle(StyleName, False)


wdcBookmarkExists

wdcObj.wdcBookmarkExists(BookmarkName)

Purpose:

Determines whether a document contains a named Word bookmark. Returns a value of True (-1) if the bookmark is found, or False (0) if it is not. In both cases the ReturnCode property is set to 0 so it is this that should be tested to determine whether an error has occurred.

Suppose we have this code:

x = wdcObj.wdcBookmarkExists(BookmarkName)

If the bookmark is found values would be set as follows:

x = -1 (True)

wdcObj.ReturnCode = 0 (the function completed successfully)

wdcObj.ResultValue = -1 (True)

wdcObj.ErrorText = ""

If the bookmark is not found values would be set as follows:

x = 0 (False)

wdcObj.ReturnCode = 0 (the function completed successfully)

wdcObj.ResultValue = 0 (False)

wdcObj.ErrorText = ""

If the command is unavailable values might be set as follows:

x = -4248

wdcObj.ReturnCode = -4248

wdcObj.ResultValue = ""

wdcObj.ErrorText = "This command is not available because no document is

 open."

Word Version Note: in Word versions 97 or later this function will successfully find bookmarks in headers and footers. This is not the case for Word versions 95 and earlier (this was not possible in Word).

See also wdcGetBookmarkNames, wdcReplaceBookmarkWithText.

Returns:

0 (False) if the bookmark is not found.

-1 (True) if the bookmark is found.

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

Example:

BookmarkName = "book1"

If wdcObj.wdcBookmarkExists(BookmarkName) = True Then ….


wdcBuildDocumentFromTemplate

wdcObj.wdcBuildDocumentFromTemplate(TemplatePath [, DataFilePath] [, DataAsDelimitedString] [, Delimiter] [, AutoPrint] [,IgnoreMissingBookmarks])

Purpose:

This powerful function creates a new document from a Word template containing bookmarks into which data is inserted. Can be used for Form Letters or for general reporting.

The data can be supplied to the function in one of two ways: it can be taken from a pre-prepared text file or it can be supplied in a single delimited string. That is, one of DataFilePath and DataAsDelimitedString must be supplied, but not both. In both cases data is supplied as pairs of bookmark names and data values separated by a Delimiter character. The function creates a new document from the specified template, searches for the supplied bookmark names and replaces them with the supplied data values.

TemplatePath is the file path of the Word template to be used to create the new document.

DataFilePath (optional) is the path of the text file containing the bookmark names and the data to be inserted. Suppose the template contains bookmarks named "Name", "Company", "Job" then the text file should contain records looking something like this:

Name/Mr. J. Johnson

Company/Acme Insurance Inc.

Job/Director

Here the bookmarks and data values are separated by the default Delimiter character.

DataAsDelimitedString (optional) is an alternative way of supplying the same data as may be found in a DataFilePath text file. Here all the bookmarks and values are concatenated together into a string:

"Name/Mr. J. Johnson/Company/Acme Insurance Inc./Job/Director"

The sequence of bookmarks is not significant. They need not appear in the same order as in the Word template.

The Delimiter (optional) parameter provides the delimiter character to be used to separate the bookmarks and data values in either the text file records or delimited string. This must be a single character. If omitted a value of "/" is assumed.

The AutoPrint (optional) parameter allows you to automatically print the newly created document to the default printer. It has values as follows:

0	do not print (default)

1	print the new document and leave it open

2	print the new document and close it (without saving)

IgnoreMissingBookmarks (optional, True/False, default False) indicates whether or not to generate an error if a specified bookmark is nor found in the document. If IgnoreMissingBookmarks is False and a bookmark is not found then an error will be generated, if True then that bookmark/data pair will be ignored. This option allows the same data source to be easily used across multiple templates even if these contain different sets of bookmarks.

 For more information on this function see Word Templates and Data Sources.

See also wdcReplaceBookmarkWithText and wdcBuildDocumentFromTemplateRTF.

Returns:

0 on success

-41 if TemplatePath is not found

-9001 if Word is not open

-9004 if parameters invalid.

-9007 if DataFilePath is specified but not found

-9008 if a bookmark name in the text file or delimited string containing the data is not found in the Word template

-9009 if format errors are found in the text file or delimited string containing the data

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Examples:

TemplatePath = App.Path & "\FORMLETTER.DOT"

using the text file method to supply the data

DataFilePath = App.Path & "\ MYDATA.TXT"

RetCode = wdcObj.wdcBuildDocumentFromTemplate(TemplatePath, _

 DataFilePath)

using the delimited string method to supply the data

DataAsDelimitedString = "Name/Mr. J. Johnson/Company/Acme Inc."

RetCode = wdcObj.wdcBuildDocumentFromTemplate(TemplatePath, , _

DataAsDelimitedString)


wdcBuildDocumentFromTemplateRTF

wdcObj.wdcBuildDocumentFromTemplateRTF(TemplatePath [, DataFilePath] [, DataAsDelimitedString] [, Delimiter] [, AutoPrint] [,IgnoreMissingBookmarks])

Purpose:

This powerful function creates a new document from a Word template containing bookmarks into which Rich Text Format data is inserted. Can be used for Form Letters or for general reporting.

This function works in exactly the same way as wdcBuildDocumentFromTemplate except that all data values are expected to be supplied (whether via text file or data string) as Rich Text Format strings rather than plain text.

See also wdcReplaceBookmarkWithText and wdcBuildDocumentFromTemplate.


wdcClearSelection

wdcObj.wdcClearSelection

Purpose:

Clears the current selection. If no text is selected deletes the character to the right of the insertion point.

Returns:

0 on success

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcClearSelection


wdcClose

wdcObj.wdcClose

Purpose:

Closes the Word application. Will prompt the user to save changes to documents if necessary.

Word Version Note: In Word 97 or later this will always close the current occurrence of Word. With Word 95 and earlier, however, this function will not close Word if multiple Word instances are running. Instead the function will return code 9002.

See also wdcCloseAllDocuments

Returns:

0 on success.

-9001 if Word is not found.

-9002 if multiple occurrences of Word are found (Word 95 and earlier).

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcClose


wdcCloseAllDocuments

wdcObj.wdcCloseAllDocuments([PromptForSave])

Purpose:

Closes all open Word documents, optionally prompting the user to save.

 PromptForSave (optional) indicates whether the user should be prompted before closing if any of the documents are dirty (have unsaved changes). If this is set to False the documents will be closed without saving. Valid values are:

False	do not prompt (default)

True	prompt if dirty

See also wdcClose

Returns:

0 on success

-91 or -5003 if command unavailable (i.e. no document is open)

-102 if command fails (for example if cancel selected when prompted to save)

-504 if document does not exist

-9001 if Word is not open

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

PromptForSave = True

both of the following are valid

closes documents without prompting, changes are not saved

RetCode = wdcObj.wdcCloseAllDocuments

closes documents with prompting

RetCode = wdcObj.wdcCloseAllDocuments(, PromptForSave)


wdcCloseDocument

wdcObj.wdcCloseDocument([DocumentName] [, PromptForSave])

Purpose:

Closes an open Word document, optionally prompting the user to save.

DocumentName (optional) is the name of the document to close. A blank value ("" or not supplied) means that the currently active document will be closed. If the document is open in Word but is not the currently active document then it will be activated before closing. If this parameter contains a name that is not the same as that of a currently open document then an error is returned. Note that DocumentName must be the name of the document exactly as it appears in the Word caption bar or the window list  so while you might open a document with a parameter like "c:\mydocs\doc1.doc", you would have to close it with a parameter like "doc1.doc", or even "doc1.doc (Read-Only)" if you opened it as readonly. If there is no open document window whose name matches exactly the parameter you specify then an error 504 will be returned.

PromptForSave (optional) indicates whether the user should be prompted before closing if the document is dirty (has unsaved changes). If this is set to False the document will be closed without saving. Valid values are:

False	do not prompt (default)

True	prompt if dirty

Returns:

-91 or -5003 if command unavailable (i.e. no document is open)

-102 if command fails (for example if cancel selected when prompted to save)

-504 if document does not exist

-9001 if Word is not open

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

DocumentName = "test.doc"

PromptForSave = True

all of the following are valid

closes active document without prompting, changes are not saved

RetCode = wdcObj.wdcCloseDocument

 close active document with prompting

RetCode = wdcObj.wdcCloseDocument(, True)

closes named document without prompting, changes are not saved

RetCode = wdcObj.wdcCloseDocument(DocumentName)

closes named document with prompting

RetCode = wdcObj.wdcCloseDocument(DocumentName, PromptForSave)


wdcConvertTextToTable

wdcObj.wdcConvertTextToTable([Delimiter])

Converts a selected block of text into a Word table.

Word Version Note: this function is only supported for Word 97 and later versions. With other versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Delimiter is the character used in the text to separate data to be put into different cells.

See also wdcInsertTable, wdcTextFileToTable

Returns:

0 on success

-509 command unavailable

-9001 if Word is not open

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

the example converts a comma-delimited selection to a table

RetCode = wdcObj.wdcConvertTextToTable(",")


wdcCopy

wdcObj.wdcCopy

Purpose:

Copies the currently selected text to the clipboard. Same as Edit…Copy in Word.

Returns:

0 on success.

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

See also wdcCut, wdcPaste.

Example:

RetCode = wdcObj.wdcCopy


wdcCut

wdcObj.wdcCut

Purpose:

Cuts the currently selected text to the clipboard. Same as Edit…Cut in Word.

Returns:

0 on success.

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

See also wdcCopy, wdcPaste, wdcClearSelection

Example:

RetCode = wdcObj.wdcCut


wdcFormatParagraph

wdcObj.wdcFormatParagraph([Alignment], [LeftIndentPoints], [RightIndentPoints], [SpaceBeforePoints], [SpaceAfterPoints], [KeepWithNext], [KeepTogether], [WidowOrphanControl])

Purpose:

Applys various paragraph formatting properties to the currently selected text.

All parameters are optional. Omitting a parameter or supplying a value of -1 (numeric parameters) or "" (string parameters) will cause it to remain unchanged.

Alignment (optional, default -1) specifies the paragraph alignment. Valid values are:

-1	leave unchanged

0	align left

1	align centred

2	align right

3	align justified

LeftIndentPoints (optional, default -1) specifies the left indentation of the paragraph in points. A value of -1 means leave unchanged.

RightIndentPoints (optional, default -1) specifies the right indentation of the paragraph in points. A value of -1 means leave unchanged.

SpaceBeforePoints (optional, default -1) specifies the gap to be inserted before each paragraph in points. A value of -1 means leave unchanged.

SpaceAfterPoints (optional, default -1) specifies the gap to be inserted after each paragraph in points. A value of -1 means leave unchanged.

KeepWithNext (optional, default -1) specifies whether or not the paragraph is to be forced to remain on the same page as the following paragraph. Valid values are:

-1	leave unchanged

0	do not keep with next

1	keep with next

KeepTogether (optional, default -1) specifies whether or not the selected paragraphs are to be forced to remain together on the same page. Valid values are:

-1	leave unchanged

0	do not keep together

1	keep together

WidowOrphanControl (optional, default -1) specifies whether or not widow and orphan lines (single lines before or after a page break) are to be controlled. Valid values are:

-1	leave unchanged

0	do not control widow and orphan lines

1	control widow and orphan lines

See also wdcApplyStyle, wdcSetFont.

Returns:

0 on success.

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open

-9004 if parameters invalid

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Examples:

'this example sets centre alignment

RetCode = wdcObj.wdcFormatParagraph(1)

'this example sets left indent to 5 points and forces 'Keep With Next'

RetCode = wdcObj.wdcFormatParagraph(, 5, , , , 1)


wdcFreeze

wdcObj.wdcFreeze

Purpose:

Freezes the Word window so that drawing is disabled while subsequent Word operations are carried out. This speeds execution greatly if complex documents are being built and provides a smoother interface.

Important: A call to this function should always be followed when operations are complete (and in error conditions) by a call to wdcUnFreeze. This is very important or you may leave your users with frozen versions of windows which they cannot unfreeze except by closing.

See also wdcUnFreeze

Returns:

0 on success

-9001 if Word is not open

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcFreeze


wdcGetActiveDocumentName

wdcObj.wdcGetActiveDocumentName

Purpose:

Returns the caption of the window containing the active document. Useful when more than one document may be open and switching between document windows is desired.

See also wdcActivateDocumentWindow, wdcGetDocumentWindowName, wdcGetDocumentWindowCount

Returns:

A string containing the name, or "" if an error occurs.

ReturnCodes (obtainable from wdcObj.ReturnCode):

0 on success.

-509 or -4248 or -5003 if command unavailable (no document window active).

-9001 if Word is not open.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

ResultValue = wdcObj.wdcGetActiveDocumentName


wdcGetBookmarkNames

wdcObj.wdcGetBookmarkNames([Delimiter])

Purpose:

Returns the names of all the bookmarks in the active document as one delimited text string.

Delimiter (optional, default "/") specifies the character to insert between each bookmark name in the result string.

Word Version Note: in Word versions 97 or later this function will successfully find bookmarks in headers and footers. This is not the case for Word versions 95 and earlier (this was not possible in Word).

See also wdcBookmarkExists, wdcReplaceBookmarkWithText.

Returns:

A concatenated string containing the bookmark names separated by the delimiter, or "" if an error occurs or no bookmarks are found.

ReturnCodes (obtainable from wdcObj.ReturnCode):

0 on success.

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Examples:

will return a string of the form

    "book1/book2/book3/book4/book5"

ResultValue = wdcObj.wdcGetBookmarkNames

will return a string of the form

    "book1~book2~book3~book4~book5"

ResultValue = wdcObj.wdcGetBookmarkNames("~")


wdcGetDocumentProperty

wdcObj.wdcGetDocumentProperty(PropertyType)

Purpose:

Returns a property of the active document.

Word Version Note: this function will only work successfully with Word 97 or later. With other versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

The PropertyType parameter indicates which built-in property will be returned. All property values are returned as text strings. PropertyType has allowable text values (case insensitive) as follows:

Title

Subject

Author

Keywords

Comments

Template

Last author

Revision Number

Last print date

Creation Date

Last save time

Total editing time

Number of pages

Number of words

Number of characters

Security

Category

Format

Manager

Company

Number of bytes

Number of lines

Number of paragraphs

Hyperlink base

Number of characters (with spaces)

See also wdcSetDocumentProperty. Note that many properties are read-only.

Returns:

A string containing the property value, or "" if an error occurs.

ReturnCodes (obtainable from wdcObj.ReturnCode):

0 on success.

-578 unknown document property

-4248 command not available because no document is open

-9001 if Word is not open.

-9005 unsupported Word version (pre Word 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The example returns the number of words in the active document (as a text string).

ResultValue = wdcObj.wdcGetDocumentProperty("Number of words")


wdcGetDocumentWindowCount

wdcObj.wdcGetDocumentWindowCount()

Purpose:

Returns the number of document windows (as seen on the Window menu).

See also wdcGetDocumentWindowName, wdcGetActiveDocumentName, wdcActivateDocumentWindow

Returns:

The integer value containing the number of document windows.

ReturnCodes (obtainable from wdcObj.ReturnCode):

0 on success.

-509 command unavailable

-9001 if Word is not open.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

ResultValue = wdcObj.wdcGetDocumentWindowCount()


wdcGetDocumentWindowName

wdcObj.wdcGetDocumentWindowName(WindowNumber)

Purpose:

Returns the caption of a document window (as seen on the Window menu).

WindowNumber indicates which document on the list of Windows is te subject of the function. A value of 2, for example, would indicate the second window on the list.

See also wdcGetDocumentWindowCount, wdcGetActiveDocumentName, wdcActivateDocumentWindow

The window caption of the specified document, or  if an error occurs.

ReturnCodes (obtainable from wdcObj.ReturnCode):

0 on success.

-509 command unavailable

-9001 if Word is not open.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

retrieve the name of the second document on the Window list

ResultValue = wdcObj.wdcGetDocumentWindowName(2)


wdcGetSelectedText

wdcObj.wdcGetSelectedText

Purpose:

Returns the text currently selected in the active document.

Returns:

A string containing the selected text, or "" if an error occurs.

ReturnCodes (obtainable from wdcObj.ReturnCode):

0 on success.

-513 string too long

-9001 if Word is not open.

-509 or -4248 or -5003 if command unavailable (no document is open)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

ResultValue = wdcObj.wdcGetSelectedText


wdcGetWordwindowHandle

wdcObj.wdcGetWordWindowHandle

Purpose:

Determines whether or not Word is running. If a single occurrence of Word is running, returns the handle of the top-level Word window.

It is NOT necessary to use this function before launching (or obtaining a reference to) Word with wdcLaunch. The function is provided mainly to obtain a Windows handle for the Word window itself which is required to do things like bring it to the top, hide it, etc. (normally done using the Windows API).

Word Version Note: Word 2000 introduced a new interface in which all open documents are implemented as separate top-level windows, independently appearing in the Task Bar. If this is the case this function will return the handle of the first top level Word window found. If multiple occurrences of Word are found and the version is 97 or earlier then the function will simply return code -9002.

Returns:

The handle of the Word window or "" if Word is not running or an error occurs.

ReturnCodes (obtainable from wdcObj.ReturnCode):

0 on success

-9001 if Word is not found.

-9002 if multiple occurrences of Word are found (Word 97 or earlier).

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

ResultValue = wdcObj.wdcGetWordWindowHandle


wdcGoto

wdcObj.wdcGoTo(Destination)

Purpose:

Moves to a position in a Word document. Many keywords are available to move in various ways. If the supplied parameter is not one of the recognised keywords then it is assumed to be a Word bookmark name.

Destination defines where the selection/cursor is to move to. Valid keywords are as follows:

"Start"

"End"

"CharLeft"

"CharRight"

"WordLeft"

"WordRight"

"LineStart"

"LineEnd"

"LineUp"

"LineDown"

"ParagraphDown"

"ParagraphUp"

"WordSelect"

"SentenceSelect"

"ParagraphSelect"

"DocumentSelect"

"TableSelect"

"ColumnSelect"

"RowSelect"

"NextCell"

"PrevCell"

Word Version Note: in Word versions 97 or later this function will successfully find and go to bookmarks in headers and footers. If the bookmark is in a header or footer and the header/footer pane is not open then the function will open it. For Word versions 95 and earlier this function will not find a bookmark in a header or footer (this was not possible in Word) and will instead return a not found error.

Returns:

0 on success

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open

-9004 if parameters invalid

-9006 or -5678 if bookmark not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

All of the following are valid

RetCode = wdcObj.wdcGoto("mybookmark")

RetCode = wdcObj.wdcGoto("start")

RetCode = wdcObj.wdcGoto("NextCell")


wdcInsertBookmark

wdcObj.wdcInsertBookmark(BookmarkName [, Location])

Inserts a bookmark into the active document at the specified position.

BookmarkName is the name of the bookmark to be inserted.

Location (optional) indicates where the bookmark should be placed. Valid special values are Start and End representing the start and end of the document. A blank value represents the current position, and if any other string is supplied then the function will search for the first occurrence of that string and place the bookmark there.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Returns:

0 if successful.

-78 if file not found

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported Word version (pre-97).

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcInsertBookmark(Book1, Start)


wdcInsertContentAtBookmark

wdcObj.wdcInsertContentAtBookmark(BookmarkName, ContentType, Content)

Purpose:

Inserts content of the specified type at a bookmark position.

BookmarkName is the name of the bookmark at which the content is to be inserted.

ContentType specifies what type of data is to be inserted. Valid values are

Text

File

Picture

Content determines the actual data to be inserted. If ContentType is Text then this is a text string. If ContentType is File or Picture then this is a file path.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Returns:

0 if successful.

-78 if file not found

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported Word version (pre-97).

-9006 bookmark not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcInsertContentAtBookmark(Book1, File,

 C:\myfile.doc)


wdcInsertFile

wdcObj.wdcInsertFile(FileName)

Purpose:

Inserts the contents of a file into the active document at the current position. Word will perform file conversions where appropriate.

FileName is the full path of the file whose contents are to be inserted.

Returns:

0 if successful.

-78 if file not found

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

Filename = "d:\docs\x.txt"

RetCode = wdcObj.wdcInsertFile(Filename)


wdcInsertPageBreak

wdcObj.wdcInsertPageBreak

Purpose:

Inserts a page break at the current position.

Returns:

0 if successful.

-9001 if Word is not open.

-509 or -4248 or -5003 if command unavailable

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcInsertPageBreak


wdcInsertPicture

wdcObj.wdcInsertPicture(FileName)

Purpose:

Inserts a picture graphic from a file into the active document at the current position. Word will perform file conversions where appropriate.

FileName is the full path of the file which contains the graphic to be inserted.

Returns:

0 if successful.

-78 if file not found

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

Filename = "d:\docs\ \mypic.jpg"

RetCode = wdcObj.wdcInsertPicture(Filename)


wdcInsertSectionBreak

wdcObj.wdcInsertSectionBreak([BreakType])

Purpose:

Inserts a section, column or line break at the current position.

The BreakType (optional) parameter indicates what type of break is required. Valid values are:

1	column break

2	next page section break (default)

3	continuous section break

4	even page section break

5	odd page section break

6	line break (newline character)

Returns:

0 if successful.

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The example inserts a continuous (no new page forced) section break.

RetCode = wdcObj.wdcInsertSectionBreak(3)


wdcInsertTable

wdcObj.wdcInsertTable(NumRows, NumCols [, ColWidth] [, InsideLineStyleCode] [, InsideLineWidthCode] [, OutsideLineStyleCode] [, OutsideLineWidthCode])

Purpose:

Inserts a Word table into the active document at the current position.

NumRows is the number of rows to create in the table.

NumCols is the number of columns to create in the table.

ColWidth (optional) is the desired width of each column in points.

InsideLineStyleCode and OutsideLineStyleCode (both optional) are the integer values which represent the line styles to use for the inside and outside lines of the table. These equate to WdLineStyle constants (see the Word help for full details).

Example values (there are more):

0	wdLineStyleNone

1	wdLineStyleSingle (default)

2	wdLineStyleDot

3	wdLineStyleDashSmallGap

4	wdLineStyleDashLargeGap

5	wdLineStyleDashDot

7	wdLineStyleDouble

8	wdLineStyleTriple

21	wdLineStyleEmboss3D

InsideLineWidth and OutsideLineWidth (both optional) are the integer values which represent the line widths to use for the inside and outside lines of the table. These equate to WdLineWidth constants (see the Word help for full details).

Example values (there are more):

2	wdLineWidth025pt

4	wdLineWidth050pt

6	wdLineWidth075pt

8	wdLineWidth100pt

12	wdLineWidth150pt

24	wdLineWidth300pt

48	wdLineWidth600pt

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Returns:

0 if successful.

-509 command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

inserts a table with 3 rows and 4 columns

RetCode = wdcObj.wdcInsertTable(3,4)


wdcInsertText

wdcObj.wdcInsertText(InsertString)

Purpose:

Inserts a text string into the active document at the current position.

If carriage returns are required the special character 13 may be included in the text string.

See also wdcReplaceBookmarkWithText.

Returns:

0 if successful.

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

InsertString = "Hello World." & Chr$(13)

RetCode = wdcObj.wdcInsertText(InsertString)


wdcLaunch

wdcObj.wdcLaunch([WindowState])

Purpose:

Launches Word or obtains a reference to a running occurrence for use in subsequent WordController method calls. Word is launched in, or if already running converted to, a show state as defined by the WindowState parameter.

This function or wdcLaunchNewInstance must be called prior to making use of other WordController functions such as wdcMailMergeDocument or wdcBuildDocumentFromTemplate.

See also wdcLaunchNewInstance, wdcSetWindowViewType.

Valid values for WindowState (optional) are as follows:

0	Hidden

1	Normal

2	Minimized

3	Maximized (default)

Returns:

0 on success.

-429 Ole Automation Server cannot create object

ReturnCodes less than zero are failure codes.

Example:

The following are both valid:

default window state (Maximized)

RetCode = wdcObj.wdcLaunch

WindowState = 1 hidden

RetCode = wdcObj.wdcLaunch(WindowState)


wdcLaunchNewInstance

wdcObj.wdcLaunchNewInstance([WindowState])

Purpose:

Launches a new instance of Word for use in subsequent WordController method calls. Word is launched in a show state as defined by the WindowState parameter.

Word Version Note: this function will only work successfully with Word 97 or later. Earlier versions are only creatable through OLE automation as single instance applications. With these versions of Word, or if Word is not correctly installed, or if Word cannot be loaded for any other reason, this function returns a negative ReturnCode (usually -429 "Ole Automation Server cannot create object") which can be trapped by the calling application and handled appropriately (perhaps with a subsequent call to wdcLaunch).

This function or wdcLaunch must be called prior to making use of other WordController functions such as wdcMailMergeDocument or wdcBuildDocumentFromTemplate.

See also wdcLaunch

Valid values for WindowState (optional) are as follows:

0	Hidden

1	Normal

2	Minimized

3	Maximized (default)

Returns:

0 on success.

-429 Ole Automation Server cannot create object

ReturnCodes less than zero are failure codes.

Example:

The following are both valid:

default window state (Maximized)

RetCode = wdcObj.wdcLaunchNewInstance

WindowState = 1 hidden

RetCode = wdcObj.wdcLaunchNewInstance (WindowState)


wdcMailMergeDocument

wdcObj.wdcMailMergeDocument(TemplatePath, DataFilePath [, AutoPrint])

Purpose:

Performs a Word MailMerge to create a merge document.

TemplatePath is the file path of the Word template to be used in the merge operation. DataFilePath is the path of the text file containing the merge data. For more information about these files and their formats see Word Templates and Data Sources.

The AutoPrint (optional) parameter allows you to automatically print the newly created merge document to the default printer. It has values as follows:

0	do not print (default)

1	print the new document and leave it open

2	print the new document and close it (without saving)

See also wdcMailMergeDocWithOptions if you wish to merge only a subset of records or avoid the default suppression of blank lines during the merge.

See also wdcMailMergeLabels, wdcMailMergeLblWithOptions.

Returns:

0 on success

-41 if TemplatePath is not found

-9001 if Word is not open

-9004 if parameters invalid.

-9007 if DataFilePath is not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The following are both valid:

the default does not print (AutoPrint assumed to be 0)

TemplatePath = App.Path & "\MERGELETTER.DOT"

DataFilePath = App.Path & "\MERGEDATA.TXT"

RetCode = wdcObj.wdcMailMergeDocument(TemplatePath, DataFilePath)

Print the document and then close it straightaway

TemplatePath = App.Path & "\MERGELETTER.DOT"

DataFilePath = App.Path & "\MERGEDATA.TXT"

AutoPrint = 2

RetCode = wdcObj.wdcMailMergeDocument(TemplatePath, _

DataFilePath, Autoprint)


wdcMailMergeDocWithOptions

wdcObj.wdcMailMergeDocWithOptions (TemplatePath, DataFilePath [, MergeSubset] [, FromRecord] [, ToRecord] [, PrintBlankLines] [, AutoPrint])

Purpose:

Performs a Word MailMerge to create a merge document - as for wdcMailMergeDocument but with additional options to allow subset record selection and non-suppression of blank lines.

TemplatePath is the file path of the Word template to be used in the merge operation. DataFilePath is the path of the text file containing the merge data. For more information about these files and their formats see Word Templates and Data Sources.

A MergeSubset (optional) value of True indicates whether a subset of the records in DataFilePath is to be selected for the merge. If this parameter is set to False (the default) then all records will be selected. If MergeSubset = True then the records in the range indicated by FromRecord and ToRecord are used  in the merge.

The PrintBlankLines (optional) parameter allows you to choose whether or not to suppress blank lines during the merge operation, e.g. for addresses. Valid values are:

False	suppress blank lines (default)

True	print blank lines

The AutoPrint (optional) parameter allows you to automatically print the newly created merge document to the default printer. It has values as follows:

0	do not print (default)

1	print the new document and leave it open

2	print the new document and close it (without saving)

See also wdcMailMergeDocument, wdcMailMergeLabels, wdcMailMergeLblWithOptions.

Returns:

0 on success

-41 if TemplatePath is not found

-9001 if Word is not open

-9004 if parameters invalid.

-9007 if DataFilePath is not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The example performs a merge using records 100-199 from file "c:\mydir\mydata.txt", printing blank lines where found. The result is not printed (default value for AutoPrint is 0).

TemplatePath = App.Path & "\MERGELETTER.DOT"

DataFilePath = "c:\mydir\mydata.txt"

MergeSubset = True

FromRecord = 100

ToRecord=199

PrintBlankLines = True

RetCode = wdcObj.wdcMailMergeDocWithOptions(TemplatePath, _

DataFilePath, MergeSubset, _

FromRecord, ToRecord, PrintBlankLines)


wdcMailMergeLabels

wdcObj.wdcMailMergeLabels(TemplatePath, DataFilePath [, AutoPrint])

Purpose:

Performs a Word MailMerge to create a merge document containing a sheet or sheets of labels.

TemplatePath is the file path of the Word template to be used in the merge operation. DataFilePath is the path of the text file containing the merge data. For more information about these files and their formats see Word Templates and Data Sources.

The AutoPrint (optional) parameter allows you to automatically print the newly created merge document to the default printer. It has values as follows:

0	do not print (default)

1	print the new document and leave it open

2	print the new document and close it (without saving)

Returns:

0 on success

-41 if TemplatePath is not found

-9001 if Word is not open

-9004 if parameters invalid.

-9007 if DataFilePath is not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

See also wdcMailMergeLblWithOptions if you wish to merge only a subset of records or avoid the default suppression of blank lines during the merge.

See also wdcMailMergeDocument, wdcMailMergeDocWithOptions.

Example:

The following are both valid:

the default does not print (AutoPrint assumed to be 0)

TemplatePath = App.Path & "\MERGELABELS.DOT"

DataFilePath = App.Path & "\MERGEDATA.TXT"

RetCode = wdcObj.wdcMailMergeLabels(TemplatePath, DataFilePath)

Print the document and leave it open in Word

TemplatePath = App.Path & "\MERGELABELS.DOT"

DataFilePath = App.Path & "\MERGEDATA.TXT"

AutoPrint = 1

RetCode = wdcObj.wdcMailMergeLabels(TemplatePath, DataFilePath,

 Autoprint)


wdcMailMergeLblWithOptions

wdcObj.wdcMailMergeLblWithOptions(TemplatePath, DataFilePath [, MergeSubset] [, FromRecord] [, ToRecord] [, PrintBlankLines] [, AutoPrint])

Purpose:

Performs a Word MailMerge to create a merge document containing a sheet or sheets of labels - as for wdcMailMergeLabels but with additional options to allow subset record selection and non-suppression of blank lines.

TemplatePath is the file path of the Word template to be used in the merge operation. DataFilePath is the path of the text file containing the merge data. For more information about these files and their formats see Word Templates and Data Sources.

A MergeSubset (optional) value of True indicates whether a subset of the records in DataFilePath is to be selected for the merge. If this parameter is set to False (the default) then all records will be selected. If MergeSubset = True then the records in the range indicated by FromRecord and ToRecord are used  in the merge.

The PrintBlankLines (optional) parameter allows you to choose whether or not to suppress blank lines during the merge operation, e.g. for addresses. Valid values are:

False	suppress blank lines (default)

True	print blank lines

The AutoPrint (optional) parameter allows you to automatically print the newly created merge document to the default printer. It has values as follows:

0	do not print (default)

1	print the new document and leave it open

2	print the new document and close it (without saving)

Returns:

0 on success

-41 if TemplatePath is not found

-9001 if Word is not open

-9004 if parameters invalid.

-9007 if DataFilePath is not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

See also wdcMailMergeLabels, wdcMailMergeDocument, wdcMailMergeDocWithOptions.

Example:

The example performs a merge using all records from file "c:\mydir\mydata.txt", printing blank lines where found.

RetCode = wdcObj.wdcMailMergeLblWithOptions("c:\mydir\mylabels.dot" _

, "c:\mydir\mydata.txt", False, 0, 0, True, 0)


wdcNewDocument

wdcObj.wdcNewDocument([TemplateName])

Purpose:

Creates a new Word document, optionally from a pre-existing template.

TemplateName optionally specifies the file path of the template to use to create the document.

Returns:

0 on success

-78 if template was not found

-9001 if Word is not open

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The following are both valid:

the default does not use a supplied template to create the document

RetCode = wdcObj.wdcNewDocument

TemplatePath = App.Path & "\FORMLETTER.DOT"

RetCode = wdcObj.wdcNewDocument(TemplatePath)


wdcOpenDocument

wdcObj.wdcOpenDocument(DocumentName [, ReadOnly] [, Password])

Purpose:

Opens a Word document.

DocumentName specifies the file path of the document to open.

ReadOnly (optional) specifies whether or not to open the document in read-only mode. Valid values are:

False	normal editing mode (default)

True	read only mode

Password (optional) specifies the password required to open the document if there is one. If a password is required and one is not supplied to the function then Word will prompt the user to enter one at runtime.

Returns:

0 on success

-78 if the document was not found

-312 or -1312 if a supplied password is incorrect

-9001 if Word is not open

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

DocumentName = App.Path & "\MYLETTER.DOC"

ReadOnly = True

Password = "xxx"

The following are all valid:

RetCode = wdcObj.wdcOpenDocument(DocumentName)

RetCode = wdcObj.wdcOpenDocument(DocumentName, , Password)

RetCode = wdcObj.wdcOpenDocument(DocumentName, ReadOnly)

RetCode = wdcObj.wdcOpenDocument(DocumentName, 0, "xxx")


wdcPaste

wdcObj.wdcPaste

Purpose:

Pastes the currently selected text from the clipboard into the active document at the current location. Same as Edit…Paste in Word.

Returns:

0 on success.

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not found.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

See also wdcCopy, wdcCut

Example:

RetCode = wdcObj.wdcPaste


wdcPrintDocument

wdcObj.wdcPrintDocument([NumberOfCopies])

Purpose:

Prints the active document to the default printer.

NumberOfCopies (optional, default value 1) signifies how many copies to print.

Returns:

0 on success

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Examples:

RetCode = wdcObj.wdcPrintDocument defaults to 1 copy

RetCode = wdcObj.wdcPrintDocument(2) 2 copies


wdcProtectDocument

wdcObj.wdcProtectDocument(ProtectionType [, Password])

Purpose:

Protects the document so that all or part of it cannot be edited.

Word Version Note: this function will only work successfully with Word 97 or later. With other versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

There are three types of protection: Allow editing in form fields only; Allow editing for comments only; Allow revisions only. The ProtectionType parameter indicates which is required. Valid values are:

0	protect for revisions

1	protect for comments

2	protect for forms

If you choose a ProtectionType of 2 (protect for forms) then you must first indicate which document sections you wish to protect. This is done with the wdcSetSectionProtection function.

If Password (optional) is non-blank then the user of the document must enter this string if they later wish to unprotect the document (with Tools…Unprotect Document).

See also wdcUnprotectDocument, wdcSetSectionProtection .

Returns:

0 on success

-4248 command not available because no document is open

-4605 document is already protected

-9001 if word not launched

-9004 if parameters invalid

-9005 unsupported word version (pre Word 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The example protects the document for forms but without a password, so the user can unprotect if they wish.

RetCode = wdcObj.wdcProtectDocument(2)


wdcReplaceAll

wdcObj.wdcReplaceAll(StringToReplace, ReplacementString [, HeaderAndFooter])

Purpose:

Replaces all occurrences of a string in an open document with another string.

StringToReplace specifies the string to search for in the document. ReplacementString specifies the string to replace it with.

The HeaderAndFooter (optional) parameter specifies whether or not the replace operation should be carried out in the document header and footer as well as the main body of the document.

False	do not replace in the header and footer (default)

True	do replace in the header and footer

Note: If you do not specifically wish to replace occurrences in the header or footer, a value of False for this parameter is recommended (rather than just always choosing True as a default). The reason for this is that when Word is replacing in the header and footer it puts up the floating Header/Footer toolbar, and this cannot be suppressed. If you choose False for this parameter then the toolbar will not pop up, which is normally preferable. If you choose True for this parameter then the toolbar will always pop up, albeit very briefly.

Returns:

0 on success

-5003 or -102 if ReplaceAll is not a valid command (usually because no document is open)

-9001 if Word is not open

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Examples:

The following are both valid:

does not attempt to replace in Header/Footer

RetCode = wdcObj.wdcReplaceAll("Default Title", "MyName")

does attempt to replace in Header/Footer

RetCode = wdcObj.wdcReplaceAll("Default Title", "MyName", True)


wdcReplaceBookmarkWithText

wdcObj.wdcReplaceBookmarkWithText(BookmarkName, InsertString [, RemoveAnySplit])

Purpose:

Replaces a bookmark in an open document with a string of text.

BookmarkName specifies the bookmark to search for in the document. InsertString specifies the string to replace it with.

The RemoveAnySplit (optional) parameter is only significant for Word 97 or later versions. It specifies whether or not the function should close any additional pane it needs to open to do the replace operation. This is necessary because if the bookmark is not in the main document but instead, for example, in a header or footer then Word will open a separate window pane to display it. This will not be closed after the operation is complete unless RemoveAnySplit is explicity set. Valid values are:

False	don't remove split

True	remove split (default)

If RemoveAnySplit is set to True and no split is present then the function ignores this parameter, so this is the normal recommended value.

Word Version Note: in Word versions 97 or later this function will successfully find and replace bookmarks in headers and footers. If the bookmark is in a header or footer and the header/footer pane is not open then the function will open it. For Word versions 95 and earlier this function will not find a bookmark in a header or footer (this was not possible in those versions of Word) and will instead return an error.

See also wdcBuildDocumentFromTemplate, wdcGoTo, wdcInsertText.

Returns:

0 on success

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open

-9004 if parameters invalid.

-9008 or -5678 if bookmark not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcReplaceBookmarkWithText("bookmark1", "Hello")


wdcRunMacro

wdcObj.wdcRunMacro(MacroName)

Purpose:

Runs a Word macro.

MacroName is the name of the Word macro to be run. The macro may be contained in any open template. Note that you cannot pass arguments to macros using this method.

See also wdcRunMacroWithParameters

Returns:

0 on success

-537 if MacroName cannot be run (normally because it is not found)

-9001 if Word is not open

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcRunMacro("Macro1")


wdcRunMacroWithParameters

wdcObj.wdcRunMacroWithParameters(MacroName, NumParameters, Param1 [, Param2] [, Param3] [, Param4] [, Param5])

Purpose:

Runs a Word macro.

MacroName is the name of the Word macro to be run. The macro may be contained in any open template.

NumParameters is the number of parameters expected by the macro.

Param1, Param2, Param3, Param4 and Param5 are the values of the parameters to pass.

Word Version Note: this function will only work successfully with Word 2000 or later as earlier versions did not support this functionality. With other versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

See also wdcRunMacro

Returns:

0 on success

-537 if MacroName cannot be run (normally because it is not found)

-9001 if Word is not open

-9004 if parameters invalid.

-9005 unsupported Word version (pre-2000).

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcRunMacroWithParameters(Macro1, 2, Smith, 45)


wdcSaveDocument

wdcObj.wdcSaveDocument

Purpose:

Saves the active document. If document has not previously been saved displays the SaveAs dialog box.

See also wdcSaveDocumentAs wdcSaveDocumentAsType.

Returns:

0 on success

-102 if the SaveAs dialog box is displayed and the user cancels

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcSaveDocument


wdcSaveDocumentAs

wdcObj.wdcSaveDocumentAs(DocumentName [, Password])

Purpose:

Saves the active document to a specified path/name.

DocumentName is the full path of the file in which the document is to be saved.

Password (optional) is a password with which to protect the document. Note that if the document is already saved with the same name then any password supplied will be ignored. You must save to a different name to apply a password.

See also wdcSaveDocument wdcSaveDocumentAsType.

Returns:

0 on success

-509 or -4248 or -5003 if command unavailable

-1056 if filename is invalid

-9001 if Word is not open

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The following are both valid

RetCode = wdcObj.wdcSaveDocumentAs("c:\temp\temp.doc")

applies a password to the saved document

RetCode = wdcObj.wdcSaveDocumentAs("c:\temp\temp.doc", "mypassword")


wdcSaveDocumentAsType

wdcObj.wdcSaveDocumentAsType(DocumentName, DocumentFormat [, Password])

Purpose:

Saves the active document to a specified path/name as a specified file type.

DocumentName is the full path of the file in which the document is to be saved.

DocumentFormat indicates what type of file you wish to create. Valid values are:

HTM (or HTML)

RTF

DOT (or TEMPLATE)

TXT (or TEXT)

Password (optional) is a password with which to protect the document.

Word Version Note: conversion to HTML format is not supported with Word versions prior to Word 97. An attempt to save to HTML with an earlier version of Word will result in ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

See also wdcSaveDocumentAs wdcSaveDocument.

Returns:

0 on success

-509 or -4248 or -5003 if command unavailable

-1056 if filename is invalid

-5154 you cannot save a template file to a non-template format

-9001 if Word is not open

-9005 this conversion not supported in this Word version

-9004 if parameters invalid.

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcSaveDocumentAsType("c:\\temp.htm", "html")


wdcSelectTable

wdcObj.wdcSelectTable(IndexNumber)

Purpose:

Selects a table in the active document.

IndexNumber identifies the table to be selected. The following rules apply: Suppose IndexNumber=n. If the selection is within a table or includes multiple tables then the nth table encountered will be used. If the selection does not include or is not within any tables then the nth table encountered in the document will be used. If less than n tables are found in the document then an error is generated.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Returns:

0 if successful.

-509 command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

-9010 Command unavailable - Table not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

select the 2nd table

RetCode = wdcObj.wdcSelectTable(2)


wdcSelectTableCell

wdcObj.wdcSelectTableCell(RowNum, ColNum)

Purpose:

Selects an individual cell in a table.

The subject table is identified by the following rules: If the selection is within a table or includes multiple tables then the first table encountered will be used. If the selection does not include or is not within any tables then the first table encountered in the document will be used. If no tables are found in the document then an error is generated.

RowNum identifies the row of the cell to be selected within the table.

ColNum identifies the column of the cell to be selected within the table.

See also wdcGoTo for navigating around tables.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Returns:

0 if successful.

-509 command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

-9010 Command unavailable - Table not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

select the cell corresponding to the 2nd row and the 3rd column.

RetCode = wdcObj.wdcSelectTableCell(2, 3)


wdcSelectTableColumn

wdcObj.wdcSelectTableColumn(ColNum)

Purpose:

Selects a column in a table.

The subject table is identified by the following rules: If the selection is within a table or includes multiple tables then the first table encountered will be used. If the selection does not include or is not within any tables then the first table encountered in the document will be used. If no tables are found in the document then an error is generated.

ColNum identifies the column to be selected within the table.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Returns:

0 if successful.

-509 command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

-9010 Command unavailable - Table not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

select the 2nd column

RetCode = wdcObj.wdcSelectTableColumn(2)


wdcSelectTableRow

wdcObj.wdcSelectTableRow(RowNum)

Purpose:

Selects a row in a table.

The subject table is identified by the following rules: If the selection is within a table or includes multiple tables then the first table encountered will be used. If the selection does not include or is not within any tables then the first table encountered in the document will be used. If no tables are found in the document then an error is generated.

RowNum identifies the row to be selected within the table.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Returns:

0 if successful.

-509 command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

-9010 Command unavailable - Table not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

select the 2nd row

RetCode = wdcObj.wdcSelectTableRow(2)


wdcSetDocumentProperty

wdcObj.wdcSetDocumentProperty(PropertyType, PropertyValue)

Purpose:

Sets a built-in property of the active document.

Word Version Note: this function will only work successfully with Word 97 or later. With other versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

The PropertyType parameter indicates which built-in property will be returned. All property values are returned as text strings. PropertyType has allowable text values (case insensitive) as follows:

Title

Subject

Author

Keywords

Comments

Category

Manager

Company

Hyperlink base

The PropertyValue parameter defines the value to be associated with the property.

See also wdcGetDocumentProperty.

Returns:

0 on success

-578 unknown document property

-4248 command unavailable because no document is active

-9001 if Word not launched

-9004 if parameters invalid

-9005 unsupported word version (pre Word 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The example sets the title property of the active document to "Sales Figures".

RetCode = wdcObj.wdcSetDocumentProperty("Title", "Sales Figures")


wdcSetFont

wdcObj.wdcSetFont([FontName], [FontSize], [ColorIndex As Variant], [Bold], [Italic], [Underline], [Strikethrough], [SmallCaps], [AllCaps], [Superscript], [Subscript], [Shadow], [Hidden])

Purpose:

Applys various font formatting properties to the currently selected text.

All parameters are optional. Omitting a parameter or supplying a value of -1 (numeric parameters) or "" (string parameters) will cause it to remain unchanged.

FontName (optional, default "") specifies the font name of the font to be applied to the paragraph. A value of "" (empty string) means leave the font name unchanged.

FontSize (optional, default -1) specifies the font size in points. A value of -1 means leave unchanged.

ColorIndex (optional, default -1) specifies the font color. This is a variant parameter which accepts numeric values or text color names. Valid values are:

-1 (leaves color unchanged)

0 or "Automatic" or "Auto"

1 or "Black"

2 or "Blue"

3 or "Cyan" or "Turquoise"

4 or "Light Green" or "Bright Green"

5 or "Magenta" or "Pink"

6 or "Red"

7 or "Yellow"

8 or "White"

9 or "Dark Blue"

10 or "Dark Cyan" or "Teal"

11 or "Dark Green" or "Green"

12 or "Dark Magenta" or "Violet"

13 or "Dark Red"

14 or "Dark Yellow"

15 or "Dark Gray" or "Dark Grey"

16 or "Light Gray" or "Light Grey"

Bold (optional, default -1) specifies whether or not to apply bold formatting to the selected text. Valid values are:

-1	leave unchanged

0	not bold

1	bold

Italic (optional, default -1) specifies whether or not to apply italic formatting to the selected text. Valid values are:

-1	leave unchanged

0	not bold

1	bold

Underline (optional, default -1) specifies whether or not to apply underling to the selected text. Valid values are:

-1	leave unchanged

0	no underlining

1	single underlining

2	words only

3	double underlining

4	dotted underlining

Strikethrough (optional, default -1) specifies whether or not to apply strikethrough formatting to the selected text. Valid values are:

-1	leave unchanged

0	not strikethrough

1	strikethrough

Smallcaps (optional, default -1) specifies whether or not to apply small capitals formatting to the selected text. Valid values are:

-1	leave unchanged

0	not smallcaps

1	smallcaps

Allcaps (optional, default -1) specifies whether or not to apply uppercase formatting to the selected text. Valid values are:

-1	leave unchanged

0	not allcaps

1	allcaps

Superscript (optional, default -1) specifies whether or not to apply superscript formatting to the selected text. Valid values are:

-1	leave unchanged

0	not superscript

1	superscript

Subscript (optional, default -1) specifies whether or not to apply subscript formatting to the selected text. Valid values are:

-1	leave unchanged

0	not subscript

1	subscript

Shadow (optional, default -1) specifies whether or not to apply shadow formatting to the selected text. Valid values are:

-1	leave unchanged

0	not shadow

1	shadow

Hidden (optional, default -1) specifies whether or not to apply hidden formatting to the selected text. Valid values are:

-1	leave unchanged

0	not hidden

1	hidden

See also wdcApplyStyle, wdcFormatParagraph.

Returns:

0 on success.

-509 or -4248 or -5003 if command unavailable

-9001 if Word is not open

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Examples:

'this example sets the font to Courier

RetCode = wdcObj.wdcSetFont("Courier")

'this example sets the font size to 14 points and applies bold, uppercase formatting

RetCode = wdcObj. wdcSetFont(, 14, , 1, , , , , 1)


wdcSetSectionProtection

wdcObj.wdcSetSectionProtection([SectionNumber] [, ProtectOn])

Purpose:

Protects a section in the active document so that only text in form fields may be selected/modified. This function should normally be used in conjunction with wdcProtectDocument.

Word Version Note: this function will only work successfully with Word 97 or later. With other versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

There are three types of protection: Allow editing in form fields only ('protected for forms'); Allow editing for comments only; Allow revisions only. This function is relevant only when documents are protected for forms. It allows control over which sections are protected.

The SectionNumber (optional) parameter indicates which section(s) you wish to protect or unprotect. The first section in the document is section 1, the second is section 2, etc. A value of zero (the default) in this parameter is a special value in that it will protect/unprotect those sections covered by the current selection (normally just the single section containing the insertion point).

The ProtectOn (optional) parameter indicates whether you wish to protect or unprotect the section(s). Valid values are:

False	unprotect the section

True	protect the section

If you attempt to protect an already protected section, or unprotect an already unprotected section, this will not cause an error.

To protect various sections of a document you should make one or more calls to this function while the document is unprotected, and then protect it for forms with wdcProtectDocument. The protection will not take effect until after this wdcProtectDocument call.

See also wdcProtectDocument, wdcUnprotectDocument.

Returns:

0 on success

-4248 command unavailable because no document is active

-5887 command unavailable, document already protected

-9001 if Word not launched

-9004 if parameters invalid

-9005 unsupported word version (pre Word 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The example marks section 2 of the active document as protected for forms.

RetCode = wdcObj.wdcSetSectionProtection(2, True)


wdcSetTableColumnWidth

wdcObj.wdcSetTableColumnWidth(ColNum, ColWidth)

Purpose:

Sets the width of a table column.

ColNum identifies the column within the table.

ColWidth is the width in points to be applied. A special ColWidth value of 0 indicates AutoFit  the column is sized automatically to fit the data contained within it.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Returns:

0 if successful.

-509 command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

-9010 Command unavailable - Table not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

set the width of the 2nd row to 50 points

RetCode = wdcObj.wdcSetTableColumnWidth(2, 50)


wdcSetTableRowHeight

wdcObj.wdcSetTableRowHeight(RowNum, RowHeight)

Purpose:

Sets the height of a table row.

RowNum identifies the row within the table.

RowHeight is the height in points to be applied.

Word Version Note: this function is only supported for Word 97 or later. With earlier versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Returns:

0 if successful.

-509 command unavailable

-9001 if Word is not open.

-9004 if parameters invalid.

-9005 unsupported word version (pre 97)

-9010 Command unavailable - Table not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

set the height of the 3rd row to 30 points

RetCode = wdcObj.wdcSetTableRowHeight(3, 30)


wdcSetWindowViewType

wdcObj.wdcSetWindowViewType(ViewType)

Purpose:

Sets the active window view type to the chosen type.

The ViewType parameter indicates which view type is required, and can take the following values:

1 	Normal View

2	Outline View

3 	Print View (called Page Layout in Word versions prior to Word 2000)

4 	Print Preview

5 	Master View

6 	Web View (not available in Word versions prior to Word 97)

Word Version Note: Web View was not available in Word versions prior to Word 97. An attempt to switch to Web View in earlier versions will result in ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

Word Version Note: In Word 95 there were various problems when using OLE Automation with documents in anything other than Normal view. When building a document it is recommended that this be done in Normal view and that you only switch to another desired view after all other processing is finished. Note also that the wdcLaunch function always switches to Normal view as a default.

See also wdcLaunch.

Returns:

0 on success

-5003 or -4248 if command unavailable

-9001 if Word not launched

-9004 if parameters invalid

-9005 view type unavailable in this Word version

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

The example switches to Print Preview mode.

RetCode = wdcObj.wdcSetWindowViewType(3)


wdcSpellCheckDialog

wdcObj.wdcSpellCheckDialog(TextToCheck)

Purpose:

Initiates the Word spellchecker dialog for checking of text supplied as a parameter. The dialog is presented independently of Word - Word need not be running before this function is called. Useful if you wish to incorporate spellchecking functionality into your application.

Word Version Note: this function will only work successfully with Word 97 or later. With other versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

The function uses its own instance of Word to do the spellchecking and this instance will appear briefly on the Task Bar while the dialog is presented.

The TextToCheck parameter provides the text with which the spellcheck dialog will be invoked.

See also wdcSpellCheckWord.

Returns:

The corrected text on closure of the dialog, or "" if an error occurs

ReturnCodes (obtainable from wdcObj.ReturnCode):

0 on success

-9001 if Word not launched

-9004 if parameters invalid

-9005 unsupported Word version (pre Word 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

MyText = "Now is the tim for all good menn to come to the aid of the party"

ReturnedString = wdcObj.wdcSpellCheckDialog(MyText)


wdcSpellCheckWord

wdcObj.wdcSpellCheckWord(WordToCheck [, Delimiter])

Purpose:

Returns a set of suggested spellings (up to 50) for a supplied word as offered by the Word spellchecking function. The suggestions are returned as a delimited string. This function has no user interface.

Word Version Note: this function will only work successfully with Word 97 or later. With other versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

The WordToCheck parameter provides the word for which spelling suggestions are required. If Word finds the word in the dictionary the function will return an empty string (""). An empty string may also be returned if Word cannot find the word in the dictionary but has no suggestions to make.

The Delimiter (optional) parameter provides the delimiter character to be used to separate the individual spelling suggestions in the return value.

See also wdcSpellCheckDialog.

Returns:

The delimited string of suggestions, or "" if an error occurs

ReturnCodes (obtainable from wdcObj.ReturnCode):

0 on success

-9001 if Word not launched

-9004 if parameters invalid

-9005 unsupported Word version (pre Word 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Examples:

MyWord = "pigg"

this returns the string "pig/piggy/peg/ping/pigs/pug/prig"

ReturnedString = wdcObj.wdcSpellCheckWord(MyWord)

MyWord = "pigg"

this returns the string "pig~piggy~peg~ping~pigs~pug~prig"

ReturnedString = wdcObj.wdcSpellCheckWord(MyWord, "~")


wdcTextFileToDocument

wdcObj.wdcTextFileToDocument(TextFilePath [, TemplatePath] [, PositionInDoc] [, SwitchOrientation] [, AutoPrint])

Purpose:

Creates a new document and inserts into it the complete contents of a text file. Can be used for general reporting where an application assembles the report data in a text file before calling this function. The new document may or may not be based on a Word template. If the new document is based on a template the text file can be inserted at any point within that template.

TextFilePath is the path of the text file containing the data to be inserted into the document.

TemplatePath (optional) is the file path of the Word template to be used to create the new document. If TemplatePath is not present the new document is created from the Normal template.

PositionInDoc (optional) indicates where the text file is to be inserted within the new document. This can be "Start", "End" or a Word bookmark name. This parameter is only used if TemplatePath is also supplied. The default value is "End". If a bookmark name is specified but is not found in the specified template then the default value "End" is also used.

The SwitchOrientation (optional) parameter has value True or False. A value of False indicates that the default page orientation for the relevant template (or the Normal template if none is specified) is to be used for the new document. A value of True changes the orientation from Portrait to Landscape or from Landscape to Portrait.

The AutoPrint (optional) parameter allows you to automatically print the newly created document to the default printer. It has values as follows:

0	do not print (default)

1	print the new document and leave it open

2	print the new document and close it (without saving)

See also wdcInsertFile, wdcTextFileToTable.

Returns:

0 on success

-41 if TemplatePath is specified but not found

-9001 if Word is not open

-9004 if parameters invalid.

-9007 if TextFilePath is not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

All of the following are valid:

creates a new document from the default Normal template and inserts the text file

RetCode = wdcObj.wdcTextFileToDocument("c:\mydata.txt")

creates a new document from a supplied template and inserts the text file at

the end

RetCode = wdcObj.wdcTextFileToDocument("c:\mydata.txt", ""c:\templates\let1.dot")

creates a new document from a supplied template and inserts the text file at

the point marked by bookmark "book1"

RetCode = wdcObj.wdcTextFileToDocument("c:\mydata.txt", ""c:\templates\let1.dot", _

"book1")


wdcTextFileToTable

wdcObj.wdcTextFileToTable(TextFilePath [, TemplatePath] [, PositionInDoc] [, SwitchOrientation] [, AutosizeColumns] [, TableBorders] [, AutoPrint])

Purpose:

Inserts into a document a Word table created from data in a text file. Can be used for general reporting where the calling application builds up the data in a text file before calling this function. The document may be the active document or a new document which may or may not be based on a Word template. If the document is the active document or a new document based on a template then the table can be inserted at any point within that document.

TextFilePath is the path of the text file containing the data to be inserted into the document. Each record in the file should contain all the data for one row in the table. Column data should be delimited, normally by commas. For more information on file formats see Word Templates and Data Sources.

TemplatePath (optional) is the file path of the Word template to be used to create the new document. If TemplatePath is not present a new document is created from the Normal template. A special value of "Active" in this parameter directs the function to create the table in the currently active document.

PositionInDoc (optional) indicates where the text file is to be inserted within the document. This can be "Start", "End" or a Word bookmark name. This parameter is only used if TemplatePath is also supplied. The default value is "End". If a bookmark name is specified but is not found in the specified template then the default value "End" is also used.

The SwitchOrientation (optional) parameter has value True or False. A value of False indicates that the default page orientation for the relevant template (or the Normal template if none is specified) is to be used for the new document. A value of True changes the orientation from Portrait to Landscape or from Landscape to Portrait.

The AutosizeColumns (optional) parameter has values True or False. A value of False indicates that default Word column widths should be used for the created table. A value of True (the default) indicates that once Word has created the table it should resize each column width to create a "best-fit".

The TableBorders (optional) parameter has values 0, 1 or 2. A value of 0 indicates that the created Word table should have no borders or gridlines. A value of 1 (default) indicates that that the table should have gridlines and a bold outside border. A value of 2 indicates that that the table should have gridlines, a bold outside border and that the first row should also have a bold border (useful if the table contains a header row).

The AutoPrint (optional) parameter allows you to automatically print the newly created document to the default printer. It has values as follows:

0	do not print (default)

1	print the new document and leave it open

2	print the new document and close it (without saving)

See also wdcTextFileToDocument,wdcConvertTextToTable

Returns:

0 on success

-41 if TemplatePath is specified but not found

-9001 if Word is not open

-9004 if parameters invalid.

-9007 if DataFilePath is not found

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Examples:

All of the following are valid:

creates a new document from the default Normal template and creates the table

RetCode = wdcObj.wdcTextFileToTable("c:\mydata.txt")

creates a new document from a supplied template and creates the table at

the end

RetCode = wdcObj.wdcTextFileToDocument("c:\mydata.txt", ""c:\templates\let1.dot")

creates a new document from a supplied template and creates the table at

the point marked by bookmark "book1". Column widths are left as default and no

borders are drawn around the table

RetCode = wdcObj.wdcTextFileToDocument("c:\mydata.txt", ""c:\templates\let1.dot", _

"book1", , False, 0)


wdcUnFreeze

wdcObj.wdcUnFreeze

Purpose:

Unfreezes the Word window which has previously been frozen by a call to wdcFreeze. See the documentation for wdcFreeze for important considerations regarding use of this function.

Note: Windows only allows one window on the desktop to be frozen at a time. This function actually unfreezes whichever window is frozen at the time. If no window is frozen no error occurs.

See also wdcFreeze

Returns:

0 on success

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

RetCode = wdcObj.wdcUnFreeze


wdcUnprotectDocument

wdcObj.wdcUnprotectDocument([Password])

Purpose:

Unprotects a protected document so that it can be edited.

Word Version Note: this function will only work successfully with Word 97 or later. With other versions of Word this function returns ReturnCode -9005 which can be trapped by the calling application and handled appropriately.

This function unprotects the document whatever type of protection is in force (there are several protection types - see wdcProtectDocument).

Password (optional) is required if a password was specified at the time the document was protected. If a password is required but not specified, Word presents the User with a dialog asking for the password.

See also wdcProtectDocument, wdcSetSectionProtection.

Returns:

0 on success

-4198 command failed (e.g. password dialog cancelled)

-4248 command unavailable because no document is active

-4605 document is already unprotected

-5485 invalid password

-9001 if Word not launched

-9005 unsupported Word version (pre Word 97)

ReturnCode 0 indicates success.

ReturnCodes less than zero are failure codes.

Example:

All of the following are valid:

if no password was set when protecting the document

RetCode = wdcObj.wdcUnprotectDocument

or

RetCode = wdcObj.wdcUnprotectDocument("")

if a password is required

RetCode = wdcObj.wdcUnprotectDocument("mypassword")


Error Handling

Whenever a WordController procedure is executed the resulting return code and any error text and/or result value are stored in the ReturnCode, ErrorText and ResultValue properties of the WordControl object. They remain available until the next procedure executes or the WordControl object is destroyed.

After executing any WordController procedure it is advisable to test for a negative ReturnCode. If one is found it is simple to then retrieve and display the relevant ErrorText.

By default, no error messages are displayed to the user by WordController. It is left to the Developer to decide when to display messages and when not to. It is possible, however, to switch on automatic error display by using the DisplayErrors property of the WordControl object:

WordControlObj.DisplayErrors = True

Now when an error is encountered by WordController a message box including the error number and description will automatically be displayed. It can be useful to set DisplayErrors on during development as any errors are then more obvious.

The WordController reference documentation lists common return codes for each function but the list of possible error codes is long. For more information see the Microsoft Word Visual Basic Reference help file  search for "trappable errors".


Word Templates and Data Sources

The wdcBuildDocumentFromTemplate, wdcMailMergeDocument, wdcMailMergeDocWithOptions, wdcMailMergeLabels, wdcMailMergeLblWithOptions,

wdcTextFileToDocument and wdcTextFileToTable methods can all take a data file path as a parameter (in some cases this is optional). Some of the functions also require a Word template file path (again, in some cases this is optional). In order for these functions to work correctly the data source file and template must be prepared in a particular way prior to calling the functions.

Word templates are files with the extension .DOT which are used as a basis for creating new documents which contain variable information. A calling application can insert variable data into a new document which is based on a template. The WordController functions which use templates require those templates to be created in a particular way.

Data source files as used by WordController are text files which contain the data to be inserted or merged into documents.

Word templates should be created during system design or by application Users. They must exist prior to application execution. Data source files, however, are normally created dynamically during application execution and then their names are passed as parameters to the relevant WordController functions.

Data Sources and wdcBuildDocumentFromTemplate

Data Sources and Mail Merges

Data Sources and wdcTextFileToDocument

Data Sources and wdcTextFileToTable


Data Sources and wdcBuildDocumentFromTemplate

A template document which is to be used by the wdcBuildDocumentFromTemplate function must contain Word bookmarks in the places in which data is to be inserted. These bookmarks can be named individually as desired. Use Insert…Bookmark in Word to create a bookmark when designing your template.

wdcBuildDocumentFromTemplate builds a complete document from a template and replaces all the bookmarks in the template with real data. The function allows the Developer a choice of two ways to pass the data in. There are two optional parameters named DataFilePath and DataAsDelimitedString. One but not both of these parameters must be supplied at runtime.

If DataFilePath is supplied then the function will retrieve data from a text file. If DataAsDelimitedString is supplied then the data is passed in a single delimited string. In either case the function expects pairs of bookmark names and data values separated by a Delimiter character (by default "/" but optionally supplied as another parameter to the function). The function creates a new document from the specified template, searches for the supplied bookmark names and replaces them with the supplied data values.

Suppose we create a simple Word template which contains three bookmarks named "Name", "Company", "Job". At runtime we must obtain the real data values for these three variables and present them as follows:

a) as a text file.

The text file should contain one record per bookmark, in the form

bookmarkname+delimiter+value

for example:

Name/Mr. J. Johnson

Company/Acme Insurance Inc.

Job/Director

In this example the bookmarks and data values are separated by the default Delimiter character but another delimiter may be used if desired (if there is a chance that the character "/" might be found in the data).

b) as a text string.

In this case all the bookmarks and values are concatenated together into a single string:

"Name/Mr. J. Johnson/Company/Acme Insurance Inc./Job/Director"

The sequence of bookmarks is not significant. They need not appear in the same order as in the Word template.

When the wdcBuildDocumentFromTemplate function executes it reads the bookmark names and data values from the text file or delimited string and replaces each bookmark with the relevant data. So in the above example the bookmark named "Name" would be replaced by "Mr. J. Johnson", the bookmark named "Company" would be replaced by "Acme Insurance Inc.", and the bookmark named "Job" would be replaced by "Director".

For an example of a template and data source file used by wdcBuildDocumentFromTemplate see files FORMLETTER.DOT and FORMLETTER.TXT in the installation pack. See also WordController in Action - creating a Form Letter.


Data Sources and Mail Merges

wdcMailMergeDocument

A template document which is to be used by the wdcMailMergeDocument function must contain Word MergeFields in the places in which data is to be inserted. These MergeFields should have names which match the names in the first record of the data source text file. The first record in the data source file is a header record which defines the positions of the various data values in the subsequent data records.

When the wdcMailMergeDocument function executes it reads each record in the data source file in turn and merges the data contained in that record (which may contain several delimited data values) into the template document to create a new merge document.

The fields in the data source file should be contained in double quotes and separated by comma delimiters. Thus the data source file may contain records as follows:

"Name","Company","JobTitle"

"A. Brown","Brown Engineering","Director"

"B. Smith","SmithCo Foods","IT Manager"

"C. Jones","Jones Incorporated",""

The first record is the header record which indicates the names of the MergeFields in the template into which the data is to be inserted.

For an example of a template and data source file used by wdcMailMergeDocument see files MERGELETTER.DOT and MERGEDATA.TXT in the installation pack.

WdcMailMergeLabels

The wdcMailMergeLabels function uses data source text files with the same format as those used by the wdcMailMergeDocument function (described above). A header record is required, followed by multiple data records. The templates are slightly different in that they contain repeated MailMerge fields - a separate set for each label.

For an example of a template and data source file used by wdcMailMergeLabels see files MERGELABELS.DOT and MERGEDATA.TXT in the installation pack.


Data Sources and wdcTextFileToDocument

The wdcTextFileToDocument function inserts the contents of a text file into a newly created document. The data in the text file should be prepared exactly as it is to go into the document.

In this function a Word template is optional. Using a template may be useful if particular text styles are required. The contents of the text file may be inserted at the beginning or end of the template document. It is also permissable to include a named bookmark in the template and specify that the file is to inserted at the position denoted by this bookmark.


Data Sources and wdcTextFileToTable

The wdcTextFileToTable function creates a Word table from the contents of a text file and inserts it into a newly created document. The data in the text file should be prepared as described above for the wdcMailMergeDocument function.

As with wdcTextFileToDocument, a Word template is optional. Using a template may be useful if particular text styles are required. The table may be inserted at the beginning or end of the template document. It is also permissable to include a named bookmark in the template and specify that the table is to inserted at the position denoted by this bookmark.

For an example of a data source file used by wdcTextFileToTable see file MERGEDATA.TXT in the installation pack.


Technical Support

This help file describes the WordController functions and how to use them. There may, however, be times when you need information or help which is not included.

Before seeking assistance:

Make sure that you have read the README.TXT file supplied with the software. This file may contain late breaking support information not covered by this help file

If you still need help, enquiries should be directed to

Rainier Software Solutions Ltd.,

6, Mitchell Avenue,

Newcastle,

NE2 3LA,

United Kingdom.

Tel: UK (44) 191-2813707

email: support@rainier.co.uk

www.rainier.co.uk


WordController In Action - Creating A Form Letter

The scenario here is that of creating a template letter to send to a person whose contact details are available to our application. The solution could equally apply, however, to a general reporting case where the need is to create a single template report or document containing variable data.

This section shows how, with the help of the WordController wdcBuildDocumentFromTemplate function, the template document may be created with a minimum of effort. The code is Visual Basic but could easily be ported to other development tools.

As described earlier, a template document which is to be used by the wdcBuildDocumentFromTemplate function must contain Word bookmarks in the places in which data is to be inserted. The template in this example is called FORMLETTER.DOT and is a template for a standard letter which contains bookmarks with the following names:

Name

Title

Company

Address1

Address2

Address3

Salutation

To create a bookmark in Word select the text you want to be bookmarked and choose Edit...Bookmark. Note that a bookmark may be inserted at the cursor point if no text is selected. Bear in mind that if a bookmark does cover selected text then wdcBuildDocumentFromTemplate will replace that text when it inserts data at that point in the document.

Assume that the values for all these variables have been obtained and that string variables with the same names have been populated. Given this, the following code is all that would be required to dynamically build the form letter.

Sub BuildDoc()

declare the main object variable for Wordcontroller

Dim wdcObj As New WordControl

declare other variables

Dim Name, Title, Company, Address1, Address2, Address3, Salutation, WorkString

Dim RetCode, TemplatePath

…. populate the variables with desired values

set the template to be used

TemplatePath = App.Path & "\FORMLETTER.DOT"

launch Word

RetCode = wdcObj.wdcLaunch

check to see if an error occurred and deal with it as desired

If RetCode < 0 Then GoTo WDC_ERROR

build concatenated string with bookmark names and data

WorkString = "Name/" & Name

WorkString = WorkString & "/Title /" & Title

WorkString = WorkString & "/Company/" & Company

WorkString = WorkString & "/Address1/" & Address1

WorkString = WorkString & "/Address2/" & Address2

WorkString = WorkString & "/Address3/" & Address3

WorkString = WorkString & "/Salutation/" & Salutation

RetCode = wdcObj.wdcBuildDocumentFromTemplate(TemplatePath, , _

WorkString)

check again to see if an error occurred

If RetCode < 0 Then GoTo WDC_ERROR

MsgBox "The document was built successfully", , "Complete"

Exit Sub

error handling

WDC_ERROR:

MsgBox "Error " & wdcObj.ReturnCode & ": " & wdcObj.ErrorText, , "Error"

…..

Exit Sub

End Sub

Note that only two WordController functions are required: one to launch Word in the appropriate state (in this case we use the default maximized state), and one to do the document creation. These are shown in bold. Two properties, ReturnCode and ErrorText, are also used for error handling.

Most WordController functions require Word to be launched before they can run, otherwise they return an error code -9001 ("Microsoft Word is not Open"). wdcLaunch may be used for this purpose. Note that if Word is already running, wdcLaunch will not start a new instance but will return a reference to the current instance. This means that it can be used safely in situations where you are not sure whether or not Word will be running.

If desired, a text file could have been used to build up the bookmark names and data instead of a string variable. See the wdcBuildDocumentFromTemplate documentation for more information.


Sample Visual Basic Code

A complete Visual Basic sample application is included with WordController. The application shows simple and more complex uses of WordController and incorporates a Form Letter and Mailing Labels Generator. It also shows how to handle errors and how to use WordController in combination with native calls to Word to add additional functionality.

This section presents snippets of code from the sample application to show how WordController may be used.

Declaring the main WordController object variable

Dim wdcObj As New WordControl

Setting Error Display On

wdcObj.DisplayErrors = True

Launching Word

RetCode = wdcObj.wdcLaunch(3) maximized

Opening a document

RetCode = wdcObj.wdcOpenDocument("C:\mydocs\doc1.doc", True) open read only

Checking for errors after a WordController function call

…. WordController function call

'check to see if an error occurred

If RetCode < 0 Then 'this signifies error

'use the WordController error properties to display the error as desired

MsgBox "Error (" & wdcObj.ReturnCode & "): " & wdcObj.ErrorText, vbCritical, _

"Error reported by WordController"

End If

Complete Form Letter Generation Procedure

This is taken from the sample application. When entering this procedure all customer data is already held in an array Customers(). See the application code for more details.

Private Sub btnGenFormLetter_Click()

'generates a template-based form letter using data for the selected customer

'requires Word template FORMLETTER.DOT (supplied)

Dim TemplatePath$, DataString$, CustId%, RetCode As Long

'get the customer data into a delimited string, indicating which bookmarks

'in the template each data element is to be associated with

'See reference documentation on wdcBuildDocumentFromTemplate for more

'information.

'the customer number is in the first 4 characters of the selected record

'in the list box

CustId% = CInt(Left$(lstCustomers.List(lstCustomers.ListIndex), 4))

'build the data string: bookmark1/value1/bookmark2/value2/bookmark3/value3/...

With Customers(CustId%)

    DataString$ = "Name/" & .Prefix & " " & .Forename & " " & .Surname

    DataString$ = DataString$ & "/Company/" & .Company

    DataString$ = DataString$ & "/Address1/" & .Address1

    DataString$ = DataString$ & "/Address2/" & .Address2

    DataString$ = DataString$ & "/Address3/" & .Address3

    DataString$ = DataString$ & "/Title/" & .JobTitle

    DataString$ = DataString$ & "/Salutation/" & .Salutation

End With

'specify which Word template we are going to use for the letter

TemplatePath$ = App.Path & "\FORMLETTER.DOT"

'launch Word or obtain a handle to a running instance

RetCode = wdcObj.wdcLaunch(3) 'maximized

If RetCode < 0 Then GoTo WDC_ERROR 'negative return code indicates error

'if desired Freeze the Word window so that updates are not displayed as

'they happen. This speeds execution and looks smoother

If chkFreeze Then wdcObj.wdcFreeze

'build the document

RetCode = wdcObj.wdcBuildDocumentFromTemplate(TemplatePath$, , DataString$)

If RetCode < 0 Then GoTo WDC_ERROR 'negative return code indicates error

'we could have used the AutoPrint parameter to print and then close the

'document if we wished. We could have even have performed the whole operation

'with Word hidden so that the User never sees it - all they see is the report

'appearing on the printer.

'unfreeze the Word window if we froze it

If chkFreeze Then wdcObj.wdcUnFreeze

Exit Sub

WDC_ERROR:

'always unfreeze the Word window in error situations

If chkFreeze Then wdcObj.wdcUnFreeze

If RetCode < 0 Then 'this signifies error

    'use the WordController error properties to display the error as desired

    MsgBox "Error (" & wdcObj.ReturnCode & "): " & wdcObj.ErrorText, vbCritical, "Error reported by WordController"

End If

End Sub

Combining WordController functions with native calls to Word for additional functionality

This is taken from the sample application. It demonstrates how to access the Word native Word.Basic and Word.Application objects via WordController and how to code additional functionality which will work with multiple Word versions. See the application code for more details.

Private Sub btnBuildDoc_Click()

'demonstrates combination of WordController calls and native calls to Word

'builds a table in a new non-template document using data from a text file

'using WordController.

'

'Goes on to change the background colour for the entire table to yellow

'this has to be done natively as WordController does not include

'this function

'requires datafile TABLEDATA.TXT (supplied)

Dim RetCode As Long, DataFilePath$, tmpWdObj As Object

'specify the datafile

DataFilePath$ = App.Path & "\TABLEDATA.TXT"

'launch Word or obtain a handle to a running instance

RetCode = wdcObj.wdcLaunch(3) 'maximized

If RetCode < 0 Then GoTo WDC_ERROR 'negative return code indicates error

'build the document

RetCode = wdcObj.wdcTextFileToTable(DataFilePath$, , , , , 2) 'accept defaults for all the other parameters except header row borders

If RetCode < 0 Then GoTo WDC_ERROR 'negative return code indicates error

'now set the background color to yellow using native Word.

'WordController offers the Word.Basic object as wdcObj.WordBasic

'This works for all versions but for versions 97 and later it is

'recommended that you use Word.Application instead. You must use

'Word.Basic for version 95 and earlier

'WordController offers the Word.Application object as wdcObj.WordApp

'This works ONLY for versions97 and later

If wdcObj.IsV97OrLater Then

    'code for Word 97 and later based on Word.Application

    Set tmpWdObj = wdcObj.WordApp

    tmpWdObj.Selection.WholeStory

    tmpWdObj.Selection.Tables(1).Shading.BackgroundPatternColorIndex = 7 'yellow

    tmpWdObj.Selection.HomeKey

Else

    'code for Word 95 and earlier based on Word.Basic

    Set tmpWdObj = wdcObj.WordBasic

    tmpWdObj.EditSelectAll

    tmpWdObj.FormatBordersAndShading , , , , , , , , , , , , , , , , , 7 '7=yellow

    tmpWdObj.StartOfDocument

End If

'ensure that our application comes back to the front

'after the document is built (note that this routine

'is nothing to do with WordController)

BringThisApplicationToFront

MsgBox "The document was successfully created.", vbInformation, "WordController Demo"

Exit Sub

WDC_ERROR:

If RetCode < 0 Then 'this signifies error

    'use the WordController error properties to display the error as desired

    MsgBox "Error (" & wdcObj.ReturnCode & "): " & wdcObj.ErrorText, vbCritical, "Error reported by WordController"

End If

End Sub