Programming Publisher 2003 Made Easy: Lesson 5

Article
07/11/2006

Andrew May
Microsoft Corporation

November 2004

Applies to:
Microsoft Office Publisher 2003

Summary: Learn how easy it is to use the Publisher object model to write macros that automate tasks in Publisher and save you time and energy. This lesson discusses how to use a method's return type, as well as how to use Microsoft Visual Basic Help to get the information you need about the Publisher object model to write your macros. (13 printed pages)

Introduction
Using the Results of a Method
Using the Object Browser
Using Publisher Visual Basic Help
Exercise
Review
Conclusion
Additional Resources

Introduction

Welcome back to the final lesson in this series. We taught you the basics of programming the object model. Now, we want to show you how to get the additional information you need as you go off and create macros of your own. This includes information about what objects are available in the Publisher object model, and how to make them and their members work for you. The Microsoft Visual Basic Editor (VBE) has a special window called the Object Browser that provides some of that information, and the online Help system provides even more. We'll show you how to get the most out of each.

But before we get to that, we have one final programming concept to introduce: return types.

Using the Results of a Method

When you call a method, it performs some action. For example, consider the following line of code:

ActiveDocument.PrintOut

The PrintOut method prints a document, in this case the active document. Sure, there are some optional parameters you can set, such as which pages to print and the number of copies you want, but the method just does what it's supposed to and that's it.

Some methods, however, actually return information as a result when they run. This information can be data, or even an object. Let's look at another line of code, one that we used in the macros written during previous lessons:

Dim myPage As Page
Set myPage = ActiveDocument.Pages.Add(1, 0)

Now, if you look closely, you see something that might confuse you. The myPage object variable is defined to hold a Page object. But in this line of code, we set it equal to the Add method. How can an object variable be set to contain a method? Well, it can't. Here is what's actually happening: the Add method returns a Page object when it runs. So the code is actually setting the myPage variable equal to the result of the Add method, which is a Page object.

Note If you're curious, procedures that do not return a result are called sub procedures. We worked with them throughout this series of lessons; all the macros that we wrote were sub procedures. Procedures that return information are called functions. You can create your own functions, but that's beyond the scope of this lesson.

The type of information a method returns is referred to as its return type. The return type of the Pages.Add method is a Page object. When describing a method, we use the following abbreviated form to denote a method's return type:

MethodName (parameters) As ReturnType

As you probably guessed, methods that do not return a result do not have a return type.

Using the Object Browser

As we worked through the first four lessons, you may have thought to yourself: this writer is so wonderful for teaching me how to use the Publisher object model, but how do I find out what objects there are to use?

To get basic information about the objects in the Publisher object model, use the VBE Object Browser window. This window lets you, well, browse through the objects in the object model, and see what properties, methods, and events each has. It also gives you basic information about how to use them.

For more information, see the online help, which is also linked to the Object Browser. We'll show you how later in this lesson. For now, let's take a brief tour of the Object Browser window.

To open the Object Browser:

Make sure you're in the Visual Basic Editor (VBE).
On the View menu, click Object Browser.
You can also open the Object Browser from the Standard toolbar. Just click the Object Browser button .

Tip If the Standard toolbar is not displaying, you can get it to display. From the View menu, select Toolbars, and click Standard.

The Object Browser usually opens in place of the Code window.

Tip Remember, you can get the Code window back at any time by selecting Code from the View menu.

Figure 1. Object Browser as it opens by default

By default, the Object Browser opens with the contents of all the different object models available. We're only interested in Publisher objects, so let's filter out the objects from the other object models. In the top pane, from the pull-down menu, select Publisher.

Figure 2. Type library selection menu

Note Object models are also sometimes referred to as type libraries. That's why the selection that shows all objects for all available object models is called <All Libraries>.

Now only the objects that belong in the Publisher object model are listed, alphabetically, in the Classes pane.

Note Objects are also sometimes referred to as classes. As we've mentioned before, the properties, methods, and events of an object are generically known as that object's members.

Let's take a look at an object we're already familiar with. Scroll down in the Classes pane and select Page. Notice that the properties, methods, and events of the Page object are now displayed in alphabetical order in the Members pane. In this way you can quickly see what members are available for an object.

The icons next to the names in the Classes and Members panes designate what type of element each item is. See the following table for examples.

Table 1. Visual Basic icons and the item types they represent

Icon	Element Type
	Object
	Property
	Method
	Event
	Enumeration category
	Enumeration value

