Numbering run amok

Word's paragraph numbering sometimes goes haywire. Just when you think you've got it organized, the numbering starts doing silly things. If Word's paragraph numbering were a group of orchestral musicians, it might look like this:

What's needed?

What's needed is someone to get those mad horn players organized and co-ordinated. We don't need another player: we clearly have enough of those! What we need is a co-ordinator.

In an orchestra, the conductor co-ordinates. For Word's numbering, the mechanism we use to organize and co-ordinate paragraph numbering is a List Style. The List Style co-ordinates. It doesn't do the actual work of formatting text. We leave that to paragraph styles.

So, we need:

• a List Style as the co-ordinating mechanism for the numbering, and
• a paragraph style for each heading level (Word allows, actually requires, 9 levels).

A List Style actually does two things.

• A List Style creates a set or group of styles. Word comes with built-in paragraph styles named Heading 1, Heading 2, Heading 3. But there is no connection between them. They just happen to share similar names. A List Style 'groups' those paragraph styles into some order. Only the List Style knows that Heading 1 is followed by Heading 2 and that it is followed by Heading 3. There are 9 levels in any List Style.
• A List Style stores the information about how to number each level. That includes the format of the number ( "1" or "a" or "i"), whether the number is preceded by text (eg "Chapter 1" or "Part A"), whether the number includes previous levels' numbers (eg paragraph 1.4.3), and the indents (the distance from margin to number and from number to text).

Set up your Heading paragraph styles

There are good reasons for using the built-in Heading styles.

Before you begin the numbering, make sure your Heading styles are set up appropriately.

Modify the Heading 1 style so that it is based on "No style". Modify Heading 2 so it's based on Heading 1. Modify Heading 3 based on Heading 2. And so on. Not everyone does this, but I find it useful because of the way the formatting of Word's styles cascade.

Now, modify the Paragraph settings of every Heading style so that the Left Indent is 0, and the Special indent is set to (none). Do this even if you want your headings to be indented from the left margin, and even if you want a hanging indent. Why? Because for outline-numbered styles, we will set the paragraph indent and the hanging indents (if any) when we set up the numbering.

Create a list style

To create your list style, on the Home tab, in the Paragraph group, click the Multilevel list menu (Figure 1).

From the menu, choose Define New List Style (Figure 2).

In the Define New List Style dialog (Figure 3), do (only) two things:

1. Give your list style a name.
   Hint: Give it a plural name. That makes it clear that this is a list style that's controlling more than one paragraph style. And, give it a name directly related to the paragraph styles you're going to use. We're going to use paragraph styles Heading 1, Heading 2, Heading 3 etc. So I suggest that you name the list style as Headings.
2. On the Format menu, click Numbering.

We're now in the Modify Multilevel List dialog box (Figure 5). The list style is the co-ordinating mechanism for the whole "set" of paragraph styles we'll use. So we set up all levels of numbering in this one dialog box.

To set up the numbering:

1. In the Modify multilevel list dialog, click the More button.
2. Attach the Heading paragraph styles to the 9 levels in the list style. To do that:
   1. In the 'Click level to modify' list, select level 1. In the 'Link level to style' box, choose Heading 1. That attaches paragraph style Heading 1 to level 1 of the list style.

   2. In the 'Click level to modify' list, select level 2 and attach style Heading 2. And attach Heading 3 to level 3, Heading 4 to level 4 and so on.

3. Now we tell Word about the numbering itself for Level 1
   1. In the 'Click level to modify' list, click level 1.
   2. Delete anything in the 'Enter formatting for number" box.
   3. If you want the numbering to start with some text (eg to number a paragraph as "Chapter 1" or "Section 1") then enter the text including any space in the 'Enter formatting for number' box. Leave the insertion point after your text.
   4. From the Number style for this level list, choose the kind of numbering you want.
4. Set up numbering for levels 2 to 9.
   1. In the 'Click level to modify' list, choose Level 2.
   2. Delete anything in the 'Enter formatting for number" box.
   3. If you want to include a previous level's numbering, then use the 'Include level number from' box. If you want punctuation after each level, add it into the 'Enter formatting for number' box as you go.

      For example, for Level 2, I might want the numbering to be "1.1". That is, I want the Level 1 number and the Level 2 number. So, from the 'Include level number from' box, I choose 'Level 1'. Then I type a full stop (full point, period, whatever). Then I choose from the 'Number style for this level' box.

      You have to do each previous level separately. By the time you come to do Level 9, if you want paragraphs numbered 1.1.1.1.1.1.1.1.1, you need to add Level 1, Level 2, Level 3 etc, all the way to Level 8. This can get tedious, but hang in there!

   4. From the Number style for this level list, choose the kind of numbering you want for the current level.
   5. Repeat for each of levels 3 to 9. If you don't want numbering for a level, leave the 'Enter formatting for number' box empty.
5. Next, set up the indents: how far in from the left margin do you want the different levels to appear? The default indents are actually quite reasonable. If you prefer to change them, then you have two choices. The easy way is to click the "Set for all levels" button. You'll see the Set for All levels dialog (Figure 4).

   

   Figure 4: Use the Set for All levels dialog to manage indents for your headings

    

   The hard way is to set the 'Aligned at', 'Text indent at' and 'Add tab stop at' boxes individually. Just remember that they're all measured from the left margin.

6. My finished settings look like Figure 5.

   

   Figure 5: The finished settings in the Modify Multilevel List dialog

    

7. OK, OK back to your document.

How to apply the Heading styles to your text

So you have set up your List Style. But we don't ever use the List Style. Instead, we format paragraphs using the Heading 1, Heading 2 etc paragraph styles. Because you linked the heading paragraph styles to the List Style, the heading styles will now use the numbering you set up in the List Style.

How to apply Heading 1 style to a paragraph

