5.5 Adding graphics to documents | Microsoft Office Automation with Visual FoxPro

Adding graphics to documents

They say a picture s worth a thousand words. Certainly a document with pictures is a lot more pleasant to look at and easier to read than one without. Word provides several ways to add graphical objects to documents. All of them begin by choosing Insert|Picture from the menu. At that point, the next step depends on the type of graphical object you want to add.

Let s start with graphics that you have sitting in a file somewhere, such as a BMP or JPG or GIF. For those, you choose From File, and the Insert Picture dialog shown in Figure 9 appears. This dialog is a specialized version of the normal Open File dialog. The Open button is labeled "Insert," and if you drop it open, there are a couple of extra choices. These options hark back to the traditional meaning of OLE object linking and embedding. Choosing Insert makes a copy of the picture in the document with no connection back to the original file; that is, it embeds the picture in the document. Link to File creates a connection between the picture file and the document; that is, it links the picture to the document changes to the picture are reflected in the document. Insert and Link does both it embeds the picture in the document, but also maintains a link to the file so that the document is updated by changes to the picture file. Each of these options has its place choose the right one for your situation, based on factors such as whether you expect the picture to change, whether you want changes in the picture to be reflected in your document, the size of the picture file, whether users can be trusted not to delete the picture, and so forth.

Figure 9. Adding pictures. Graphics can be linked, embedded, or both. When a picture is linked, changes to the graphic file are reflected in the document.

The list of graphical objects you can add also includes various kinds of drawings, like AutoShapes and WordArt. To add an AutoShape to your document, choose Insert|Picture|AutoShapes from the menu. This opens the AutoShapes toolbar (shown in Figure 10). When you click on one of the buttons, a menu of shapes of that type appears (see Figure 11). Choose one, and Word switches to Page Layout view if necessary and puts the chosen shape wherever you click. The AutoShapes toolbar stays open so you can add as many shapes as you want.

Figure 10. The AutoShapes toolbar. This toolbar appears whenever you choose Insert|Picture|AutoShapes from the menu.

Figure 11. Choosing an AutoShape. The items on the AutoShapes toolbar look like buttons, but each opens a menu of shape items.

Each of the other kinds of graphic objects has its own approach. None of them are really native to Word; they all call on other applications (such as Microsoft Clip Gallery and Microsoft Graph) to supply the data to be displayed.

The two faces of graphics

Graphics in Word can be placed on two different layers of the document. Pictures that come from files normally live on the same layer as the text in the document. AutoShapes and other drawing objects are positioned as free-floating objects on a separate layer above the text. This means that they can cover the text and graphics in the main layer. Two different collections are used to manage the two types of graphic objects. Objects in the text layer are stored in the InlineShapes collection, while those that float over the text layer are controlled by the Shapes collection. Each contains a corresponding object type: InlineShape and Shape, respectively.

Working with InlineShapes

Instead of a single Add method, the InlineShapes collection has several different methods for adding different kinds of objects.

Perhaps the most important of the Add methods for the InlineShapes collection is AddPicture, which lets you add a graphic from a file. This is the programmatic equivalent of the Insert Picture dialog, shown in Figure 9. The syntax for AddPicture is as follows:

oDocument.InlineShapes.AddPicture( cPictureFile, lLinkToFile,

lSaveWithDocument, oRange )

cPictureFile	Character	The name, including the path, of the file that contains the graphic to be added to the document.
lLinkToFile	Logical	Indicates whether a link to the original field should be maintained in OLE terms, whether the picture is linked.
lSaveWithDocument	Logical	Indicates whether the picture is saved in the document or only linked in OLE terms, whether the picture is embedded.
oRange	Object	Pointer to the location where the picture should be inserted.

For example, to add the TasTrade bitmap to the beginning of a document, use code like this:

oRange = oDocument.Paragraphs[1].Range()

* Add picture, don't link, do embed

oDocument.InlineShapes.AddPicture( ;

_SAMPLES + "TASTRADE\BITMAPS\TTRADESM.BMP ", ;

.F., .T., oRange )

The results for a new document are shown in Figure 12.

