4.5.5 Borders and shading | Microsoft Office Automation with Visual FoxPro

Borders and shading

Word allows you to put borders around and shading behind various parts of a document to set them off from the rest of the document. You can put borders around or shade pretty much anything, from a single character to an entire page. Border styles vary from simple lines to complex patterns and from a half-point to six points. A border can be applied on any or all sides of the text. Shading can be any color and can run the gamut from just a plain color to a patterned fill. Interactively, it s all controlled from the Borders and Shading dialog on the Format menu.

In Automation, two objects run the show. Not surprisingly, they re called Borders and Shading. Borders is a collection of Border objects.

Creating borders

Setting up borders interactively can be tricky. It s often hard to get the border where you actually want it. That s because the Borders collection can belong to different objects, and the object to which it belongs determines where the border actually appears. Table 7 lists some of the objects that can hold a Borders collection and the interpretation of the collection in that case.

Table 7. Almost anything can have borders. The interpretation and size of the Borders collection depends on what object it belongs to.

Object	Meaning of Borders
Section	Sets a Page Border for that section of the document.
Paragraphs collection	Sets borders around the group of paragraphs in the collection.
Paragraph	Sets borders for that paragraph.
Range	Sets borders for that range. When the range crosses paragraph boundaries or there s a break of some sort, such as a hard page break or a section break within the range, the range is expanded to include the complete paragraphs at each end. The border is applied to that expanded range, which is treated like a Paragraphs collection.
Table	Sets borders for the outside of the table and for the gridlines inside the table.
Rows collection	Sets borders for the rows in the collection. Applies only to the outside borders of the collection, not to the borders for each row in the collection.
Columns collection	Sets borders for the columns in the collection. Applies only to the outside borders of the collection, not to the borders for each column in the collection.
Row	Sets borders for the specified row.
Column	Sets borders for the specified column.
Cells collection	Sets borders for the cells in the specified collection. This approach works much better than using either Rows or Columns. Be sure to specify top or bottom borders when accessing Cells through a Row, and left or right borders when accessing Cells through a Column. While the others work, they re not very productive.
Cell	Sets borders for a specified cell, indicated by both row and column. This approach is also effective.
Style	Sets borders for a style.

A number of other objects reference Borders collections as well, but they re pretty esoteric.

The Borders collection contains a lot more information than most. Also, unlike most collections, you can t add members freely. The number of Border objects it contains is determined by the kind of object it belongs to. Most of the time, there are four members, accessed using these constants: wdBorderTop (-1), wdBorderLeft (-2), wdBorderBottom (-3), and wdBorderRight (-4). For some objects, including tables, the collection has additional members. The constants are: wdBorderHorizontal (-5), wdBorderVertical (-6), wdBorderDiagonalDown (-7), and wdBorderDiagonalUp (-8).

In addition to the individual Border objects, the collection has a number of other properties. Table 8 contains a sampling of them.

Table 8. Borders collection properties. While most collections have few properties, Borders is particularly rich in them.

Property	Type	Description
Count	Numeric	The number of Border objects in this collection.
InsideLineStyle	Numeric	The type of line used for the inside of a table. Can be overridden by setting borders for the individual rows, columns, or cells. Uses the constants shown for LineStyle in Table 9.
InsideLineWidth	Numeric	The size of the lines used for the inside of a table. Can be overridden by setting borders for the individual rows, columns, or cells. Uses the constants shown for LineWidth in Table 9.
OutsideLineStyle	Numeric	The type of line used for the outside border of the specified object. Uses the constants shown for LineStyle in Table 9.
OutsideLineWidth	Numeric	The size of the lines used for the outside border of the specified object. Uses the constants shown for LineWidth in Table 9.
Enable	Logical	Indicates whether or not borders should be enabled for the specified object. Setting this property to .F. turns off borders for the object.

A variety of other properties determine how far from the specified object the borders appear.

At long last, we reach the actual Border object, which describes the characteristics of a single border. Table 9 shows its key properties.

This code creates a document and puts a page border of hot air balloons on it. Figure 8 shows the result (substantially reduced in size).

#DEFINE wdArtBalloonsHotAir 12

#DEFINE wdBorderTop -1

#DEFINE wdBorderBottom -2

#DEFINE wdBorderLeft -3

#DEFINE wdBorderRight -4

oDocument = oWord.Documents.Add()

WITH oDocument.Sections[1]

.Borders[ wdBorderTop ].ArtStyle = wdArtBalloonsHotAir

.Borders[ wdBorderBottom ].ArtStyle = wdArtBalloonsHotAir