To apply the numbering to one or more paragraphs in your document:

1. click once within a paragraph, or select text from two or more paragraphs
2. on the Home tab, click the thumbnail for the Heading 1 style  (or, for keyboard junkies, use Ctrl-Alt-1, which is the built-in keyboard shortcut for applying style Heading 1).

How to create a lower-level heading (or: how to demote a heading)

You can create lower levels of headings by applying the paragraph styles Heading 2, Heading 3 etc. There are lots of ways to apply a paragraph style to your text. Here are three particularly relevant to headings:

• By default, the heading styles appear on the Quick Styles gallery as you need them. That is, once you've used, say, style Heading 4, then Heading 5 will automagically appear on the Quick Styles gallery. Click in your paragraph, click the thumbnail for the style you want and presto! the paragraph is numbered.
• Use the built-in keyboard shortcuts for the first three levels of headings: Alt-Ctrl-1, Alt-Ctrl-2, Alt-Ctrl-3.
• Use the Increase Indent button. It's on the Home tab, in the Paragraph group (Figure 6). And, to promote a paragraph (ie move it to the left), use the Decrease Indent button. Or, for keyboard junkies use Shift-Alt-Right arrow and Shift-Alt-Left arrow.

  There are three important things to note here:

• If you click in a paragraph in a Heading 1 style and click the Increase Indent button (or do Shift-Alt-Right arrow), you're not applying some kind of nasty direct formatting. Word will apply style Heading 2 to your text. Click Increase Indent again, and Word will apply style Heading 3. And so on.

  That is, Word is applying the appropriate paragraph styles to your paragraphs.

• The Increase Indent and Decrease Indent buttons (and Alt-Shift-Left and Alt-Shift-Right) only work in this special way because you attached your Heading paragraph styles to a list style. They don't work like this out-of-the-box.

How to edit your numbering scheme

Your numbering scheme is stored in your Headings list style. It's not stored in the individual paragraph styles. Therefore:

• Edit the individual paragraph styles if you want to change paragraph settings (eg space before or after) or the font of the text that follows the heading text (eg to make it big or pink or bold). To edit an individual paragraph style, see How to modify styles in Microsoft Word.
• Edit the list style if you want to change the numbers, the position between number and text, the size of the number itself and so on. To edit your list style:
  • Click in a heading.
  • On the Home tab, in the Paragraph group, click the Multilevel list menu button (Figure 7)

    

    Figure 7: Choose the Multilevel list menu

     

     

  • You will see the Headings list style highlighted at the bottom of the menu.
  • Right-click the thumbnail for the Headings list style and choose Modify. Format > Numbering (Figure 8). You can how change any or all of your numbering settings.

    

    Figure 8: To edit your list style, hover over the thumbnails for the list styles to identify the one you need, then right-click and choose Modify.

     

Is all this really necessary? Can't I just use the List Library?

If using the List Library on the Multilevel List menu (see Figure 2 or Figure 8 ) works for you, then go for it! For quick'n'dirty work, it may be just the thing.

For a corporate template that will be used by hundreds or thousands of users, it's probably not the best solution. For really big complicated documents, or documents where you have to cut and paste from one document to another a lot, then the List Library may let you down.

For more information, direct from Microsoft's Word development team, see The Many Levels of Lists and Multilevel Lists vs List Styles.

Too good to be true?

Related articles on other sites

All sounds too good to be true? It is. When you've finished getting your numbers just right, you might be interested to read some of the material MVPs have put together on numbering. Start at the Microsoft Word MVP FAQ site, click FAQ and then Numbering.

And, read from people in Microsoft's Word development team about numbering especially Stuart Stuple's The Why Behind Our Styles and Lists Designs.

Related articles on this site

How to create numbered headings or outline numbering in your Microsoft Word document.

How to number headings and figures in Appendixes in Microsoft Word

Photo info

Photograph of horn players taken at National Music Camp, Geelong Grammar, January 1993. I have no recollection of why all the horn players were wearing silly hats, but National Music Camp has a fine tradition of encouraging innocent pranks and general merriment—as well as damned hard work—so it's not entirely surprising. What's more puzzing is why I kept the photo all these years!

John Curro, conductor of the Queensland Youth Orchestra who taught me more than I'll ever know.

To set background and foreground colours, do these steps in order:

1. Set the .BackgroundPatternColor.
2. Set the .Texture. If you don't want a visible texture, set texture to wdTextureNone.
3. Set the .ForegroundPatternColor. If you don't want a visible foreground, set the colour to wdColorAutomatic.

In the Microsoft Word object model, background and foreground colours are controlled through a Shading object. This article explains how to manage shading for paragraph styles using the Microsoft Word object model.

Shading basics

Shading is controlled through a .Shading object. There are three main properties of a .Shading object:

• .BackgroundPatternColor
• .ForegroundPatternColor
• .Texture

And, there are two properties of a paragraph style that return a .Shading object:

• Style.Shading
• Style.ParagraphFormat.Shading

These two objects appear to be the same thing. That is, if you set, say, myStyle.Shading.ForegroundPatternColor = wdColorRed, then Word automatically sets the myStyle.ParagraphFormat.Shading.ForegroundPatternColor to red. You can't set them independently.

The properties of a .Shading object mirror the user interface:

Relationships between foreground colour, background colour and texture

The tricky bits come when you try to work out how to manipulate the combination of foreground and background colours, and texture.

In the user interface, if you choose the Clear texture (wdTextureNone in the object model), then you only see the background colour. The UI won't let you set the foreground colour. If you choose the Solid texture (wdTextureSolid in the object model), then you only see the foreground colour.

In the object model, a newly-created paragraph style has:

• .BackgroundPatternColor = wdColorAutomatic
• .ForegroundPatternColor = wdColorAutomatic
• .Texture = wdTextureNone