Note Enumerations are fixed sets of named values. For example, the Position enumeration category might have the following enumeration values: Top, Middle, and Bottom. These values are also sometimes called constants, because, unlike variables, you cannot change their value. Using enumerations is beyond the scope of these lessons.

And no, don't ask me what the method icon is supposed to be. I have no idea.

Viewing an Element's Signature

Not only does the Object Browser show you what objects and members are in an object model, it also provides you with some basic information about how to use those elements.

With Page still selected, click the Height property in the Members pane. Notice how a few lines of text display in the untitled pane on the bottom of the Object Browser. This is the Height property's signature. This signature provides basic information about the element.

Figure 3. Signature of the Height property

1: Element type

2: Data type

3: Access

4: Member

Now select the Duplicate method. See how the information changes:

Figure 4. Signature of the Duplicate method

5: Parameter

6: Return type

The signature is a brief summary of the you are most likely to want to know, and may answer your question without you having to consult the online help at all. So let's take a detailed look at what the information presented actually means.

Element type. This indicates what type of element you selected. In this case, Height is a property. Methods are marked as either Sub or Function, depending on whether they have a return type. Objects are marked as classes.
Data type. (Properties only) This tells you what type of data a property contains. In the case of the Height property, we now know this property is a Long data type.

Note To get technical for a moment, the Long data type is a signed (that is, positive or negative) integer ranging in value from -2,147,483,648 to 2,147,483,647. For more information on data types, see Fundamental Variable Data Types.
Access. (Properties only) Some properties you can read, but not set their value. These are read-only properties. These properties are usually ones that Publisher sets itself, or they rely on some other setting for their value. If a property's signature doesn't explicitly state that it's read-only, then it's read-write, meaning you can set the property's value as well.
Member. This indicates the object model the element belongs to, and the object it belongs to if it's a property, method, or event.
Parameters. (Methods only) Method signatures also list the parameters of the method, and related information, including:
- The parameters a method has.
  
  For example, the Duplicate method has two parameters, NewAbbrevation and NewName.
- The data or object type of each parameter.
  
  For example, both parameters here are of the String data type; this means each parameter takes a series of characters, such as a word or sentence.
- The order in which you have to list your parameters when using the method.
  
  For example, you must specify parameters in the same order as they appear in a method's signature.
- Which parameters are optional.
  
  For example, parameters enclosed in straight brackets ([]) are optional. Both parameters of the Duplicate method are optional.

Note When you use an optional parameter in your code, do not include the straight brackets. They're just in the signature to show the parameter is optional.

Return type. (Methods only) As we discussed earlier, the return type is the type of information the method returns when it runs. From this signature, we can tell that the Duplicate method returns a Page object.

You can see how this is useful. Just from looking in the Object Browser, we now know what objects exist in the Publisher object model, what members each object contains, and the basic information for each member.

Searching for an Object or Member

You can also search an object model to find a specific object or member.

To find an object or member in the Object Browser:

Make sure Publisher is selected from the Library drop-down menu.
Enter search text in the text box. This can include wild cards.
Click Search.

The Object Browser displays the objects and members that match your search criteria in the Search Results pane.

Using Publisher Visual Basic Help

Handy as the Object Browser is, sometimes you need more than the basic information it provides. And that's where the online Help system comes in. The online help for Publisher includes the Publisher Visual Basic Reference. This reference contains a separate help topic for each object and member in the Publisher object model.

There are several ways to get to the reference. You can open the reference and look for the topic you want. Even better, the reference is also context-sensitive; if you want to view a particular topic, you can open the online help right to that topic from within the Object Browser or Code window.

To open the Publisher VBA reference to the table of contents

There are two ways to open the online help with the Publisher VBA Reference open to its table of contents:

On the Standard toolbar, click Help. The Visual Basic Help pane opens. Click the book titled Microsoft Publisher Visual Basic Reference.
From the Help menu, click Microsoft Visual Basic Help. The Visual Basic Help pane opens. Click the book titled Microsoft Publisher Visual Basic Reference.

In the table of contents, the help topics for Publisher object model elements are listed alphabetically, according to element type: Collections, Objects, Methods, Properties and Events. Clicking a topic title launches the Help window with that topic showing.

To open the Publisher VBA reference to a specific topic

If you're in the middle of writing some code, and you want to find out information about a specific object model element, getting to that element's help topic is only a single click away. Both the Object Browser and Code windows have context-sensitive help; this means they display the correct help topic for the object model element you've got selected at the time. Here's how it works.

From the Object Browser window:

