");
$oWriter->TableColumnBegin();
$oWriter->Write("TableRowBegin()");
$oWriter->TableEnd();
#Save the document
$oWriter->SaveAs("01example.doc");
PROPERTIES
oWord
A Win32::OLE object with a Word Application instance.
oDocument
A Win32::OLE object with the Application's Document object. Often used
shorthand.
oSelection
A Win32::OLE object with the Application's Selection object.
oTable
The current Win32::Word::Writer::Table object, if a table is being
created, or undef if not.
METHODS
Note that all methods return 1 or die on errors, unless otherwise
stated.
new()
Create new Word Writer object which can be written to.
Return new object, or die on errors.
init()
Init the object. Called by new.
Open($file)
Discard the current document and open the Word document in $file.
Note that you may want to MoveToEnd() after opening an existing document
before adding new text.
Note that this object is in an unusable state if the Open fails to load
a document.
SaveAs($file, %hOpt)
Save the document to $file (may be a relative file name). %hOpt is:
format => $format -- Save $file as $format (default:
Document). Valid values are: Document, DOSText, DOSTextLineBreaks,
EncodedText, HTML, RTF, Template, Text, TextLineBreaks, UnicodeText
(A common mistake is to inspect the document in another Word instance
when re-running a script. The document will be locked by Word and the
script can't re-create the file.)
Checkpoint()
Checkpoint the document, i.e. save it to a temp file.
This is necessary to do sometimes because Word seems to keep state until
the document is saved, and when using Word automation you tend to
exercise the application in ways they haven't tested properly. And after
a while you get weird errors, just because Word couldn't deal with all
that information.
So you should call this after adding, say, 20K of text to the document
(this is true for Word 2000, it may be better in later versions).
Close()
Discard the current document no-questions-asked (i.e. even if it's not
saved).
Note that this object is in an unusable state until a new document is
created or opened.
METHODS - ADDING TEXT
Write($text)
Append $text to the document (using the current style etc).
WriteParagraph($text, [heading => $level], [style => $name])
Append $text as a new paragraph of heading $level or style $name. The
style overrides heading. The style should be a paragraph style.
The default style is "Normal".
NewParagraph([heading => $level], [style => $name])
Start a new paragraph of heading $level or with style $name. The style
overrides heading. The style should be a paragraph style.
The default style is "Normal".
SetStyle([$style = "Normal"])
Set the style to $style.
If $style is a paragraph style, it will change the style of the current
paragraph.
If $style is a character style, it will turn on that style. It will be
in effect until a new style is set somehow, or until it's cleared with
ClearCharacterFormatting().
ClearCharacterFormatting()
Clear the characther formatting/set it to default.
The paragraph can have a style, and individual characters a separate
formatting style.
StyleSpec([heading => $level], [style => $name])
Return the final style, given a specification of heading $level or style
$name. The style overrides heading.
The default style is "Normal".
ToggleBold()
Toggle the current Bold charachter setting
SetBold($enable)
Set the Bold status to 1 or 0.
Return the new Bold state, or throw OLE exception.
ToggleItalic()
Toggle the current Italic charachter setting
SetItalic($enable)
Set the Italic status to 1 or 0.
Return the new Italic state, or throw OLE exception.
METHODS - BULLET POINT LISTS
ListBegin()
Begin a new bullet point list.
Can be nested to create sub-lists.
Use ListItem() to create new bullet points before adding text to the
list.
ListItem()
Start a new bullet point in the list.
The first text you Write() after this becomes the new bullet text.
You should not WriteParagraph() within a list item. New paragraphs are
signals to Word to advance to the next list item, so that will confuse
Win32::Word::Writer and/or Word.
ListEnd()
End an existing bullet point list.
If it's the outermost list, go back to normal text.
METHODS - TABLES
TableBegin()
Begin a new table.
The table model resembles a HTML table with rows and columns, but you
don't have to close columns or rows. Simply start a new one.
A row and col must be created with TableRowBegin() and
TableColumnBegin() before any text is added.
Tables can not be nested.
Note that tables are rather fragile so don't expect them to work with
very complex layouts, or very wide columns. Prepare for exceptions to be
thrown.
TableRowBegin()
Begin a new row in the current table.
Add a column also before adding text to the table.
TableColumnBegin()
Begin a column in the current table in the current row.
Any new text/paragraph added to the document will end up in this table
cell until a new row or column is created, or the table is ended.
TableEnd()
Begin a column in the current table in the current row.
Any new text/paragraph added to the document will end up in this table
cell until a new row or column is created, or the table is ended.
METHODS - MOVEMENT AND SELECTION
MoveToEnd()
Set the insertion point at the end of the document.
SelectAll()
Make the selection the entire document.
Return 1 on success, else die.
METHODS - FIELDS AND TABLES
FieldsUpdate()
Update the fields in the entire document. Retain the current cursor
location.
But note this doesn't always work with Table of Contents tables.
Return 1 on success, else die.
ToCUpdate()
Update both entries and page numebers of all the Tables of Contents in
the entire document. Retain the current cursor location.
Return 1 on success, else die.
METHODS - BOOKMARKS
BookmarkAdd($name)
Add a new bookmark called $name at the current cursor location.
Return 1 on success, else die.
BookmarkGoto($name)
Go to bookmark called $name. The bookmark should exist.
Return 1 on success, else die.
BookmarkDelete($name)
Delete bookmark called $name. The bookmark should exist.
Return 1 on success, else die.
METHODS - UTILITY
MarkDocumentAsSaved()
Mark the Word document as "saved". This is in effect until the document
is changed again.
Being saved e.g. means it can be abandoned without questions.
Return 1 on success, else die.
GetFileTemp()
Return a temporary file name in fileTemp().
DESTROY
Release objects including the OLE Word object.
KNOWN BUGS
Supressing dialog boxes
The most serious problem I have with Word is that the documented way of
supressing interactive dialog boxes... doesn't work! This is worked
around in a few cases (see below), but mostly it's broken.
I don't know if this only goes for my Office 2000 Word, but it may
affect you too.
It's a very bad thing anyhow, since it can cause your program to just
freeze, waiting for user interaction. To boot, the dialog boxes are
usually displayed below other applications.
I blame Bill.
OLE errors during global destruction
If you are in the middle of a table and something goes wrong, there will
be strange OLE warnings during global destruction. I haven't found out
why this happens.
Layout too complex
I have run into this problem where, despite the no-don't- show-dialogs,
Word pops up an error dialog below all other windows (so you can't see
it, great!).
After clicking Ok in this dialog a number of times, the OLE call finally
fails properly and dies in the Perl application layer.
http://support.microsoft.com/kb/292174
The only way to not run into this problem seems to be to save the
document to disk after adding some text. The Checkpoint() method does
this for you.
Rouge WINWORD.EXE processes
Sometimes it seems like Win32::OLE has some problems with closing the
Word instance during global destruction. This happens mostly when things
die().
TODO
Tests for tables
Tests for Tables of Contents etc
Tests for Bookmarks
APPLICATION DOM INFORMATION
So what does the Word DOM look like? Actually, the documentation is
available when installing Office.
Start Word and press Alt-F11 to bring up the VBA window. There is an
Object Browser in the toolbar. Select an object, method or property and
press F1 to bring up the help.
A good way to figure out how to do something is to record a Macro and
then bring up the VBA window and inspect the code written by the Macro
Recorder.
DESIGN ISSUES
Software versions
This is tested and developed using w2k and Office 2000. Things may be
different with other versions. Please let me know.
Supressing the "Save as..." dialog box
The problem with this is that it doesn't work to follow the manual and
advice found on the Net.
The usual answer is to set DisplayAlerts to False, or wdAlertsNone. That
doesn't work for me.
What works is to set the Document.Saved property to False before
quitting (the MarkDocumentAsSaved() method).
That's why the ActiveX object is Quit from the DESTROY method, and not
using the exit handler in CreateObject which is the normal course of
action.
GOOD IDEAS
Keep an eye on the Task Manager
When you fiddle around with this program, it's useful to keep the Task
Manager window open to keep track of any WINWORD.EXE processes that may
be stuck in memory if you e.g. C-Break out of the script (don't do that,
Win32::OLE won't have a chance of cleaning up the Word instance it
created).
Kill abandoned Word processes (but make sure you don't kill any
documents you may be editing :)
EXTENDING THE MODULE
The interface of this module is spotty in an opportunistic way; I have
added utility methods as I needed them.
If you need to add your own methods, I suggest you simply inject them in
this namespace to get your application working and send me a patch.
PRIVATE PROPERTIES
These are considered implementation details, but you may need to fiddle
with them if you extend the module.
hasWrittenParagraph
Whether the writer has written a paragraph yet.
levelIndent
The indentation level for bullet point lists.
Default: 0
hasWrittenInIndent
Whether the writer has written anything after changing indentation
level.
rhConst
Ref to hash with imported Word constant symbold.
styleOld
The previous style.
fileTemp
The name of a temporary file.
AUTHOR
Johan Lindström, ""
BUGS
Please report any bugs or feature requests to
"bug-win32-word-document-writer@rt.cpan.org", or through the web
interface at
. I will be notified, and then you'll automatically be notified of
progress on your bug as I make changes.
ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE
Copyright 2005 Johan Lindström, All Rights Reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.