In the normal course of events, when you just want some coloured shading, set the .BackgroundPatternColor and ensure that the .Texture is wdTextureNone.

However, if you set the .ForegroundPatternColor to any colour other than wdColorAutomatic, and you don't set the .BackgroundPatternColor, Word will change the .Texture from the default (wdTextureNone) to wdTextureSolid.

How to manage background and foreground colours

Based on these findings, the rules are:

If you want a background with a plain, solid colour

1. Set the .BackgroundPatternColor to the colour of your choice.
2. Ensure that the .Texture is wdTextureNone.
3. Ensure that the .ForegroundPatternColor is wdColorAutomatic.

If you want a pattern to display over the background color

1. Set the .BackgroundPatternColor to the colour of your choice.
2. Set the .Texture to something other than wdTextureNone.
3. Set the .ForegroundPatternColor.
    

This page describes my experiences with borders in table styles. Your mileage, as they say, may vary.

So what's the problem with borders and table styles?

For basics of controlling borders in styles, see Border basics for developers. The issues for table styles are the same as those for non-table styles:

• A .Borders property can have 1, 4, 5 or 8 borders, some of which you can control, and some of which you can't.
• Sometimes you can set the distance between the borders and the text, and sometimes you can't.
• Sometimes can you set a shadow on the borders, and sometimes you can't.

In addition, the built-in style Table Normal has its own rules, often different from the way any other table style, built-in or custom, behaves. In general, my experience is that it's best to leave style Table Normal alone. Avoid trying to read its properties, and if you do, litter your code with error catching. Certainly don't try to set the properties of Table Normal.

Summary

How borders behave for different elements of table styles

Style.Borders

The Word Style object has a .Borders property. It doesn't work for a table style, and returns error "That property is not available on that object".

Style.Table.Borders

This is the .Borders property of the table style's .Table. For example, ActiveDocument.Styles("MyTableStyle").Table.Borders.

There are 8 borders: top, right, bottom, left, horizontal, vertical and two diagonals.

Any border on the style's .Table will be overriden by, eg, Style.Table.Condition(n).Border(m). So, for example, if the first column condition has a left border, then you won't see the whole-of-table border. That makes sense, because the specific is over-riding the general. This applies whether the condition's border is set before or after the Style.Table.Borders border.

Top, right, bottom, left, horizontal and vertical borders

These borders generally work as expected.

Diagonal borders

Diagonal borders are basically uncontrollable:

• Diagonal borders always display as wdLineStyleSingle no matter what line style you set.
• You can't set a width on diagonal borders.
• Diagonal borders always show as black, regardless of what colour you set.
• You can't read the colour or width of a diagonal border. Both properties always return wdUndefined, even when the border is visible. Their default is wdUndefined, and they always report wdUndefined, so you can't rely on the reported value.

Setting distance from top (eg myStyle.Table.Borders.DistanceFromTop = 5) never works. It does not produce an error, but it makes no difference, either.

.Shadow = True never works. Word throws error 4198 'Command Failed'. And, when that happens, Word sets the first 6 borders (ie top, right, bottom, left, vertical and horizontal, but not diagonal) of the table to black, single line borders. So you can't just 'on error resume next' your way past the .Shadow setting, because it has unintended consequences.

Style.ParagraphFormat.Borders

This property controls the borders of text within a table cell.

A Table style has a .ParagraphFormat property, which has a .Borders property. For example ActiveDocument.Styles("MyTableStyle").ParagraphFormat.Borders.

There are 5 borders: top, right, bottom, left plus horizontal borders. If you set the top border, it appears only on the first paragraph in the table cell. If you want a border on the top of every paragraph, use the horizontal border, which displays between paragraphs. As far as I can see, you can't set the Horizontal borders in the user interface. You can only do it through code.

Notes:

• You may not be able to see the borders at all unless you type some more text in the document. Even a print preview does not force the borders to display.

• Generally, you can't see the top border if: (a) .Shadow = False and (b) the Style.Table.TopPadding = 5. Note that you may not be able to see the border in Print Layout view with other settings of .TopPadding, but you'll see the borders in Print Preview. But with .TopPadding = 5, you can't see the border in print preview, either. It may or may not print on paper. I've seen other settings for .TopPadding that also go wrong. So these borders are a bit flaky.

Distance from top (eg myTableStyle.ParagraphFormat.Borders.DistanceFromTop = 20) causes an error if the value is < 0 or >=31. Within that range, it does not appear to do anything.

.Shadow works, but expect some display artefacts that don't print.

Style.Font.Borders

In the object model this is Style.Font.Borders

There is only one border.

Trying to set the distance between border and text (eg myStyle.Font.Borders.DistanceFromTop = 10) never works. It always returns error 5891: "That property is not available on that object."

The .Shadow property works as expected.

Style.Table.Condition(n).Borders

In the object model, this is Style.Condition(n).Borders. A table style has 12 conditions (first column, last row, top right cell etc). myStyle.Condition(1) returns a ConditionalStyle object, and it has a .Borders property.

There are 8 borders: top, right, bottom, left, horizontal, vertical and two diagonals.

Top, right, bottom, left, horizontal and vertical borders

These work more-or-less as expected with three exceptions:

• The Distances between border and text do not cause an error if the value is >=0 and <32, but does not appear to do anything, either. They cause an error if value is <0 or >=32.

• You can't set the .Shadow property. If you try to access this property, Word throws error 4198 'Command failed'.

• Setting a border may have unintended consequences. For example, if the table in the document has been set to show the Total Row, Last Column and Banded Columns, and you set a border on the Top Row, then table will lose its Total Row, Last Column and Banded Column setting. So if you're going to set borders on a style in an existing document, you need to read these settings (for each table to which the style has been applied), store them, modify the style, apply it, then re-apply the individual table settings.

Diagonal borders

