What's New For Developers in Publisher 2007
Saul Candib, Microsoft Corporation
Applies to: 2007 Microsoft Office System, Microsoft Office Publisher 2007
Summary: Explores new features for developers in Microsoft Office Publisher 2007, describes the new objects and members of the Publisher 2007 object model, and lists deprecated members. (13 printed pages)
The following list describes new developer-related features in Microsoft Office Publisher 2007. Each of these features has an associated API that makes it possible to control the feature programmatically. The new developer-related features provide the following functionality:
Creating e-mail merges (sending personalized e-mail messages to multiple recipients).
Managing mail-merge lists, including recipient lists for mail and catalog merges.
Creating bulk mail publications and inserting bar codes.
Getting and setting printer options.
Saving publications as fixed format files: Portable Document Format (.pdf) and XML Paper Specification (.xps).
Changing templates and reusing extra content.
Setting business information.
This article introduces new objects and members that developers can use to take advantage of these features. It includes links to Office Publisher Help topics on MSDN that provide more details about each object and member, and code samples that show how to use some of the new objects and members.
You can now programmatically create and send merged e-mail messages that contain your publication. The new EmailMergeEnvelope object exposes several properties that let you specify the recipients, subject, priority, and attachments to the merged e-mail message that contains your publication. The properties of the EmailMergeEnvelope object correspond to the required and optional settings in the Merge to E-mail dialog box in the Publisher 2007 user interface (UI).
Publisher 2007 introduces the ability to combine information from multiple data sources into a common master data source for creating mail-merge documents. You can use this feature in the UI and through the object model.
You can use several new methods of the MailMergeDataField object to create and manage mail-merge recipient lists. The AddToRecipientFields method adds a new field (column) from a particular data source to the master data source (combined collection of data fields) for a mail-merge publication. The MapToRecipientField method maps a column in a particular data source to a recipient column in the master data source, while the UnmapRecipientField method undoes the mapping.
Additionally, the new IsMapped and MappedTo properties of the MailMergeDataField object provide information about the mapping status of data fields, while the IsMaster property of the MailMergeDataSource object indicates whether the parent object is a master data source (a combination of all data sources connected to the current publication). The EditRecord method of the MailMergeDataSource object changes one of the data fields in one of the records in the master data source.
The new ExportRecipientList method of the MailMerge object exports the list of mail-merge recipients to a Microsoft Office Access (.mdb) file or to a comma-delimited text (.csv) file. The new CreateShortcut method of the MailMerge object creates a shortcut to the file that contains the list of recipients or products for a mail-merge publication to make it easier to access the list later.
Office Publisher 2007 makes it easier for businesses to take advantage of bulk mailing rates by programmatically creating and inserting postal bar codes and validating mail-recipient addresses in mail-merged publications. Several new members of existing objects extend the Publisher object model for support of bulk mailing, bar codes, and address validation. You can write code that uses these members in the Publisher Visual Basic Editor window, or you can create an add-in for Office Publisher 2007 that validates recipient addresses and maintains its own data sources.
The MailMergeGenerateBarcode event of the Application object occurs when Publisher requires data to generate bar codes in a mail-merge publication, in particular, when the mail-merge recipient list changes.
The EverValidated property of the MailMergeDataSource object indicates whether the list of recipient addresses in the parent object has ever been validated.
The ValidatedClean property of the MailMergeDataSource object indicates whether all recipient addresses in the parent object were successfully validated, and whether any changes were made to the list since the last validation that require the list to be validated again.
The new InsertBarcodeVisible property of the Application object enables insertion of bar codes into the publication from the UI.
The ValidateAddressVisible property of the Application object enables validation of the recipient address list from the UI.
You can get and set many new printer options programmatically. These options correspond to the options that you can set in the Print Setup and Advanced Printer Setup dialog boxes in the Office Publisher 2007 UI.
The new Printer object exposes 15 properties, many of which correspond to settings in the Print Setup dialog box for a specific printer. For example, the PaperOrientation property gets or sets the paper orientation (landscape or portrait) of the printer. The IsActivePrinter property gets or sets a specific printer as the active printer.
The new InstalledPrinters object represents the collection of all the printers installed on your computer.
The AdvancedPrintOptions object exposes four new properties that specify how envelopes are fed to the printer and whether the printed page should be rotated.
You can use the new Recolor method of the PictureFormat object to apply a color cast to a picture in a publication. To subsequently change the colors of the picture back to the original colors, use the RestoreOriginalColors method of the same object.
In addition, you can use three new properties of the PictureFormat object to get information about recolored pictures and to set recoloring options:
The IsRecolored property value indicates whether the image represented by the parent PictureFormat object was recolored, either in the user interface or by using the Recolor method.
The LeaveBlackAsBlack property value indicates whether the black parts of the original image should remain black when you recolor the image represented by the parent PictureFormat object.
The RecoloredPictureColor property returns the color that is applied to the image represented by the parent PictureFormat object.
You can save your publications as .pdf and .xps files, and then share them with other users who have PDF or XPS readers. This makes it easier to share your publications with customers, colleagues, or family members who do not have Office Publisher 2007 installed on their computers. It also readies the document to be sent to commercial presses, to copy shops, for desktop printing, or for electronic distribution.
If you want to change the current publication template, for example, from one style of brochure to another, you can use the new ChangeDocument method of the Document object to change the current publication to one that uses the publication wizard, and optionally, the design that you specify.
When you change publication templates in an existing publication, some shapes in the old publication template may not fit neatly into the new template. Office Publisher 2007 classifies these shapes as surplus shapes, and notifies you of the classification so that you will not lose work. Two new properties provide information about surplus shapes:
The new SetBusinessInformation method of the Document object applies an existing business information set, which consists of a logo image and business contact information (such as a company name and address), to the current publication.
The following tables list new objects, methods, properties, events, enumerations, and constants in the Office Publisher 2007 object model.
Table 1 lists the new objects in the Office Publisher 2007 object model.
Represents a single file attachment for e-mail merge contained in a publication.
A collection that contains Attachment objects that represent the attachments in a publication.
Represents the e-mail container (envelope) that holds the Publisher 2007 document that is merged into an e-mail merge.
Gets the names of all printers installed on the computer.
Represents the collection of all MailMergeDataSource objects in the active Publisher document, each of which represents one of the data sources in a mail-merge operation.
Gets the page size of the current publication.
Represents the collection of all PageSize objects in the parent Document object, where each PageSize object represents one of the page sizes available in the current Publisher document.
Corresponds to a printer available on your system.
Table 2 lists the new methods in the Office Publisher 2007 object model.
Adds the parent MailMergeDataField object from a particular data source to the master data source (collection of data fields) for a mail-merge publication.
Changes the current publication to one that uses the wizard, and optionally, the design that you specify.
Creates a shortcut to the file that contains the list of recipients or products for a mail-merge publication.
Changes one of the data fields in one of the records in the master data source (the combined mail-merge recipient list).
Converts a Publisher 2007 publication into .pdf or .xps format. The conversion readies the document to be sent to commercial presses, to copy shops, for desktop printing, or for electronic distribution.
Exports the list of mail-merge recipients to an Access (.mdb) file or to a comma-delimited text (.csv) file.
Returns the current expression for the primary key column that corresponds to the specified field.
Maps a field (column) in a particular data source represented by the parent MailMergeDataField object to a recipient field (column) in the master data source (combined mail-merge recipient list).
Moves a shape to the specified page.
Changes the color of a picture in a publication.
Restores the original colors of a picture that was recolored.
Saves one or more shapes to a picture file.
Helps store business information. Business information consists of a logo image and business contact information, such as the company name and address.
Specifies the type of the wizard (template) to convert the current publication type to.
Displays the Publication Types catalog for the wizard of the specified type.
Undoes the mapping between the parent MailMergeDataField object in a particular data source and the recipient field in the master data source (combined mail-merge recipient list) to which it is currently mapped.
Table 3 lists the new properties in the Office Publisher 2007 object model.
Gets a reference to the 2007 Microsoft Office system IAssistance object, which enables developers to create a customized Help experience for users within the 2007 Office system. Read-only.
Specifies the security mode to use when you open files programmatically.
Gets or sets whether the second side of the paper for two-sided printing should be inserted face up or face down.
Returns the base cyan-magenta-yellow-black (CMYK) color value of the parent ColorFormat object before any tinting or shading is applied to the color. Read-only.
Returns the MailMergeDataSources collection that includes the parent MailMergeDataSource object. Read-only.
Returns the EmailMergeEnvelope object associated with the parent MailMerge object. Read-only.
Determines whether the text "Continued from page pagenumber" appears in a text box when Publisher 2007 uses text-box linking.
Determines whether the text "Continued on page pagenumber" appears in a text box when Publisher 2007 uses text-box linking.
Determines whether Add a postal bar code is available under More Items on the Mail Merge and Catalog Merge task panes in the Publisher 2007 UI; and whether Add postal bar codes is available under Prepare for Mailing on the Publisher Tasks task pane in the Publisher 2007 UI.
Gets the names of all printers installed on the computer and to which the application can print the publication. Read-only.
Indicates whether the parent Shape object is an excess shape after the document template (wizard) is changed by using the Document.ChangeDocument method or by using the Change Template command in the Publisher 2007 UI. Publisher 2007 places any excess shape under Extra Content in the Format Publication task pane. Read-only.
Indicates if the parent MailMergeDataField object is mapped to a recipient field in the master data source (combined mail-merge recipient list). Read-only.
Indicates whether the parent MailMergeDataSource object is a master data source (a combination of all data sources connected to the current publication). Read-only.
Returns True if the image represented by the parent PictureFormat object was recolored, either in the UI or by using the PictureFormat.Recolor method. Read-only.
Returns True if, while you are recoloring, the black portion of the original image should be left as black. Read-only.
Returns the number of lines of text in the text range represented by the parent TextRange object. Read-only.
Gets or sets the alignment (left, right, or center) of where envelopes are fed to the printer's manual feed.
Gets or sets the orientation (landscape or portrait) of how envelopes are fed to the printer's manual feed.
Returns the name of the recipient field (column) in the master data source (combined mail-merge recipient list) that the parent MailMergeDataField object is mapped to. Read-only.
Gets or sets whether the second page must be rotated 180 degrees from the first-page direction before it is reinserted for two-sided printing.
Returns or sets the page size for the specified custom mailing label.
Returns the number of paragraphs of text in the text range represented by the parent TextRange object. Read-only.
Returns the color that is applied to the image represented by the parent PictureFormat object. Read-only.
Gets or sets the string (if any) that appears as the fourth item under Prepare to follow-up on this mailing on the third Mail Merge task pane in the Publisher 2007 UI.
Returns a ShapeRange object that represents the collection of surplus shapes that Publisher 2007 places under Extra Content in the Format Publication task pane after the document template (wizard) is changed by using the Document.ChangeDocument method or by using the Change Template command in the Publisher 2007 UI. Read-only.
Returns or sets a Single indicating the degree of transparency of the specified fill, shadow, or line as a value between 0.0 (opaque) and 1.0 (clear).
Gets or sets the type of mail merge represented by the parent MailMerge object.
Gets or sets whether to use a wizard for blank publications.
Determines whether Validate addresses is available under Refine recipients in the Mail Merge task pane and whether Validate addresses is available under Prepare for Mailing on the Publisher Tasks task pane in the Publisher 2007 UI.
Indicates whether all recipient addresses in the parent MailMergeDataSource object were successfully validated, and whether any changes were made to the list since the last validation that require the list to be validated again.
Returns the number of words in the text range represented by the parent TextRange object. Read-only.
Table 4 lists the new events in the Office Publisher 2007 object model.
Occurs after all variables and fields are printed. UI control does not return to the user until the event handler executes. The event is called after all the drawing operations are complete to notify the user that the document has printed.
Occurs before the publication is printed or previewed. This event occurs only after the document fully loads and the On Load events are returned. Printing does not occur until the event handler executes.
Occurs when the catalog of publication wizards is hidden in the Publisher 2007 UI.
Occurs when Publisher 2007 requires data to generate bar codes in a mail-merge publication, in particular, when the mail-merge recipient list changes.
Occurs when the user issues the command to insert postal bar codes into a mail-merge publication, either in the Publisher 2007 UI, or programmatically.
Occurs when the user closes the Mail Merge Recipients dialog box. (On the Mail Merge or E-mail Merge task pane, click Edit Recipient List.) Also occurs when the user closes the Catalog Merge Product List dialog box, which opens when the user clicks Edit Product List in the Catalog Merge task pane.
Occurs when a user clicks the string that appears as the fourth item under Prepare to follow-up on this mailing on the third Mail Merge task pane in the Publisher 2007 UI.
Occurs when the catalog of publication wizards is displayed in the Publisher 2007 UI.
Table 5 lists the new enumerations in the Office Publisher 2007 object model.
Driver-type constants returned by the Printer.DriverType property.
Constants for merged e-mail message priority passed to and returned by the EmailMergeEnvelope.Priority property.
Constants passed to the ExportAsFixedFormat method that specify how the user intends to share the resulting file: by sending it to a commercial printer or desktop printer, or by distributing it online or through e-mail merge.
Constants passed to the ExportAsFixedFormat method that specify the different file formats in which you can save fixed-format publications, .pdf or .xps.
Constants that specify the type of mail merge, passed to and returned by the MailMerge.Type property.
Constants that specify the print style, passed to the Document.PrintOutEx and ExportAsFixedFormat methods.
Constants that specify the type of file in which to save an exported mail-merge recipient list, passed to the MailMerge.ExportRecipientList method.
Table 6 lists new constants that are available in existing enumerations in the Office Publisher 2007 object model.
Table 7 lists object-model items that are deprecated in the Office Publisher 2007 object model.
Object or Enumeration
Member or Constant
This article introduces the new features of interest to developers in Office Publisher 2007, including the APIs associated with the new features. It lists all the new objects and members added to the Office Publisher 2007 object model and provides links to Office Publisher Help topics on MSDN that show how to use the new objects and members. In addition, it lists the items that are deprecated in the Office Publisher 2007 object model.