Setting Options for Raster Export Programmatically in Visio 2010

Summary:  Learn how to programmatically set options for exporting Microsoft Visio 2010 diagrams in raster format (as .bmp, .gif, .jpg, .png, and .tif files).

Applies to: Office 2010 | SharePoint Server 2010 | Visio 2010 | Visio Premium 2010

In this article
Introduction
Getting and Setting Raster Export Resolution
Getting and Setting Raster Export Size
Setting Other Raster Export Properties
Conclusion
Additional Resources

Published:  October 2010

Provided by:  Saul Candib, Microsoft Corporation

Contents

• Introduction

• Getting and Setting Raster Export Resolution

• Getting and Setting Raster Export Size

• Setting Other Raster Export Properties

• Conclusion

• Additional Resources

Introduction

You can use the Visual Basic for Applications (VBA) object model exposed by Microsoft Visio 2010 to export Visio 2010 diagrams in raster file formats (as .bmp, .gif, .jpg, .png, and .tif files). To do so, you can use the Export method of the Page object, assigning the appropriate extension to the file. Alternatively, you can use the Export method of the Master, Selection, or Shape object.

When you use the Visio user interface (UI) to export diagrams in raster formats, you are presented with a dialog box that lets you set options—such as resolution, size, color format, and background and transparency color—for the exported file. In Visio 2010, you can also set these options programmatically. This article describes how to use the new raster-export-related methods and properties of the ApplicationSettings object to set raster export options for the active Visio page. To get an ApplicationSettings object, you can use the Settings property of the Application object.

Getting and Setting Raster Export Resolution

Raster export resolution is the resolution of the resulting image file when you export a Visio drawing in a supported raster format. You can use the GetRasterExportResolution method to get the current raster export resolution and the SetRasterExportResolution method to set the raster export resolution.

Table 1 shows the parameters that the GetRasterExportResolution method takes.

Table 1. GetRasterExportResolution parameters

The pResolution parameter must be a constant from the VisRasterExportResolution enumeration. These constant values include screen resolution, printer resolution, source resolution, and custom resolution. If pResolution returns anything other than custom resolution—visRasterUseCustomResolution (3)—the method returns zero for all the other parameters. On the other hand, if pResolution is visRasterUseCustomResolution, GetRasterExportResolution returns non-zero values for all the other parameters.

The method itself does not return a value. As shown in the following Visual Basic for Applications (VBA) code sample, you get return values by declaring variables of the appropriate types shown in the preceding table, passing those variables as output parameters. Then you check the values of the variables after you run the method.

Public Sub GetRasterExportResolution_Example()

    Dim cnstRasterExportResolution As VisRasterExportResolution
    Dim dblWidth As Double
    Dim dblHeight As Double
    Dim cnstRasterExportResolutionUnits As VisRasterExportResolutionUnits
    
    Visio.Application.Settings.GetRasterExportResolution cnstRasterExportResolution, dblWidth, dblHeight, cnstRasterExportResolutionUnits
    
    Debug.Print cnstRasterExportResolution; dblWidth; dblHeight; cnstRasterExportResolutionUnits    

End Sub

The SetRasterExportResolution method closely resembles the GetRasterExportResolution method. SetRasterExportResolution does have two key differences, however:

• The parameters it takes are input parameters, instead of output parameters.

• All except the first parameter, resolution, are optional, as shown in Table 2.

Table 2. SetRasterExportResolution parameters

As is the case with the GetRasterExportResolution method, if the resolution parameter value is a constant other than visRasterUseCustomResolution, SetRasterExportResolution ignores all the other parameters, if they are used. If resolution is visRasterUseCustomResolution, SetRasterExportResolution accepts values for all parameters, assuming they meet the constraints noted in the table, and fails if the parameters are absent. Like GetRasterExportResolution, SetRasterExportResolution returns nothing.

The following VBA code example shows how to set raster export resolution. It passes visRasterUseCustomResolution for the resolution parameter, thereby telling Visio to accept the values in the remaining, optional parameters.

Public Sub SetRasterExportResolution_Example()

    Dim cnstRasterExportResolution As VisRasterExportResolution
    Dim dblWidth As Double
    Dim dblHeight As Double
    Dim cnstRasterExportResolutionUnits As VisRasterExportResolutionUnits
    
    cnstRasterExportResolution = visRasterUseCustomResolution
    dblWidth = 640
    dblHeight = 480
    cnstRasterExportResolutionUnits = visRasterPixelsPerCm
    
    Visio.Application.Settings.SetRasterExportResolution cnstRasterExportResolution, dblWidth, dblHeight, cnstRasterExportResolutionUnits
    
    Debug.Print cnstRasterExportResolution; dblWidth; dblHeight; cnstRasterExportResolutionUnits    