Diagonal borders are basically uncontrollable.

• Diagonal borders always display as wdLineStyleSingle regardless of what line style you set.
• You can't set a width on diagonal borders.
• Diagonal borders always show as black, regardless of what colour you set.
• You can't read the colour or width of a diagonal border. Both properties always return wdUndefined, even when the border is in plain sight. Their default is wdUndefined, and they always report wdUndefined, so you can't really manipulate diagonal borders in any way.

Style.Table.Condition(n).ParagraphFormat.Borders

In the object model this is Style.Condition(n).ParagraphFormat.Borders

There are 4 borders. Yes, 4. The Style.ParagraphFormat.Borders property has 5 borders, but Style.Condition(n).ParagraphFormat.Borders only has 4. I've no idea why.

Notes:

• These borders over-ride the Style.ParagraphFormat.Borders setting for the particular border. That makes sense to me, because the specific is over-riding the general.
• In early releases of Word 2007, the Top border wasn't visible unless the .Condition(n).TopPadding was at least 9. This is no longer a problem with Word 2007 Service Pack 2 and it works in Word 2010.
• In early releases of Word 2007, the Bottom border was unreliable unless the .Condition(n).BottomPadding was less than 9. This is no longer a problem with Word 2007 Service Pack 2 and it works in Word 2010.

The Distances between border and text do not cause an error if the value is >=0 and <32, but these properties do not appear to do anything, either. They cause an error if value is <0 or >=32.

The .Shadow works as expected.

Style.Table.Condition(n).Font.Borders

In Word 2003

Avoid this .Borders property.

We can't control these borders in code:

• These borders will be over-ridden by the Style.Font border. That doesn't make sense, because we would expect the specific to over-ride the general. Here, the reverse is true.
• You can set a .LineStyle, but Word will ignore your setting. If you interrogate the property, Word seems to report .LineStyle = 0 or .LineStyle = wdUndefined even when there is a line I can see.
• You can't ever set .LineWidth: Word throws an error every time.
• You can set a border .Color, but if you also set .Shadow to True, Word will ignore the colour and set the borders to Black, assuming no Style.Font.Borders settings.
• Borders whose .Color is undefined sometimes return the number −399507165 instead of 9999999 (the normal Word.wdUndefined constant). This number appears sporadically as the return value of a table style's .Table.Condition(x).Font.Borders(1).Color, but only if we're barging through the code, and not if we're using F8 to step through the code line by line. I have only seen it appear on some Conditions: last row, first column, last column, odd and even rows, even columns, top right cell and bottom right cell. I have not seen it appear on the other Conditions.
• Even if you do set the colour, and leave .Shadow = False, Word will not return the correct colour of the border.

These borders are badly behaved. For example, I used the user interface to set a border on the .Font of the first row (.Condition(0)). I could see the border. I then interrogated it in the Immediate pane in the VBE:

How can this happen?

? ActiveDocument.Styles("Shauna").Table.Condition(0).Font.Borders(1).LineStyle
0
Set brdr = ActiveDocument.Styles("Shauna").Table.Condition(0).Font.Borders(1)
? brdr.LineStyle
9999999

The display seems to come and go. The same code will sometimes display a border and sometimes not. That might just be a display or memory issue, but testing suggests otherwise. It may have something to do with the presence, or absence, of a border around the table as a whole, If the table has a border, you can't see the .Condition(x).Font.Borders.

Style.Table.Condition(0) (condition 0 is the top row) is flakier than the rest. You rarely see the effect of the border in the top row.

Distances between text and border (eg .DistanceFromTop = 5)  never works. You always get error 5891 'That property is not available on that object'.

In Word 2007 and Word 2010

Avoid this Borders property. It produces no borders, and will crash Word 2007 in a trice.

Setting the .Borders(1).LineStyle property or .Borders(1).Color property has no visible effect.

Setting the .LineWidth causes error 5843. In Word 2007, if you re-run the line of code with the error, Word may crash. To demonstrate, close and re-open Word, then run the following VBA code:

Sub HowToCrashWord2007()
Dim doc As Word.Document
Dim sty As Word.Style

    Set doc = Documents.Add
    Set sty = doc.Styles.Add(Name:="ATableStyle", Type:=wdStyleTypeTable)

    With sty.Table.Condition(wdLastRow).Font.Borders(1)

        On Error Resume Next
        .LineWidth = wdLineWidth025pt

        'Following line causes Word to crash
        .LineWidth = wdLineWidth025pt

    End With
End Sub

In the original version of Word 2007, setting the .Shadow caused no error. In Word 2007 with SP2, attempting to set the .Shadow property causes error 4198. There's a nice case for testing our code against service packs!

Finally, we cannot read the property values of these borders. .LineStyle and .LineWidth always return wdUndefined. .Colour always returns 0. And .Borders.Shadow always returns True even though there is patently no shadow since no border is displayed.

Related pages

• Border basics for Developers
• Borders in character and paragraph styles

Controlling page breaks in tables and table styles

Style.Table _
.AllowBreakAcrossPage controls page breaks within all rows.

Table.Rows(n) _
.AllowBreakAcrossPages controls page breaks within one or more rows.

Style.Table.AllowPageBreaks doesn't work.

.KeepWithNext sometimes keeps this paragraph on the same page as the next paragraph.

The Microsoft Word object model has four settings that control page breaks in tables and table styles:

• In a table style: .AllowBreakAcrossPage
• In a table: .AllowBreakAcrossPages
• In a table or table style: .AllowPageBreaks
• In a various places: .KeepWithNext

This page describes my observations about how these four settings work.

In a table style: prevent or allow page breaks within rows (.AllowBreakAcrossPage )

What it does

The .AllowBreakAcrossPage property applies to the Table of a table style. It controls the behaviour of individual rows, not the whole table. It determines whether the individual rows in a table may break across a page. But this is a property of the table style, not individual rows. So it applies to all rows in the table.