Figure 12. Adding a graphic. To add a picture with Automation, you specify the filename, whether to link, whether to embed, and where to put it.

The other methods add other kinds of objects to the collection, like horizontal lines, bullets made from pictures, and OLE objects. See the Help file for details.

The InlineShape object itself is a container for the picture or other object. It doesn t hold the actual graphic or OLE object, but like VFP s OLE Container control, it provides a place for it to hang its hat. InlineShape has information about the format of the object it represents, as well as what type of object it is. The information that s available varies, depending on the type of object and whether it s linked or embedded. Table 8 lists the key properties of InlineShape and the constant values relevant for adding graphics.

Table 8. Adding graphics and other objects on the text layer. The InlineShape object contains format and other information about objects that move with the document text.

Property	Type	Description
Type	Numeric	The kind of graphic or other object. wdInlineShapePicture 3 Not linked wdInlineShapeLinkedPicture 4 Linked
Height, Width	Numeric	The size of the inline shape, in points. This is the actual space used for the shape in the document it s unrelated to the size of the underlying graphic. LockAspectRatio determines whether these can be changed independently.
ScaleHeight, ScaleWidth	Numeric	Percentage of the original height and width at which the object should be displayed. When these are changed, Height and Width also change. LockAspectRatio determines whether these can change independently.
LockAspectRatio	Logical	Indicates whether Height and Width must stay in the same relative proportions. When .T., changing Height also changes Width, and changing ScaleHeight also changes ScaleWidth.
PictureFormat	Object	For picture objects, reference to a PictureFormat object, which controls those items managed interactively through the Format Picture item on Word s menu (either Format\|Picture from the main menu or Format Picture from the context menu for a picture). These include cropping, brightness, and contrast. See Help for more information.
LinkFormat	Object	For linked objects, reference to a LinkFormat object, which contains information about the linked object, including the name of the file and the type of object. See Help for more information.
Borders	Object	Reference to a Borders collection for the InlineShape.

There are a number of other properties, many of them specific to particular types of objects or situations.

When processing the InlineShapes collection, be sure to check Type before assuming that properties like PictureFormat or LinkFormat are available. Different object types use different subsets of the properties, and accessing properties that aren t in use is a good way to cause an error.

Working with Shapes

Like InlineShapes, the Shapes collection doesn t have a method called simply Add. It has a number of specific methods for adding various types of objects. Shapes has its own version of AddPicture, with a somewhat different parameter list:

oDocument.Shapes.AddPicture( cPictureFile, lLink, lSaveWithDocument,

nLeft, nTop, nWidth, nHeight, oAnchor )

nLeft, nTop	Numeric	The position of the picture relative to the object referenced by oAnchor. Both default to 0. (Optional)
nWidth, nHeight	Numeric	The size of the picture. Defaults to the actual size of the picture. (Optional)
oAnchor	Object	A Range object that indicates where the picture is to be "anchored" in the document.

The other parameters have the same meaning here as they do for the InlineShapes collection s AddPicture method.

The anchor parameter to Shapes.AddPicture is a position in the document from which the picture is allowed to float. This gives Word the flexibility to move the picture around and put it where there s room for it. In addition, pictures added through Shapes can have text wrapped around them, in a number of different ways. InlineShapes pictures cannot, as they always occupy the entire width of the page or column, even if that leaves considerable white space.

There are a couple of downsides to using Shapes for adding graphics. The first is minor. The graphics don t show up in Word s Normal view; you have to switch to Print Layout or Web Layout (in Word 97, use Page Layout view) to see them. That can be misleading when you re editing a document, but is less of an issue for Automation.

The other issue is more serious. Because Word can move these graphics around, it does. Controlling where a picture added through the Shapes collection appears is difficult. As the document changes, the pictures can jump around the document.

Choosing the right way to add graphics requires evaluation of the pros and cons of each approach. Different documents may call for different choices.

The AddShape method lets you add AutoShapes. Here s the syntax:

oDocument.Shapes.AddShape( nShape, nLeft, nTop, nWidth, nHeight, oAnchor )

