NAME

Win32::Word::Writer - Create Microsoft Word documents

DESCRIPTION

Easily create MS Word documents, abstracting away the Word.Application DOM interface and all the required workarounds. The DOM interface is still exposed for doing more fancy stuff.

SYNOPSIS

use strict;
use Win32::Word::Writer;

my $oWriter = Win32::Word::Writer->new();

#Adding text and paragraphs with different styles
$oWriter->WriteParagraph("Example document", heading => 1);          #Heading  level 1
$oWriter->WriteParagraph("Usage", style => "Heading 2");             #Style "Heading 2"
$oWriter->WriteParagraph("Write sentences to the document using a"); #Normal
$oWriter->WriteParagraph("heading level, or Normal
if none is specified. ");                            #\n is new paragraph

$oWriter->Write("Add some more text the current paragraph");

$oWriter->NewParagraph(style => "Envelope Return");  #The style must exist
$oWriter->Write("Return to sender. ");

$oWriter->SetStyle("Envelope Address");              #Change the current style
$oWriter->Write("Nope, we changed the style of the entire paragraph");
$oWriter->Write("to a footer style");

#Setting character styles
$oWriter->WriteParagraph("Some more normal text. ");
$oWriter->SetStyle("Hyperlink");                 #A charachter style
$oWriter->Write("http://www.DarSerMan.com/Perl/");
$oWriter->ClearCharacterFormatting();            #Clear character style
$oWriter->Write("  <-- my ");

#Bold/Italics
$oWriter->ToggleBold();         #Toggle bold
$oWriter->Write("Perl ");
$oWriter->SetItalic(1);         #Turn on Italic
$oWriter->Write("stuff.");
$oWriter->ToggleItalic();       #Toggle Italic
$oWriter->SetBold(0);           #Turn off bold

#Bullet point lists
$oWriter->ListBegin();
$oWriter->ListItem();
$oWriter->Write("The first bullet item");
$oWriter->ListItem();
$oWriter->Write("The second bullet item");

$oWriter->ListBegin();   #Nested bullet point list
$oWriter->ListItem();
$oWriter->Write("The first inner bullet item");
$oWriter->ListItem();
$oWriter->Write("The second inner bullet item");

$oWriter->ListEnd();
$oWriter->ListEnd();


#Do this at regular intervals (say, every couple of 10K of text you add)
$oWriter->Checkpoint();


#Tables
$oWriter->WriteParagraph("Table example", heading => 1);
$oWriter->NewParagraph();

$oWriter->TableBegin();
$oWriter->TableRowBegin();
$oWriter->TableColumnBegin();
$oWriter->SetBold(1);
$oWriter->Write("HTML table");
$oWriter->TableColumnBegin();
$oWriter->Write("Win32::Word::Writer");

$oWriter->TableRowBegin();
$oWriter->TableColumnBegin();
$oWriter->SetBold(0);
$oWriter->Write("<table>");
$oWriter->TableColumnBegin();
$oWriter->Write("TableBegin()");

$oWriter->TableRowBegin();
$oWriter->TableColumnBegin();
$oWriter->Write("<tr>");
$oWriter->TableColumnBegin();
$oWriter->Write("TableRowBegin()");

$oWriter->TableEnd();


#Save the document
$oWriter->SaveAs("01example.doc");

INSTALLATION

With Strawberry Perl, the regular CPAN shell should work:

cpan Win32::Word::Writer

All dependencies except Microsoft Word itself should sort itself out automatically.

This may work with ActiveState too if you have the MinGW compiler, or it might be easier to install with ppm (if available, I'm not sure about the state of the PPM repos at this point).

CONCEPTS

Win32::Word::Writer uses an OLE instance of Word to create Word documents.

The documents are constructed in a linear fashion, i.e. you add text to the document and generally don't move around the document a lot.

Styles

A "style" in Word is a set of properties that can be assigned to a piece of text. There are two types of styles: Paragraph and Character styles.

"Normal", and "Heading 1" are example of paragraph styles.

When a paragraph gets applied to a piece of text it applies to the entire paragraph, whereas the character style only affects the actual chars. You can see the difference if you open a Word document and look at the available styles.

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