As far as I can see, there is no way to set this property from the user interface. You can only do it in code. However, in the user interface, you can override the setting for one individual row in a table to which this table style has been applied.

This is actually a very useful feature. In most tables I create, I don't want any rows to break across a page. Setting this property on the table style tells Word to do just what I want. And I can use the user interface to allow an individual row to break across a page if I need to.

As far as I can see, you can't use this property to define a table style such that some rows will break and others won't. But we can achieve the same thing using .KeepWithNext. See below.

Default value

If I create a new table style, I observe that rows break across the page. So it seems like the default for .AllowBreakAcrossPage is True. The documentation says that this property returns a Long (not a Boolean), and that the default value is True. That sounds right, but it isn't. In Word-land, True is -1. But a newly-created style returns a value of 1 (not -1) for this property.

Reading the property

For a newly-created style, the default value is 1. Here is some sample VBA code from the immediate window:

?ActiveDocument.Styles("MyTableStyle").Table.AllowBreakAcrossPage = True ' returns False
?ActiveDocument.Styles("MyTableStyle").Table.AllowBreakAcrossPage = False ' returns False

Subsequently interrogating the value of .AllowBreakAcrossPage is also tricky. If I set the value to .True, the return value is 1 (which is not what you'd expect), and Word denies that the value is .True. If I set the value to .False, the return value is 0 (which is kind of what you'd expect) and Word acknowledges that the value is .False.

Setting the property

This works quite reliably:

 ActiveDocument.Styles("MyTableStyle").Table.AllowBreakAcrossPage = True

How to use this property

• We can set the value reliably using True or False or 1 ("true") or 0 (False).
• To read the property value, we must assume that the only valid values are 1 (ie "true") and 0 (False).

As far as I can see, there is no way to set this property in the user interface.

In a table: prevent or allow page breaks within specified rows  (.AllowBreakAcrossPages)

What it does

This property applies to a real, live table. It does not apply to a table style.

Table.Rows.AllowBreakAcrossPages or Table.Rows(n).AllowBreakAcrossPages applies to an individual Row or all the .Rows of a table. It determines whether the row(s) may break across a page. This is the setting controlled in the user interface in the Table Properties dialog box, on the Row tab.

Setting the property

This property works quite reliably. For example:

ActiveDocument.Tables(1).Rows(2).AllowBreakAcrossPages = False

Note that individual rows retain the value of their .AllowBreakAcrossPages property, even if you change the underlying table style's .Table.AllowBreakAcrossPage property. 

Reading the property

This property reliably returns True or False, just as you'd expect.

In a table or a table style: keep the whole table on one page (.AllowPageBreaks)

This property does not work, and is effectively unusable.

What it does

This property applies to a table or a table style using Table.AllowPageBreaks or Style.Table.AllowPageBreaks.

It is supposed to work like this:

• If, given paper size, margins, fonts and so on, the whole table could fit on one page, and this property is True, then Word will pop the whole table over to the next page, and keep the whole table on one page.
• If the whole table could fit on one page, and this property is False, then Word will split the table across two pages, with rows breaking according to the .AllowBreakAcrossPage and .AllowBreakAcrossPages settings.
• If the table would not fit on one page, then Word will, not unreasonably, split the table across two or more pages regardless of the setting of .AllowPageBreaks.

As far as I can see, you can only set this property in code. There is no way to set this property from the user interface. For the classic workaround in the user interface, see Keeping a table together on one page.

Default value

Microsoft's object model documentation says that this is a Boolean. And indeed, if you query the property on a newly-created table style or table, Word will tell you that the value is True. But it isn't. The default value is actually 1, not True.

Setting the property

You can set the property in the normal way:

ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = True

But, this property doesn't work. That is, the table will not be kept on one page.

• In Word 2003, it will appear to work, but once you save the file and re-open it, it stops working.
• In Word 2007, it does not appear to do anything.
• In Word 2010, it does not appear to do anything. In Word 2010, Microsoft's object model help says that the AllowPageBreaks property is 'Hidden' and that 'Hidden' means "The member has been deprecated and is not recommended for use in code."

Reading the property

If you set the value to True, Word will then deny that you have so set it. The following, from the Immediate pane in the VBE, is clearly crazy:

ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = True
?ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks
True
?ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = True
False

When Word reports that the value is True, the value is actually 1.

If you set the value to False, then Word behaves rather better:

ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = False
?ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks
False
?ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = False
True

How to use this property, given the bugs

We can't use this property because it doesn't work.

.KeepWithNext

"Keep with next" means "keep this paragraph on the same page as the next paragraph".

The .KeepWithNext property applies to the .Paragraphs collection, a .Paragraph object and the .ParagraphFormat object.

Thus, it can be applied to one or more real paragraphs (using the .Paragraphs collection or a .Paragraph object) or to a paragraph or table style (using the style's .ParagraphFormat property).

.KeepWithNext is used extensively in defining paragraph styles. By default, the heading styles have .KeepWithNext = True so as to prevent a heading at the bottom of the page, and its subsequent text at the top of the following page.

In tables, .KeepWithNext works a little differently. If any paragraph in a row of a table is marked KeepWithNext = True, then that row will always appear on the same page as the first paragraph in the following row. If that following row is marked so as not to break across a page, then the KeepWithNext setting has the effect of keeping that row on the same page as the whole of the following row.

In theory, we can set a table style's .ParagraphFormat to KeepWithNext. For example:

ActiveDocument.Styles("MyTableStyle").ParagraphFormat.KeepWithNext = True

But I can't see any effect of doing this. It doesn't seem to work at all.

But .KeepWithNext does have interesting, if inconsistent, effects when applied to just part of a table style using one of the style's .Conditions.

sty.Table.Condition(wdFirstRow) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdLastRow) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdFirstColumn) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdNWCell) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdNECell) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdSWCell) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdSECell) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdEvenRowBanding) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdEvenColumnBanding) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdOddRowBanding) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdOddColumnBanding) _
.ParagraphFormat.KeepWithNext = True

