Border basics for developers

Microsoft's documentation of borders in styles in the VBA help files is poor. This page seeks to describe my experience with setting and controlling borders in styles. Your mileage may vary.

Setting individual borders

How many borders?

Lots of objects in the Word object model have borders. But not all objects have the same number of borders. For example:

• a Font object has 1 border (in the user interface this is described as a border on the "Text")
• a paragraph has 5 (top, right, bottom, left plus horizontal)
• a table cell has 8 (4 outside borders, vertical and horizontal plus two diagonals).

Setting the LineStyle, LineWidth and Color for each border

With some exceptions due to what I consider to be bugs, you can control a single border using its three three main properties:

• .LineStyle (eg plain or dotted)
• .LineWidth
• .Color

If .LineStyle is wdLineStyleNone, then you can't set the .LineWidth, or you get an error. Therefore, if you want a border, you must set the .LineStyle you want before setting the .LineWidth.

You must set the .LineStyle before setting the .Color, or Word will ignore the colour.

So in general, set the properties in the order shown above: .LineStyle, then, only if you need them, .LineWidth and .Color .

Not every line style is available in every width. You can see in the user interface that, for example, a wavy line is only available in 0.75pt or 1.5pt, and a double wavy line only available in 0.75pt. There does not appear to be any way to determine valid combinations of .LineStyle and .LineWidth from the object model. If you choose a line width that is incompatible with your line style, you'll get an error.

Using .Border(n).Visible

The .Visible property applies to an individual border, for example:

ActiveDocument.Styles("MyParagraphStyle").Borders(wdBorderBottom).Visible = True

The .Visible property does not have much to offer a developer.

Setting .Visible to False is the same as setting .LineStyle to wdLineStyleNone. And vice versa: if you set .LineStyle to wdLineStyleNone, .Visible will return False.

If I set .Visible to True, Word applies a border, but the border style, width and colour that Word applies are at least partly random. I think that Word applies the border width from the current default border width (ie the width that shows when you display the Borders and Shading dialog), but always applies a black, wdLineStyleSingle border. The control freak in me can't cope with that, so I never use .Visible = True.

The .Visible property will reliably tell you whether a border is visible. So

Debug.Print ActiveDocument.Styles("MyParagraphStyle").Borders(wdBorderBottom).Visible

is equivalent to

Debug.Print ActiveDocument.Styles("MyParagraphStyle").Borders(wdBorderBottom).LineStyle <> wdLineStyleNone

Setting several borders at once

Using .Borders.Enable

Removing borders using .Borders.Enable

Perhaps the simplest way to delete all borders from an object is to use .Borders.Enable method. For example, in VBA code:

• Selection.Borders.Enable = False
• ActiveDocument.Styles("My style name").Borders.Enable = False
• ActiveDocument.Tables(1).Borders.Enable = False
• Selection.Cells(1).Borders.Enable = False

Note, however, that .Borders.Enable = False will not remove diagonal borders from a table or a table style.

Setting borders using .Borders.Enable

I do not recommend using .Borders.Enable to create a border. That is because .Enable = True applies whatever line style, width and colour were last used in the Borders and Shading dialog box. So as a developer, we have no idea what settings might currently exist in that dialog box. And therefore, we cannot predict what .Enable = True will do.

Reading the value of .Borders.Enable

The .Enable method returns:

• False if the object has no visible borders
• True if the object has borders that have the same line style and line width as the current default border properties (that is, the line style and line width that Word displays when you open the Borders and Shading dialog box)
• wdUndefined (9999999) in any other circumstance. So:
  • if the borders are all the same, Word will return wdUndefined if the borders have a line style and/or line width different from the current default border properties (that is, the line style and line width that Word displays when you open the Borders and Shading dialog box)
  • if the borders have different widths or colours (for example, you have a top border only; or if the top border is red, and the left border is blue), .Borders.Enable will equal wdUndefined.

You can't rely on the return value for much that's useful. But it's not necessary to read the .Enable property. That is because, when you set .Borders.Enable = True, Word changes the .LineStyle, .LineWidth and .Color of each individual border. So, with significant exceptions for table styles, you can read the properties for each individual border.

Using Borders.OutsideLineStyle, .OutsideLineWidth and .OutsideColor

The 'outside' borders are the top, right, bottom and left borders of an object. These methods affect all four of the outside borders. You can reliably set borders using these methods, as long as you follow the same rules as for setting individual borders:

• set the .OutsideLineStyle
• if the .OutsideLineStyle is not wdLineStyleNone then
  • set the .OutsideLineWidth
  • set the .OutsideColor
• not all line widths are available for all line styles, and there's no way to determine in the object model what line widths are available for a specified line style.

You can reliably read these 'outside' border properties.

Using Borders.InsideLineStyle, .InsideLineWidth and .InsideColor

The 'inside' borders are the vertical and horizontal borders of an object. The inside borders are most useful in tables, to control the cell borders within the table. A paragraph, a paragraph style and some .ParagraphFormat objects also have a horizontal (but not vertical border). See Borders in character and paragraph styles for more information.

You can reliably set borders using these methods, as long as you follow the same rules as for setting individual borders:

• set the .InsideLineStyle
• if the .InsideLineStyle is not wdLineStyleNone then
  • set the .InsideLineWidth
  • set the .InsideColor
• not all line widths are available for all line styles, and there's no way to determine in the object model what line widths are available for a specified line style.

You can reliably read these 'inside' border properties.

Issues in setting borders in styles

Not all .Borders properties are equal. Depending on the style type and where you are in the object model, some .Borders properties have one border, but some have 4, or 5, or 8 borders. In some you can set the distance between the border and text, in others you can't. In some .Borders.Shadow will give you a shadow. Sometimes it gives you an error. Sometimes it does nothing.

How borders behave for different elements in the Word object model

• Borders in character and paragraph styles
• Borders in table styles
• Page (that is, section) borders