Home Products Support Corporate

Support Knowledge Base, Article 1263

Product

WordWriter

Version

3.x and higher

Title

HOW-TO: Using Named Styles with the WordApplication class

Problem

In Microsoft Word, a named style is a collection of settings for formatting attributes such as font, spacing, borders, and bullet type. A named style can be applied to a paragraph, a table, a list or a block of characters. Word comes with a large set of built-in named styles, such as Body Text and various Heading styles.

While you cannot create named styles in WordWriter, you can use the WordApplication class to access named styles and apply them to a paragraph or a table. How to use named styles depends on whether you are using the WordApplication class to create a new document or to open an existing document.

This article also addresses the situation in which NullReferenceException is thrown when you try to use certain built-in named styles (see the section "Using the NamedStyle.Builtin enumeration").

Solution

How to apply a named style

A named style is represented by the NamedStyle class. Named styles associated with a document are contained in a Styles collection, which is returned by the Styles property of a Document object. The Length method of the Styles collection returns the number of styles.
To retrieve a NamedStyle object, index into the Document.Styles collection by one of the following:
1. an integer index
  Example: Document.Styles[0]
2. the name of the style
  Example: Document.Styles["Body Text"]
3. a value of the NamedStyle.Builtin enumeration
  Example: Document.Styles[NamedStyle.BuiltIn.BodyText]
The most convenient method is to use the NamedStyle.Builtin enumeration, but be aware of one issue. Refer to the "Using the NamedStyle.Builtin enumeration" for more information.
To apply a named style to a paragraph, pass a NamedStyle object as parameter to the InsertParagraphBefore and InsertParagraphAfter methods (if no named style is desired, pass null in C# or Nothing in VB.NET). Alternatively, assign a NamedStyle object to the Style property of a Paragraph object.
To apply a named style to a table, assign a NamedStyle object to the Style property of a Table object.
The code sample below illustrates the use of named styles:

[C#]

[VB.NET]

//--- doc is a new or existing document

//--- Applying a named style to a paragraph
NamedStyle style1 = doc.Styles[NamedStyle.BuiltIn.BodyText];   
Paragraph para = doc.InsertParagraphAfter(style1);
para.InsertTextAfter("The quick brown fox jumps over the lazy dog", true);

//--- Applying a named style to a table
//--- Contemporary table style must exist in document
NamedStyle style2 = doc.Styles[NamedStyle.BuiltIn.TableContemporary];
Table myTable = doc.InsertTableAfter(2, 3);
myTable.Style = style2;

'--- doc is a new or existing document

'--- Applying a named style to a paragraph
Dim style1 As NamedStyle = doc.Styles(NamedStyle.BuiltIn.BodyText)
Dim para As Paragraph = doc.InsertParagraphAfter(style1)
para.InsertTextAfter("The quick brown fox jumps over the lazy dog.", True)

'--- Applying a named style to a table
'--- Contemporary table style must exist in document
Dim style2 As NamedStyle = doc.Styles(NamedStyle.BuiltIn.TableContemporary)
Dim myTable As Table = doc.InsertTableAfter(2, 3)
myTable.Style = style2

If you wish to modify or add to the formatting settings provided by a named style, you can pass a ParagraphFormatting object as a second parameter to the InsertParagraphBefore or InsertParagraphAfter methods, or assign a TableFormatting object to the Formatting property of a table.

Using named styles when creating a new document

Before you can access and use a named style with WordApplication, the style must already be stored in the document. In Word 2003, you can view the styles stored in a document (select Format, Styles and Formatting from the Word menu, then select Available Styles from the Show drop-down list on the Styles and Formatting panel). You can also view all possible styles (select Show All Styles on the Styles and Formatting panel). Normally, the number of styles stored in a document is only a subset of all possible styles. A style is not stored with the document until it is applied.
When you create a new document with the WordApplication.Create method, WordWriter automatically includes a set of styles with the newly created document. To avoid overburdening the document with unnecessary styles, the document is given a set of 28 most commonly used styles. These are given below:

Normal
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Heading 7
Heading 8
Heading 9
Default Paragraph Font
Table Normal
No List
Block Text
Body Text
Body Text 2
Body Text 3
Body Text First Indent
Body Text Indent
Body Text First Indent 2
Body Text Indent 2
Body Text Indent 3
Closing
Date
E-mail Signature
Emphasis
Envelope Address
Header

Using named styles when opening an existing document

When you open an existing document with the WordApplication.Open method, you have access to only those named styles which are stored in the document, including custom named styles that you create before saving the document. Using custom named styles is discussed in the next section.
When you create a blank document in Word (select File, New from the menu), the document contains as many styles as are defined in the Word template on which the document is based. For example, a blank document created from the default Normal.dot template contains only a handful of basic styles. By contrast, a blank document based on the Contemporary Report.dot template has as many as 98 predefined styles.
Note that a document based on the default Normal.dot template contains fewer predefined styles than a document created with the WordApplication.Create method.
If you apply other styles to the document which are different from the default styles, the additional styles will be associated with the document and accessible to WordApplication.

Using custom named styles

In Word, you can create custom named styles. When you open an existing document containing custom styles, the custom styles are stored in the document's Styles collection. You can access a custom style using an integer index or the style's name.
For example, if you open an existing document containing a custom style named "My Style", you can retrieve the NamedStyle object for "My Style" with Document.Styles["My Style"].

Using the NamedStyle.Builtin enumeration

To get a NamedStyle object, you can use a value of the NamedStyle.Builtin enumeration as an index into the Document.Styles collection. For example, the following statement returns the the NamedStyle object for the Body Text style:

[C#]	[VB.NET]
NamedStyle style; style = Document.Styles[NamedStyle.BuiltIn.BodyText]; Dim style As NamedStyle style = Document.Styles(NamedStyle.BuiltIn.BodyText)

The NamedStyle.Builtin enumeration lists all of the possible built-in named styles in Word. The Document.Styles collection contains only the styles that are stored in the document. Typically, there are many more possible built-in styles in Word than are stored in the document.
Consequently, when you index into the Document.Styles collection using a value of the NamedStyle.Builtin enumeration, you must select a style that belongs to the collection. Otherwise, if you choose a style that does not exist in the collection, a NullReferenceException will be thrown. Unfortunately, this mistake is easy to make, because Visual Studio's IntelliSense lists all of the values in the NamedStyle.Builtin enumeration.
For a new document created with the WordApplication.Create method, choose a NamedStyle.Builtin enumeration value corresponding to one of the 28 styles listed above. If you want to use a different style from these 28 styles, do not create a new document with WordApplication.Create. Instead, use the following workaround:

In Word, create a blank document
Enter some text and apply all desired styles
Delete the text and save the document
Open the saved document with WordApplication.Open
Access the explicitly applied named style which should now be stored with the document

For an existing document, you must know a priori the named styles that exist in the document and choose the corresponding NamedStyle.Builtin enumeration values.