Word styles cascade. Out of the box, a few styles have no parent, but most are based on another style. In the object model, this is controlled through the .BaseStyle property.

One of the rules is that a style can only be based on another style of the same type. So, a Character style can only be based on another Character style. A Table style can only be based on another Table style. And so on.

Interrogating the .BaseStyle of a Style routinely returns nonsense. Open a document and try something like this:

Sub TestBaseStyles()

Dim sty As Word.Style

    For Each sty In ActiveDocument.Styles
        'In a clean document, this produces nonsense
        Debug.Print sty.NameLocal, sty.BaseStyle
    Next sty

End Sub

Unless your Style object has been 'primed' in some way, reading the .BaseStyle property produces unmitigated nonsense:

• Word 2003 reports that most styles are based on Normal style. Clearly character styles, table styles and list styles can't be based on Normal, since it's a paragraph style.
• Word 2007 and Word 2010 seem to report a random style as the .BaseStyle. Table styles might tell you they're based on character styles. Character styles might tell you they're based on paragraph styles.

Workaround

The best way I've found to work around this is to read the .Description property before reading the .BaseStyle property. This somehow 'primes' the Style object and thereafter it will report the .BaseStyle accurately.

So something like this works perfectly well:

Sub TestBaseStyles()

Dim sty As Word.Style

    For Each sty In ActiveDocument.Styles
        Debug.Print sty.NameLocal, sty.Description, sty.BaseStyle
    Next sty

End Sub

You don't have to output the .Description in any way. Just reading it and assigning to a variable will do. Something like this:

Sub DoSomethingWithMyStyle()

Dim sty As Word.Style
Dim sDescription as String

    For Each sty In ActiveDocument.Styles
        '"Prime" the style
        sDescription = sty.Description

        'Now we can read the .BaseStyle
        MsgBox sty.BaseStyle
    Next sty

End Sub

There are some other properties of a style that will coerce a style into reporting the correct .BaseStyle. That's why this problem does not appear very often: your code may already have read one of the properties that settle the style down. Reading the .Linked property of a paragraph style, for example, is enough to force Word to report the .BaseStyle accurately.

The advantage of using the .Description property is that it appears to be innocuous and applies to every style type, so it's easy to get into the habit of reading the .Description before reading the .BaseStyle.

I can't find any reference from Microsoft to the cause of error 5848 "The style definition is empty.".

But I can identify at least one way in which this error occurs. This only seems to go wrong in Word 2010, both RTM and SP-1.

The Style object in Word has an old, deprecated, property named .Hidden. You can only see it in the Object Browser in the Word VBE if you choose to 'Show Hidden Members'.

Reading the .Hidden property causes no problems.

Setting the .Hidden property to True or False has no effect on the visibility of the style in question.

But setting the .Hidden property of any style to True causes Word to create a new, fake, half-broken duplicate Normal style in your document.

This code, for example. will create a half-baked duplicate Normal style:

'Do not use this! This creates a broken duplicate Normal style in your document.

ActiveDocument.Styles(wdStyleBodyText).Hidden = True

When is this likely to be a problem?

A half-baked duplicate Normal style is likely to be a problem if you want to cycle though all styles in your document.

You can read some properties of the problem-child Normal style:

• .NameLocal
• .Description
• .Font
• .Frame
• .Shading
• .Table

If you attempt to read any other property of this problem Normal style, Word throws error 5848 "The style definition is empty".

How to avoid the problem

Don't apply the .Hidden property to any style, ever.

How to get around the problem

If you're cycling through all the styles in a document, it may be wise to include some error trapping in case you run into a document with this problem.

If you need to access the real Normal style, and don't want to risk referring to the problem child, do so using Word's built-in enumerated constant (which is good practice anyway).

So, use this:

'This is safe
ActiveDocument.Styles(wdStyleNormal)

not this:

'This might not be safe
ActiveDocument.Styles("Normal")

How to get rid of the offending "Normal" style

I can't find a way to get rid of the half-baked problem child in the user interface. I can only find it listed in the Manage Styles dialog (Figure 1). If I try to delete the style from there, Word does nothing. Apparently Word can't distinguish between the real "Normal" and the fake "Normal".

It seems that the only way to get rid of this style is in code. Word is so protective of the real "Normal" style that we have to re-name the fake to delete it. Something like this seems to work:

Sub DeleteDuplicateNormalStyle()

Dim sty As Word.Style
Dim nCounter As Long
Dim eStyleType As Word.WdStyleType

    For Each sty In ActiveDocument.Styles
        If sty.NameLocal = "Normal" Then

            On Error Resume Next
            eStyleType = sty.Type

            If Err.Number = 5848 Then
                sty.NameLocal = "DuplicateNormal"
                sty.Delete
                Exit For
            End If
        End If

    Next sty

End Sub

A Table style in Word has a .Table.Condition method that returns a ConditionalStyle object. The ConditionalStyle objects refer to different elements of the table: top row, left column, bottom right-hand cell, and so on. There are 12 ConditionalStyle objects in each table style.

If you try to access one of these ConditionalStyle objects, some of the time Word will throw error 5825 'Object has been deleted", even though, plainly, every table style has exactly 12 ConditionalStyle objects, and you can't delete one even if you tried.

What causes this error

You might, for example, assign a table style to a Style variable, and then attempt to access the First Row condition, like this:

Dim sty As Word.Style
Dim cond As Word.ConditionalStyle

    Set sty = ActiveDocument.Styles(wdStyleTableColorfulGrid)
    Set cond = sty.Table.Condition(wdFirstRow)