Select an object or member in the Search Results, Classes, or Members pane.
Press F1.

The Help window opens, displaying the topic for the element you selected.

From the Code window:

Highlight the name of an object or member in the code you wrote.
Press F1.

The Help window opens, displaying the topic for the element you highlighted.

Note When you use either of these methods, the Visual Basic Help pane does not open.

Anatomy of a Help Topic

Now that we know how to get to the help topic we want, let's take a look at what information the help topics actually give us.

Signature. The help topic contains the element's signature, which is also displayed in the Object Browser. However, the help topic often provides more explanation about the signature. For example, the help topic might tell you what a method's different parameters actually represent, if it's not obvious from their names.
Remarks. This is a catch-all for any other information you should know about how to use the object or member. These might include discussing other properties that influence the element value, what you can or can't do with the element, or any other "gotchas" that might make your code fail if you didn't know about them in advance.
Examples. This might be the most useful section for programmers who are just starting out. Most of the topics have examples that show how you use the element in your code. Feel free to steal this code. That's why it's there. Copy and paste the code into your procedures, modify it to suit your needs, and you're ready to go. If there are other things you need to set for the code to run properly, that's noted in the explanatory text right before the code sample.

Navigating Between Help Topics

Once you're in a help topic, and you want to look at a related topic, you don't need to go back to the table of contents, or the Object Browser, or the Code window (although you certainly can). Each help topic contains hyperlinks to other, related topics. For example, object topics contain links to topics for the object's members, and member topics contain links to object topics. The links are presented a little differently in object topics than in member topics, so let's discuss each.

Open the RulerGuide object help topic, using the method of your choice. The RulerGuide object represents one of the grid lines you use to align objects on a page. Figure 5 shows what you see at the top of the topic.

Figure 5. Object topic navigation bar and object hierarchy

Under the title there's a navigation bar that contains links to the object's members. For example, click Properties, and the topic displays a list of the RulerGuide object's properties. Each property name is a link to the topic for that property. If an object doesn't have any elements of a certain type, that type is disabled. The RulerGuide object doesn't have any events, for instance, so Events is disabled.

Click See Also for a list of any topics that might also be of interest. These are usually conceptual topics that discuss technical information that affects multiple objects or members.

Right underneath the navigation bar is a small illustration that shows the object's place in the Publisher object model. From it, we can see that the RulerGuide object is contained in the RulerGuides collection, which is in turn contained in the Page object. If the RulerGuide object contained other objects, these would be shown as well. Each object in the illustration is also a link; clicking the object takes you to the topic for that object.

Terminology If an object is contained in another object, that other object is referred to as its parent object. If an object contains another object, that other object is referred to as its child object. For example, the Page object contains the RulerGuides collection. The Page object is the parent object for the RulerGuides collection; the RulerGuides collection is a child object of the Page object.

In cases where the object is contained in more than one type of object, clicking the parent object icon displays a list of all the possible parent objects. The same is true when the object contains multiple child objects.

Member topics are a little different. The navigation bar for member topics contains three types of links: See Also, Applies To, and Example. Click Applies To and the topic displays a list of the objects that have that member. Click Examples and the topic scrolls down to the code example, because some of the topics get long, and you might only be interested in seeing the code sample.

Exercise

Let's take a real-world scenario, and see how we can use what we learned to find the information we need to complete our macro.

In the last lesson, we created a macro that replaces each instance of our logo in a publication with a new, better logo. Now, suppose we're talking about a Web publication, and we also want to add a hyperlink to our logo, so clicking it takes the user to our main Web site. That's reasonable, right? We know we can do it by using the Publisher user interface. But how would we figure out how to do that programmatically?

Here's the code we want to modify:

Sub UpdateLogo()
Dim pbPage As Page
Dim pbShape As shape

For Each pbPage In ActiveDocument.Pages
  For Each pbShape In pbPage.Shapes
    If pbShape.Type = pbLinkedPicture Then
      If pbShape.PictureFormat.Filename = "C:/logo.gif" Then
        pbShape.PictureFormat.Replace ("C:/newlogo.gif")
      End If
    End If
  Next pbShape
Next pbPage
           
End Sub

First, we need to be clear about what we want to do. So let's break it into discreet steps we need to code:

Add a hyperlink to an image, which is a shape.
Set the destination of the hyperlink.

Objects are models of real-world "things." A hyperlink is a thing in a publication. So let's see if the Publisher object model contains a Hyperlink object.