.Borders[ wdBorderLeft ].ArtStyle = wdArtBalloonsHotAir

.Borders[ wdBorderRight ].ArtStyle = wdArtBalloonsHotAir

ENDWITH
Table 9. What s in a border? These properties describe a single border.

Property	Type	Description
LineStyle	Numeric	The type of line used for the border. For example: wdLineStyleNone 0 wdLineStyleDashDot 5 wdLineStyleSingle 1 wdLineStyleDouble 7 wdLineStyleDot 2 wdLineStyleSingleWavy 18
LineWidth	Numeric	The size of the line used for the border. You cannot set the point size for the line, but rather must use the constant value for a predefined size. Check the Object Browser for more choices. wdLineWidth025pt 2 0.25 points wdLineWidth050pt 4 0.5 points wdLineWidth075pt 6 0.75 points wdLineWidth100pt 8 1 point wdLineWidth150pt 10 1.5 points wdLineWidth225pt 18 2.25 points wdLineWidth300pt 24 3 points wdLineWidth450pt 36 4.5 points wdLineWidth600pt 48 6 points wdUndefined 9999999 Undefined
ColorIndex, Color	Numeric	The color for the line used for the border. Word offers two sets of colors. Use ColorIndex to specify a value from a short list, using the wdColorIndex constants, or use Color for a full list of RGB values, which can be passed either with VFP s RGB() function, as an actual numeric value, or by using the wdColor constants. Either property is acceptable. ColorIndex is quick and easy, but Color gives you more choices. Note that Color is new in Word 2000.
ArtStyle	Numeric	The graphic to use for a page border. More than 150 are available. Shades of PrintShop. Here s a sampling: wdArtApples 1 wdArtMusicNotes 79 wdArtBalloonsHotAir 12 wdArtPaperClips 82 wdArtBasicBlackDots 156 wdArtPencils 25
ArtWidth	Numeric	The width of the page border, in points.
Inside	Logical	Indicates whether the bordered object should have an inside border, if it supports one.

Figure 8. Page border. The Borders collection lets you add borders to various objects. Its interpretation changes with the object.
Shading text

After the complexities of borders, the good news is that shading is far easier. There s only one object involved, and it has only a handful of properties.

Like borders, shading can be applied at a number of levels. Many objects have a Shading property that references a Shading object. All the objects listed in Table 7 support shading except for Section, which makes sense because Section s Borders collection is really about page borders, something different than the rest.

Once you know what you want to shade, there are only three components involved in specifying shading: the background color, the foreground color, and the texture. Better yet, you can often omit the last two of these. The background color is just what it sounds like the color to put behind the text. For most printed documents, you ll usually want some variant of gray. You can specify it with either BackgroundPatternColor or BackgroundPatternColorIndex. The difference is that BackgroundPatternColor expects an RGB value, while the longer-named property takes its value from a list of 18 predefined colors (you can look them up in the Object Browser under wdColorIndex). To specify light gray shading, try:

oRange.Shading.BackgroundPatternColor = RGB(230,230,230)

ForegroundPatternColor and ForegroundPatternColorIndex lay another color over the background color. Doing this doesn t make much sense if you don t specify a value for Texture. It s just an alternate way of specifying the shading color (or a complex way of mixing colors).

BackgroundPatternColor and ForegroundPatternColor are new in Word 2000. In Word 97, you have to use the Index versions of the two properties and are limited to the list of predefined colors they provide.

However, Word can do much better tricks. The shading can be muted from full strength down to as low as 5 percent, with nearly 40 total steps offered. In addition, about a dozen other fill patterns are available for shading. In that case, the two colors are used as their names indicate. Table 10 shows some of the constants available for the Texture property.

Table 10. Textured shading. Word offers a variety of textures that allow shading to be more than just background.

Constant	Value	Constant	Value
wdTextureNone	0	wdTextureCross	-11
wdTextureSolid	1000	wdTextureDarkCross	-5
wdTexture5Percent	50	wdTextureHorizontal	-7
wdTexture10Percent	100	wdTextureVertical	-8
wdTexture12Pt5Percent	125	wdTextureDiagonalCross	-12
wdTexture30Percent	300	wdTextureDiagonalUp	-10
wdTexture75Percent	750	wdTextureDiagonalDown	-9

This example sets up a diagonal crosshatch of orange on teal:

#DEFINE wdTextureDiagonalCross -12

WITH oRange.Shading

.Texture = wdTextureDiagonalCross

.BackgroundPatternColor = RGB(0,192,255)

.ForegroundPatternColor = RGB(255,128,0)

ENDWITH