If you run this code on a new document, Word will throw error 5825 'Object has been deleted'.

The problem seems to be that a table style isn't really ready for use until it's used in some particular ways. Once you have "primed" the style, it will then work fine. That's why the error is so difficult to track down: your code errors out the first time, but runs just fine every other time. Or, the same code will work in some circumstances but not others.

Workaround

The best way I've found to work around this is to read the .Description property before using the .Condition method of a table style's .Table. This somehow 'primes' the Style object and thereafter it will allow you to access the .Condition method.

You don't have to output the .Description in any way. Just reading it and assigning to a variable will do. So this code will run without error:

Dim sty As Word.Style
Dim cond As Word.ConditionalStyle
Dim sPrimeTheStyleObject As String

    Set sty = ActiveDocument.Styles(wdStyleTableColorfulGrid)
    sPrimeTheStyleObject = sty.Description
    Set cond = sty.Table.Condition(wdFirstRow)

The advantage of using the .Description property is that it appears to be innocuous and applies to every style type, so it's easy to get into the habit of reading the .Description before using the .Condition method.

Related pages

Word reports the .BaseStyle of styles inaccurately  (the .BaseStyle property of a style doesn't work until it is "primed", either)

Shading in table styles: what works?

To apply background shading in table styles, apply the shading to a table style's .Table.Condition.

No other shading works reliably.

This page is for developers. It's about table styles (not about an individual table in a document).

For table shading information for users see Table cell shading.

There are 7 ways to set shading (ie background colour) on all or part of a table style using the Word object model. Microsoft has not documented how this is supposed to work. My experience is that, of the 7, two work, more or less, and five don't. This page describes my experience with setting shading in a table style.

Shading the style: Doesn't work

The object model provides, for example, ActiveDocument.Styles("MyTableStyle").Shading.

As far as I can see, this .Shading object does not work for Table styles.

For character styles and paragraph styles, you can set the shading directly on the style object. If you try this with a table style, Word throws error 5891 'That property is not available on that object'.

Shading the style's .Table: Works a little bit

To apply shading to the .Table of a table style, this works for any colour:

ActiveDocument.Styles("MyTableStyle").Table.Shading.BackgroundPatternColor = wdColorAqua

But, there are bugs:

• Shading the whole table does not work for the built-in style Table Normal. If you attempt to modify Table Normal, Word throws error 4198 'Command failed'.
• The three crucial properties of the .Shading object (.BackgroundPatternColor, .Texture and .ForegroundPatternColor) are effectively write-only. No matter what you set:
  • .ForegroundPatternColor returns wdColorAutomatic
  • .BackgroundPatternColor returns wdColorAutomatic
  • .Texture returns wdTextureNone.
• You can't set a .ForegroundPatternColor or a .Texture. You are limited to a single, solid colour. If you set the .ForegroundPatternColor as well as the .BackGroundPatternColor, then Word will ignore the .Texture property and display the table style with the .ForegroundPatternColor as shading.

Shading parts of the table: This works

You can successfully apply shading to part of the table of a table style. For example, in VBA, the following works for any .Condition, for any colour and any texture:

With ActiveDocument.Styles("MyTableStyle").Table.Condition(wdFirstRow).Shading
   .BackgroundPatternColor = wdColorBlue
   .ForegroundPatternColor = wdColorRed
   .Texture = wdTexture15Percent
End With

Word accurately returns the values for the colours and texture. 

In terms of shading, this is the only part of the table style object model that simply works.

Does not work: Style.ParagraphFormat.Shading.BackgroundPatternColor or Style.Font.Shading.BackgroundPatternColor

The following don't work, for any style or for any colour:

ActiveDocument.Styles("MyTableStyle").ParagraphFormat.Shading.BackgroundPatternColor = wdColorRed

ActiveDocument.Styles("MyTableStyle").Font.Shading.BackgroundPatternColor = wdColorRed

What Word does if you set the .BackgroundPatternColor

In Word 2003, in both cases, Word applies white shading. You won't see that unless the cell already has a visible coloured shading against which to see the white. Further, if you happen to have white text, you now won't be able to see the text since it's sitting on top of white shading.

In Word 2007, in both cases, Word ignores the command. The UI shows that the condition's fill is 'No color'.

What Word tells you it does if you set the .BackgroundPatternColor

In both cases, in Word 2003 and Word 2007, Word returns the wrong value. That is, if you set the colour to, eg, wdColorRed, Word will tell you that the shading is red, but you can't see any red shading: what you see is white shading (in Word 2003) or no shading (in Word 2007). There is no workaround for this, so we cannot read this property.

Does not work: Style.Table.Condition(n).ParagraphFormat.Shading.BackgroundPatternColor

The following doesn't work, for any style, for any .Condition or for any colour:

ActiveDocument.Styles("MyTableStyle").Table.Condition(wdFirstRow).ParagraphFormat.Shading.BackgroundPatternColor = wdColorRed

What Word does if you set the .BackgroundPatternColor

In Word 2003, Word applies white shading. You won't see that unless the cell already has a visible coloured shading against which to see the white. Further, if you happen to have white text, you now won't be able to see the text since it's sitting on top of white shading.

In Word 2007, Word ignores the command. The UI shows that the condition's fill is 'No color'.

What Word tells you it does if you set the .BackgroundPatternColor

In both cases, in Word 2003 and Word 2007, Word returns the wrong value, and there is no workaround for this. So we can't read this property.

If you set the colour to, eg, wdColorRed, you won't be able to see any red shading: what you see is white shading (in Word 2003) or no shading (in Word 2007). If you ask Word what color is applied, the answer is wdColorRed (ie 255). If you ask Word if the color applied is red, then the answer is True. It's wrong, but at least it's consistent. The following VBA code demonstrates:

Sub TestTableConditionParagraphFormatShading()

Dim sty As Word.Style

Set sty = ActiveDocument.Styles.Add(Name:="Shauna", Type:=wdStyleTypeTable)

With sty.Table.Condition(wdFirstRow).ParagraphFormat.Shading
    'Set the first row's ParagraphFormat shading colour to red
    .BackgroundPatternColor = wdColorRed

    'Ask Word what colour is the shading colour
    Debug.Print .BackgroundPatternColor
    '255

    'Ask Word whether the colour is red
    Debug.Print .BackgroundPatternColor = wdColorRed
    'True
End With

End Sub

Does not work: Style.Table.Condition(n).Font.Shading.BackgroundPatternColor

The following is barely usable:

ActiveDocument.Styles("MyTableStyle").Table.Condition(wdFirstRow).Font.Shading.BackgroundPatternColor = wdColorRed

What Word does if you set the .BackgroundPatternColor

In Word 2003, Word does not apply the shading you specify. It applies white shading. You won't see that unless the cell already has a visible coloured shading against which to see the white. Further, if you happen to have white text, you now won't be able to see the text since it's sitting on top of white shading.

In Word 2007 as it was first shipped, Word ignores the command. The UI showed that the condition's fill is 'No color'. With Service Pack 2, Word 2007 applies the shading correctly. Word 2010 applies the shading correctly.

What Word tells you it does if you set the .BackgroundPatternColor

Word 2003, Word 2007 and Word 2010 all return the wrong value. So we cannot read this property in code.

In Word 2003, if you set the colour to, eg, wdColorRed, you won't be able to see any red shading. What you see is white shading. So I would expect that Word would tell me there was white shading. But no. Word will tell you that the shading is wdUndefined.

In Word 2007 with no service packs, if you set the colour to, eg, wdColorRed, you won't see any shading. Word will tell you that the shading is wdUndefined.

In Word 2007 with Service Pack 2 and in Word 2010, if you set the colour to, eg, wdColorRed, you will see red shading. But if I set the colour to red, and then ask Word 2007 or Word 2010 if the color applied is red, then the answer is False. Here's an example in VBA:

Sub TestTableConditionFontShading()

Dim sty As Word.Style

Set sty = ActiveDocument.Styles.Add(Name:="Shauna", Type:=wdStyleTypeTable)

With sty.Table.Condition(wdFirstRow).Font.Shading
    'Set the first row's Font shading colour to red
    .BackgroundPatternColor = wdColorRed

    'Ask Word what colour is the shading colour
    Debug.Print .BackgroundPatternColor ' Returns 9999999

    'Ask Word whether the colour is red
    Debug.Print .BackgroundPatternColor = wdColorRed  ' Returns False
End With

End Sub

In Word 2007 and Word 2010, when you click within a table, two Table Tools contextual tabs become available on the Ribbon.

The Design tab includes the Table Styles group. This gives you, out of the box, 99 table styles from which to choose.

Having applied one of the 99 styles, the user can then choose whether or not to show banded columns, banded rows, header or total rows and so on.

In a corporate environment, the communications people would tear their hair out if users formatted tables in 99 different ways. A corporate environment is likely to have 2 or 3 'approved' ways to format a table.

The solution: hide most, if not all, of the built-in table styles

Well-constructed templates for corporate use are likely to have 2 or 3 custom table styles that fit the corporate branding. Or, the in-house rules may be that 2 or 3 of the built-in styles are to be used, but the rest are off limits.

There is no way in the user interface to hide the built-in table styles.

But you can do it in code. Something like this will do the trick:

Sub HideATableStyle()

    With ActiveDocument.Styles(Word.wdStyleTableLightShading)
        .Visibility = True ' Yes, True.
        .UnhideWhenUsed = False
    End With

End Sub

If you're creating a template for corporate use, it may be appropriate to hide most of the built-in table styles in the template. Leave the approved custom or built-in table styles visible. Users can then easily apply the corporate-approved table styles when working on documents based on that template.

But… there is a disadvantage to this method. If the user copies a table from another document, and that table has your hidden style applied to it, then the user cannot see what style has been applied to the table. To avoid that, use something like this:

Sub HideATableStyleButMakeItVisibleWhenUsed()

    With ActiveDocument.Styles(Word.wdStyleTableLightShading)
        .Visibility = True ' Yes, True.
        .UnhideWhenUsed = True
    End With

End Sub

1. The frame is visible: when you click in a paragraph of that style, you can see the frame boundaries.
2. The frame is functional: content will wrap around the paragraph according to the settings of the frame.

It's not so obvious in the Word object model.

The object model gives us a .Delete method to remove a frame. For example:

ActiveDocument.Styles("MyStyle").Frame.Delete

But there is no way to add a frame to a style. The .Frame property returns a Frame object whether or not the style has a frame that is visible in the user interface. From the point of view of the object model, a frame is present for all paragraph styles.

There is no obvious way to detect the presence of a Frame as the user experiences it. That is, if I want to know whether the frame for a style is visible and functional, there is nothing in the object model that tells me.

However, testing suggests that testing the .Width and .Height properties of a style's Frame give us a proxy for identifying the presence of a frame.

If the .Width and .Height of the frame equal -1, then the frame is not visible and not functional. You cannot set the .Width or .Height to -1 (you get a message saying that the measure must be between 0.5pt and 1584pt). It seems that the only way that .Width and .Height come to be -1 is if there is no visible, functional frame.

Microsoft has not documented the use of .Width and .Height as a proxy to detect whether a paragraph style has a frame. I discovered it by testing, and it has been reliable for me. YMMV, as they say.

Follow up:  One person says that this method does not work for him, but Cindy Meister provides an alternative solution: http://social.msdn.microsoft.com/Forums/en-US/worddev/thread/6a06f149-94a2-4fa0-8026-738b1c315261/