Background and foreground: Shading in paragraph styles

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.