|
PxPlus Word Object |
The PxPlus Word object simplifies the use of the Word.Application extended object. This object consists of various properties and methods that make it easier to interact with Word documents. See Properties and Methods below.
The Word object allows more than one Word document to be opened at one time.
(The Word object was added in PxPlus 2017.)
Instantiating the Word Object
To instantiate the Word object using the handle word_obj (where word_obj could be any numeric variable), enter the following command:
word_obj=NEW("*obj/word")
To access any of the available properties and/or methods, the Word object handle (word_obj) is used, followed by an ' (apostrophe) and the property or method (with the desired parameters).
Examples:
doc=word_obj'ACTIVE_DOCUMENT
retVal=word_obj'SetDocument(3)
When an Error is Encountered
In case of method failure, the ERROR object may be useful in getting more information about the last error encountered.
Example:
If Word is unable to set the active document in the previous example because there are not three documents in the collection, retVal will be equal to '0'. Checking the Description$ property of the ERROR object may also provide more information:
PRINT word_obj'ERROR'Description$
The requested member of the collection does not exist.
Global Named Constants
The Word Application makes use of hundreds of global named constants. If required, these constants may be accessed by using the PVXCONSTANTS object, which has been defined as a property called WCONSTANTS. See *CONSTANTS.
Example:
PRINT word_obj'WCONSTANTS'wdAlertsMessageBox (should return -2)
The properties used by the Word object are listed below.
|
Property |
Description |
|
(Read Only) Handle to the active document object. This property is set by using the SetDocument method and corresponds to the WORD'ActiveDocument value. | |
|
Defaults to '0' for case insensitive searches. Set to '1' for case sensitive searches. | |
|
Allows suppression of Word message boxes. Defaults to Off ('0'). | |
|
DOCUMENTS_COUNT |
(Read Only) Number of documents opened. This property corresponds to the WORD'DOCUMENTS'Count value. |
|
ERROR |
(Read Only) Handle to Word ERROR object. Can be used to display the last error message via the Description$ property. |
|
Defaults to '0' so that the Insert (see
FindInsert below) will insert text after the position located with the Find method. | |
|
Set to a non-zero value to keep the Word application active and visible when the PxPlus Word Object is dropped. Has no effect if the VISIBLE property has not been set. Defaults to Off ("0"). (The KEEP_VISIBLE property was added in PxPlus 2020.) | |
|
Defaults to '1' so that the
FindReplaceAll and the various Find methods (see
Find,
FindInsert,
FindReplace,
FindSetColor and
FindSetFont) will search from the beginning of the document to the end. | |
|
VISIBLE |
Allows the Word application to be made visible. Defaults to Off ('0'). |
|
WCONSTANTS |
(Read Only) Handle to the Word CONSTANTS object. |
|
WORD |
(Read Only) Handle to the main Word object. Note: |
The methods used by the Word object are listed below. To make it easier to locate information for a particular method, this list has been broken into the following smaller groups:
|
|
For creating, setting, printing, saving and closing a document | |
|
|
For creating, inserting, reading and deleting a paragraph | |
|
|
For creating, inserting, reading and deleting a sentence | |
|
|
For finding, replacing, inserting and setting text color/font |
Common Parameters
The following is a list of some of the common parameters used by multiple methods of the Word object:
|
Parameter |
Description |
|
document |
1-based index number of the Word document. |
|
document_name$ |
Simple document name without the full path (e.g. "test_document.docx"). |
|
path$ or document_path$ |
Full path name for the document (e.g. "c:/application/test_document.docx"). |
|
Document Methods |
Description | |||||||||||||||||||||||||||||||||||
|
AppendFile(path$,document) AppendFile(path$,document_name$) |
Appends the file defined as path$ at the end of the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified or the file indicated by path$ is invalid. (The AppendFile method was added in PxPlus 2019.) | |||||||||||||||||||||||||||||||||||
|
CloseDocument(document) CloseDocument(document_name$) |
Closes the document specified by either an index number or a simple document name. If no document is specified, the active document will be closed. Note:
| |||||||||||||||||||||||||||||||||||
|
CloseDocuments( ) |
Closes all open documents. This method is called automatically when the Word object is dropped. Note:
| |||||||||||||||||||||||||||||||||||
|
CreateDocument(path$) |
Creates a new Word document (path$). The path$ parameter may be either a simple or full pathname. The new document is opened and becomes the ACTIVE_DOCUMENT. If the path$ parameter is null, the document is named according to the Word default (e.g. Document1.docx). Warning!
| |||||||||||||||||||||||||||||||||||
|
InsertFile(path$) InsertFile(path$,para_num) InsertFile(path$,para_num,document) InsertFile(path$,para_num,document_name$) |
Allows you to merge two files together by inserting a specified file into a given location (paragraph number) in a particular document. Inserts the file defined as path$ in the document specified by either an index number or a simple document name. The file will be inserted beginning as paragraph number para_num. If no document is specified, the active document is assumed. If para_num is not specified or is set to 0, the file will be inserted beginning at paragraph 1. If para_num is larger than the current number of paragraphs, the paragraph will be inserted before the last paragraph. Alternatively, to insert a file at the very end of the document, use one of the AppendFile( ) methods. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified or the file indicated by path$ is invalid. (The InsertFile method was added in PxPlus 2019.) | |||||||||||||||||||||||||||||||||||
|
OpenDocument(path$) |
Opens the Word document located at pathname path$. After opening a document, the ACTIVE_DOCUMENT property is set to the document object corresponding to the document just opened. Note:
| |||||||||||||||||||||||||||||||||||
|
PrintDocument( ) PrintDocument(document) PrintDocument(document_name$) |
Prints the document specified by either an index number or a simple document name. If no document is specified, the active document is printed. To print all of the documents currently opened, pass a document_name$ of 'ALL' (case insensitive). Note:
| |||||||||||||||||||||||||||||||||||
|
SaveAsDocument(document_path$) SaveAsDocument(document_path$,document) SaveAsDocument(document_path$,document_name$) |
Used to save a document to a different location or with a different file format. Saves the document specified (by either an index number or a simple document name) with the pathname provided. If no document is specified, the active document is saved. If a full pathname is not provided, the document will be saved in the default Word document folder. The format used to save the document is determined by the extension specified in the document_path$. Supported extensions are listed below (in alphabetical order).
Returns '1' if successful. (Support for other file formats was added in PxPlus 2018.) | |||||||||||||||||||||||||||||||||||
|
SaveDocuments( ) |
Saves all currently opened documents. Returns '1' if successful. | |||||||||||||||||||||||||||||||||||
|
SaveDocument( ) SaveDocument(document) SaveDocument(document_name$) |
Saves the document specified by either an index number or a simple document name. If no document is specified, the active document is saved. Returns '1' if successful. | |||||||||||||||||||||||||||||||||||
|
SetDocument(document_name$) |
Sets the active document object ACTIVE_DOCUMENT to the document specified by either an index number or a simple document name (e.g. sample_doc.docx). Returns '1' if successful. |
|
Paragraph Methods |
Description |
|
AppendParagraph(para_text$) AppendParagraph(para_text$,document) AppendParagraph(para_text$,document_name$) |
Appends the text defined as para_text$ as a new paragraph at the end of the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. To insert a paragraph with no text, set para_text$="". Returns '1' if successful. Returns '0' if Word was unable to locate the document specified. (The AppendParagraph method was added in PxPlus 2019.) |
|
InsertParagraph(para_text$) InsertParagraph(para_text$,para_num) InsertParagraph(para_text$,para_num,document) InsertParagraph(para_text$,para_num,document_name$) |
Inserts the text defined as para_text$ as a new paragraph added to the document specified by either an index number or a simple document name. The paragraph will be inserted as paragraph number para_num. If no document is specified, the active document is assumed. If para_num is not specified or is set to 0, the paragraph will be inserted as paragraph 1. If para_num is larger than the current number of paragraphs, the paragraph will be inserted as the last paragraph. Alternatively, to insert a paragraph at the very end of the document, use one of the AppendParagraph( ) methods. To insert a paragraph with no text, set para_text$="". Returns '1' if successful. Returns '0' if Word was unable to locate the document specified. (The InsertParagraph method was added in PxPlus 2019.) |
|
ReadParagraph$(para_num) ReadParagraph$(para_num,document) ReadParagraph$(para_num,document_name$) |
Reads the contents of the paragraph numbered para_num in the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. A para_num value of less than 1 will read the first paragraph. Returns a string containing the text for the paragraph specified if successful. Returns '0' if Word was unable to locate the document specified or the paragraph number para_num does not exist. (The ReadParagraph$ method was added in PxPlus 2019.) |
|
DeleteParagraph(para_num) DeleteParagraph(para_num,document) DeleteParagraph(para_num,document_name$) |
Deletes the paragraph numbered para_num from the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. A para_num value of less than 1 will delete the first paragraph. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified or the paragraph number para_num does not exist. (The DeleteParagraph method was added in PxPlus 2019.) |
|
Sentence Methods |
Description |
|
AppendSentence(sent_text$) AppendSentence(sent_text$,document) AppendSentence(sent_text$,document,name$) |
Appends the text defined as sent_text$ as a new sentence (or sentences) at the end of the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified. (The AppendSentence method was added in PxPlus 2019.) |
|
InsertSentence(sent_text$) InsertSentence(sent_text$,sent_num) InsertSentence(sent_text$,sent_num,document) InsertSentence(sent_text$,sent_num,document_name$) |
Inserts the text defined as sent_text$ as a new sentence added to the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. If sent_num is set to 0, the sentence will be inserted as sentence 1. If sent_num is larger than the current number of sentences, the sentence will be inserted as the last sentence. Alternatively, to insert a sentence at the very end of the document, use one of the AppendSentence( ) methods. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified. (The InsertSentence method was added in PxPlus 2019.) |
|
ReadSentence$(sent_num) ReadSentence$(sent_num,document) ReadSentence$(sent_num,document_name$) |
Reads the contents of the sentence numbered sent_num in the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. A sent_num value of less than 1 will read the first sentence. Returns a string containing the text for the sentence specified if successful. Returns '0' if Word was unable to locate the document specified or the sentence number sent_num does not exist. (The ReadSentence$ method was added in PxPlus 2019.) |
|
DeleteSentence(sent_num) DeleteSentence(sent_num,document) DeleteSentence(sent_num,document_name$) |
Deletes the sentence numbered sent_num from the document specified by either an index number or a simple document name. If no document is specified, the active document is assumed. A sent_num value of less than 1 will delete the first sentence. Returns '1' if successful. Returns '0' if Word was unable to locate the document specified or the sentence number sent_num does not exist. (The DeleteSentence method was added in PxPlus 2019.) |
|
Text Methods |
Description |
|
Find(find$) Find(find$,document) Find(find$,document,instance) Find(find$,document_name$) Find(find$,document_name$,instance) |
Determines if a particular string (find$) exists in a document specified by either an index number or a simple document name. If no document is specified, the Find will check the active document. Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. Returns '1' if the text find$ was found. |
|
FindInsert(find$,insert$,document) FindInsert(find$,insert$,document,instance) FindInsert(find$,insert$,document_name$) FindInsert(find$,insert$,document_name$,instance) |
Finds the text defined as find$ in a document specified by either an index number or a simple document name and inserts the text defined as insert$ into the document. If no document is specified, the active document is assumed. To perform the Insert on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. By default, the insert$ text will be inserted immediately following the find$ text. To insert the insert$ text before the find$ text, set the INSERT_BEFORE property to '1'. Returns '1' if successful. |
|
FindReplace(find$,replace$,document) FindReplace(find$,replace$,document,instance) FindReplace(find$,replace$,document_name$) FindReplace(find$,replace$,document_name$,instance) |
Finds the text defined as find$ in a document specified by either an index number or a simple document name and replaces the find$ text with the replace$ text. If no document is specified, the active document is assumed. To perform the Replace on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. Returns '1' if successful. |
|
FindReplaceAll(find$,replace$) FindReplaceAll(find$,replace$,document) FindReplaceAll(find$,replace$,document_name$) |
Finds the string find$ and replaces all occurrences with the string replace$. When only the find$ and replace$ parameters are passed, the Find/Replace is performed on the active document. Pass either a document index number or a simple document name to perform the Find/Replace on a document other than the active document without changing the ACTIVE_DOCUMENT property. To perform the Find/Replace on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. Searches will replace all occurrences of the find$ string. The FindReplace method can be used to replace a single occurrence of the find$ string. Returns '1' if successful. When finding/replacing on all documents: Returns '-1' if Word was only able to perform find/replace on some of the documents successfully. |
|
FindSetColor(find$,color_index) FindSetColor(find$,color_index,document) FindSetColor(find$,color_index,document,instance) FindSetColor(find$,color_index,document_name$) FindSetColor(find$,color_index,document_name$,instance) FindSetColor(find$,color$) FindSetColor(find$,color$,document) FindSetColor(find$,color$,document,instance) FindSetColor(find$,color$,document_name$) FindSetColor(find$,color$,document_name$,instance) |
Finds the text defined as find$ in a document specified by either an index number or a simple document name and sets the color for that text as specified in color_index or color$. If no document is specified, the active document is assumed. To set the color of the find$ text on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. The text color may be passed as one of the following: • A color index (numeric) Note:
|
|
FindSetFont(find$,font$,document) FindSetFont(find$,font$,document,instance) FindSetFont(find$,font$,document_name$) FindSetFont(find$,font$,document_name$,instance) |
Finds the text defined as find$ in a document specified by either an index number or a simple document name and sets the font information (font name, font size, font style) for that text as specified in font$. If no document is specified, the active document is assumed. To set the font of the find$ text on all opened documents, pass a document_name$ of 'ALL' (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. The font$ variable can pass font name, font size and font style (Bold, Italic, etc.), separated by commas. Example: Note:
|
This example tests the Word object.
! Test word object
!
! Instantiate object
w=NEW("*obj/word")
!
! Open document
path$="c:\documents\document1.docx"
doc1=w'OpenDocument(path$)
!
! Open another document
path2$="c:\documents\document2.docx"
doc2=w'openDocument(path2$)
!
! Check number of documents open
MSGBOX STR(w'documents_count)
!
! Set document to first document opened
t=w'SetDocument("document2.docx)
!
! Search and Replace on all opened documents
find$="[FirstName]"
replace$=firstName$
test=w'FindReplaceAll(find$,replace$,"all")
!
! Make Word visible
w'Visible=1
!
! Set active document
q=w'SetDocument(2)
!
! find text and set font in active document
w'FindSetFont("Set font on this text","Algerian,18,bold")
!
! find second instance of text and set color index of active document
w'FindSetColor("Sample text",4,0,2)
!
! Find last instance of text and replace with alternate text in test.docx
w'search_forward=0
w'FindReplace("Find Text","Replace text","test.docx",1)
!
! Save active document with another name
w'SaveAsDocument("c:\document\differentdoc.docx")
!
!
DROP OBJECT w
END
This example demonstrates using the Word object to replace given placeholders in a template document with variable data:
promo.docx document:
PxPlus promo program:
! promo - Use Word object for mail merge
!
OPEN (HFN,IOL=*)"client"
clients=LFO
!
path$="C:\PVX Plus Technologies\PxPlus version_number\word\"
!
w=NEW("*obj/word")
!
! populate client name and address data
search_fields$="ClientName$"+SEP+"Address1$"+SEP+"Address2$"+SEP+"City$"+SEP+"State$"+SEP+"Country$"+SEP+"ZipCode$"+SEP+"ytdSales"+SEP
SELECT * FROM clients WHERE ytdSales>10000
promo=w'OpenDocument(path$+"promo.docx")
!
ERASE path$+Clientid$+"docx",ERR=*NEXT
!
FOR field$ FROM search_fields$
find$="["+field$+"]"
IF find$="[ytdSales]" THEN replace$="$"+STP(STR(ytdSales:"###,###.00"),"L"," ") ELSE replace$=VIS(field$)
w'case_sensitive_search=1
w'FindReplaceAll(find$,replace$)
NEXT
!
! populate dates
w'FindReplaceAll("[TodaysDate]",DTE(0:"%Ml %D,%Y"))
w'FindReplaceAll("[YearDate]",DTE(0:"%Y"))
!
! highlight '25% off coupon'
W'FindSetColor("25% off coupon","red")
!
w'SaveAsDocument(path$+ClientId$)
w'PrintDocument(1)
w'CloseDocument(1)
!
NEXT RECORD
!
DROP OBJECT w
CLOSE (clients,ERR=*NEXT)
!
END
PxPlus Excel Object
Google Workspace Objects