The parameters are the same as for the Shapes collection s AddPicture method, except for the additional nShape parameter. This is a numeric value that indicates which AutoShape to add. As you d expect, there s a set of constants available for these. Look up AutoShapeType in Help to see the list, or, for a more useful list of them, check out the msoAutoShapeType constants in the Object Browser. The list corresponds to the shapes available on the AutoShapes toolbar.

Shapes supports a number of other objects and has corresponding Add methods for those, as well. See Help for details.

The Shape object is the analogue to InlineShape and contains information about the picture or other object once you ve added it to the document. Shape has some of the same properties as InlineShape, but it also has additional properties that address specific issues of floating graphics.

As elsewhere, Type identifies the kind of item the Shape contains. However, it references a different set of constants. In this case, they come from Office itself. Table 9 lists a few of the permitted values.

Table 9. What kind of shape am I? The Type property of Shape accepts values from Office s msoShapeType set of constants.

Constant	Value	Constant	Value
msoPicture	13	msoAutoShape	1
msoLinkedPicture	11	msoChart	3

Height, Width, PictureFormat, and LinkFormat are the same for Shape as for InlineShape. ScaleHeight and ScaleWidth are methods rather than properties here (check Help for the parameters).

This example adds the TasTrade bitmap as a floating graphic attached to the first paragraph of the document:

oRange = oDocument.Paragraphs[1].Range()

* Add picture, don't link, do embed.

* By omitting the size, it defaults to the size of the graphic.

oDocument.Shapes.AddPicture( ;

_SAMPLES + "TASTRADE\BITMAPS\TTRADESM.BMP ", ;

.F., .T., 100, 100, , , oRange )

In order to see this picture, you have to be in a view other than Normal. Set the Type property of the View object of the Document s ActiveWindow to wdPrintView (3) or wdWebView (6). To return to the Normal view, set the property to wdNormalView (1).

#DEFINE wdPrintView 3

oDocument.ActiveWindow.View.Type = wdPrintView

With Shape objects, you can decide whether text is wrapped around the graphic and, if so, how wrapping works. Several properties and methods control this ability. The WrapFormat property references a WrapFormat object. That object s Type property offers the first level of settings for wrapping. Set it to wdWrapNone (3) to prevent text from wrapping around a graphic; in that case, the graphic appears in front of the text. The default is wdWrapSquare (0), which draws an imaginary square around the graphic (regardless of its actual shape) and puts text up to the edges of that square. There are several other choices, as well.

WrapFormat s Side property determines whether text appears on both sides of a graphic, if that s a possibility. The possible values are wdWrapBoth (0), wdWrapLargest (3), wdWrapLeft (1), wdWrapRight (2). The trickiest option here involves allowing text and graphics to occupy the same space, but making both of them visible. Figure 13 shows an AutoShape with text superimposed.

Figure 13. Combining graphics and text. By manipulating the Shape object s ZOrder method, you can put text on top.

The secret to creating this kind of effect is to call the Shape s ZOrder method and pass msoSendBehindText (5) as a parameter. ZOrder has more options for Shape than it does in Visual FoxPro. In addition to bringing an object to front (msoBringToFront, or 0) or sending it to back (msoSendToBack, or 1), you can send it behind text as in Figure 13 or bring it in front of text (msoBringInFrontOfText, or 4), and a couple of other choices, as well.

Here s the code to create Figure 13 at the beginning of a document:

#DEFINE msoShape16PointStar 94

#DEFINE msoSendBehindText 5

#DEFINE wdWrapNone 3

#DEFINE wdWrapBoth 0

#DEFINE CR CHR(13)

LOCAL oDocument, oRange, oShape

oDocument = oWord.Documents.Add()

oRange = oDocument.Range()

* Add the text

oRange.Font.Name = "Calligrapher" && or choose your favorite

oRange.Font.Size = 18

oRange.InsertAfter( CR + " Gold" + CR + " Medal")

* Now add the shape

oShape = oDocument.Shapes.AddShape( msoShape16PointStar, 0, 0, 81, 81, oRange )

oShape.WrapFormat.Type = wdWrapNone

oShape.WrapFormat.Side = wdWrapBoth

oShape.ZOrder( msoSendBehindText )