End Sub

When the SetRasterExportResolution method runs successfully, the resulting settings remain in effect until you either run the method again or change the settings in the user interface.

Getting and Setting Raster Export Size

Raster export size is the size of the resulting image when you export a Visio drawing in a supported raster format. You can use the GetRasterExportSize method to get the current raster export size, and the SetRasterExportSize method to set the raster export size.

Table 3 shows the parameters that the GetRasterExportSize method takes.

Table 3. GetRasterExportSize parameters

The pSize parameter must be a constant from the VisRasterExportSize enumeration. These constant values include screen size, printer size, source size, and custom size. If the pSize parameter value is a constant other than visRasterFitToCustomSize, GetRasterExportSize returns zero for all the other parameters. If pSize is visRasterFitToCustomSize, GetRasterExportSize returns non-zero values for all parameters.

Like the GetRasterExportResolution method, the GetRasterExportSize method itself does not return a value. As shown in the following VBA code example, you get return values by declaring variables of the appropriate types shown in the preceding table, passing those variables as output parameters, and then checking the values of the variables after you run the method.

Public Sub GetRasterExportSize_Example()

    Dim cnstRasterExportSize As VisRasterExportSize
    Dim dblWidth As Double
    Dim dblHeight As Double
    Dim cnstRasterExportSizeUnits As VisRasterExportSizeUnits
    
    Visio.Application.Settings.GetRasterExportSize cnstRasterExportSize, dblWidth, dblHeight, cnstRasterExportSizeUnits
    
    Debug.Print cnstRasterExportSize; dblWidth; dblHeight; cnstRasterExportSizeUnits

End Sub

The SetRasterExportSize method closely resembles the GetRasterExportSize method. SetRasterExportSize does have two key differences, however:

• The parameters it takes are input parameters, instead of output parameters.

• All except the first parameter, size, are optional, as shown in Table 4.

Table 4. SetRasterExportSize parameters

As is the case with the GetRasterExportSize method, if the size parameter value is a constant other than visRasterFitToCustomSize, SetRasterExportSize ignores all the other parameters, if they are used. If size is visRasterFitToCustomSize, SetRasterExportSize accepts values for all parameters, assuming they meet the constraints noted in the table, and fails if the parameters are absent. Like GetRasterExportSize, SetRasterExportSize returns nothing.

The following VBA code example shows how to set raster export size. It passes visRasterFitToCustomSize for the size parameter, thereby telling Visio to accept the values in the remaining, optional parameters.

Public Sub SetRasterExportSize_Example()

    Dim cnstRasterExportSize As VisRasterExportSize
    Dim dblWidth As Double
    Dim dblHeight As Double
    Dim cnstRasterExportSizeUnits As VisRasterExportSizeUnits
    
    cnstRasterExportSize = visRasterFitToCustomSize
    dblWidth = 640
    dblHeight = 480
    cnstRasterExportSizeUnits = visRasterPixel
    
    Visio.Application.Settings.SetRasterExportSize cnstRasterExportSize, dblWidth, dblHeight, cnstRasterExportSizeUnits
    
    Debug.Print cnstRasterExportSize; dblWidth; dblHeight; cnstRasterExportSizeUnits    

End Sub

When the SetRasterExportSize method runs successfully, the resulting settings remain in effect until you either run the method again or change the settings in the user interface.

Setting Other Raster Export Properties

In Visio 2010, you can programmatically set not only raster export resolution and size, as shown previously, but also all of the other raster export options that are available in the Visio user interface. These options are available in the various Output Options dialog boxes (one for each raster type) that appear when you click Save in the Save As dialog box after you have selected one of the raster types in the Save as type list. The options vary by raster file type, as shown in Table 5. The table lists the new properties on the ApplicationSettings object that are available for setting raster export options.

Table 5. ApplicationSettings raster export properties

Where the preceding table indicates (in the Applicable Export Formats column) that the applicable export formats listed depend on the particular property value applied, see the linked topics for more information.

In general, for any given session of Visio 2010, when any of these property values are set (either programmatically or in the user interface), the setting then becomes the new default for the rest of the session. However, it is not persisted to the next session.

Conclusion

In Visio 2010 you can set options programmatically for exporting masters, pages, shapes, and selections as files in raster format—options that in previous versions you could set only in the UI. This article presents the new methods and properties on the ApplicationSettings object that make this export possible and provides code examples that show how to use the new methods to get and set raster export resolution and size.

Additional Resources

Visio Developer Center

Visio Insights Blog

Office Client Developer Content Blog