In the Visual Basic Editor, click Object Browser. In the Object Browser, make sure the Publisher object model is selected. Type "hyper" into the search box, and then click Search.

The second entry in the Search Results pane lists a Hyperlink property, which belongs to the Shape object. That looks promising. Select that entry and press F1 to bring up the associated help topic.

In the help topic, the definition for the Hyperlink property tells us that the property "returns a Hyperlink object representing the hyperlink associated with the specified shape." Sounds like what we're looking for. Even better, the code example in the topic shows how to use the hyperlink of a shape, and set the destination address for the link. How lucky a coincidence is that?

So it looks like we want to do the following:

Use the Hyperlink property of the Shape object to access the shape's Hyperlink object.
Use the Address property of the Hyperlink object to set the link's destination.

But let's get some more information, just to be sure. Let's find out more about the Hyperlink object. We could click the hyperlink to the object topic in the help topic. Instead, let's look in the Object Browser again. In the Classes pane, scroll down to Hyperlink, then select it. The Hyperlink object's members appear in the Members pane. So here we can get a quick look at the members of an object, and see their signatures.

In the Members pane, select the Address property so we can take a look at its signature. It's a String data type, which means it's a line of characters like a word, or phrase, or. . .Internet address. It doesn't say read-only, so it's read/write, which means we can set its value directly through code. Let's open the help topic to see if there's anything else we should know about this property before we use it. With the Address property selected, press F1.

This brings up the Address property topic. As we figured, the property is a string that represents the URL address for a hyperlink. There aren't any remarks about how to use this property, so it looks pretty straightforward. The phrase "Returns or sets" is another way of saying you can both write and read the property value; now we know for sure we can set its value using code.

Now that we researched the object and property we need to use, let's modify our code to get the job done. Because of our research, we know that all we have to do is add a single line of code, one that specifies the address of the hyperlink:

pbShape.Hyperlink.Address = "http://www.tailspintoys.com"

We need to add this line inside the If. . .Then statement that updates the logo image. The final macro code should look like this:

Sub UpdateLogo()
Dim pbPage As Page
Dim pbShape As shape

For Each pbPage In ActiveDocument.Pages
  For Each pbShape In pbPage.Shapes
    If pbShape.Type = pbLinkedPicture Then
      If pbShape.PictureFormat.Filename = "C:/logo.gif" Then
        pbShape.PictureFormat.Replace ("C:/newlogo.gif")
        pbShape.Hyperlink.Address = "www.tailspintoys.com"
      End If
    End If
  Next pbShape
Next pbPage
           
End Sub

So with just a few minutes of research and a single line of code, we can add a hyperlink wherever our new logo appears in the publication. That's the power of programmability.

Review

Some methods return information as a result when they run. This information can be data or an object. The type of information a method returns is referred to as its return type.

To get basic information about the objects in the Publisher object model, use the VBE Object Browser window. This window lets you view the objects in the object model, and see what properties, methods, and events each has.

Make sure you're in the Visual Basic Editor (VBE).
From the View menu, click Object Browser.

The Object Browser window also displays the selected element's signature. This signature provides basic information about the element.

For more information, see the online help.

To open the online help with the Publisher VBA Reference open to its table of contents, do one of the following:

Click Help on the Standard toolbar. The Visual Basic Help pane opens. Click the book titled Microsoft Publisher Visual Basic Reference.
From the Help menu, click Microsoft Visual Basic Help. The Visual Basic Help pane opens. Click the book titled Microsoft Publisher Visual Basic Reference.

To open the Publisher VBA Reference to a specific topic, do one of the following:

From the Object Browser window, select an object or member in the Search Results, Classes, or Members pane, and press F1.
From the Code window, highlight the name of an object or member in the code you've written, and press F1.

Each help topic contains hyperlinks to other, related topics.

Conclusion

Congratulations! You completed the entire series of lessons. By now, you should have a wide range of skills for writing macros that get the job done. Not only are you familiar with the Publisher object model, and special types of objects like collections, forms, and controls, but you also mastered programming logic techniques such as using If. . .Then and For Each. . .Next loops. With lesson five, you learned how to use the Visual Basic Help to get the information you need about the Publisher object model in order to write your macros.

Go forth and code.

Acknowledgments

Special thanks go out to Frank Rice, for allowing me to steal the structure of his Super-Easy Guide to the Microsoft Office Excel 2003 Object Model article for this series of lessons. Thank you, Frank.

Additional Resources

This section lists a number of resources you can use to learn more about the products and technologies mentioned or used in this article.