Shading (ie background colour) in table styles

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