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.
Note
Availability of these options varies by raster type. However, if a particular option applies to more than one raster type, setting it programmatically for one type sets it for all applicable types. For more information, see Setting Other Raster Export Properties.
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
Name |
Required/Optional |
Data type |
Description |
---|---|---|---|
pResolution |
Required |
VisRasterExportResolution |
Output parameter. The raster export resolution type. |
pWidth |
Required |
Double |
Output parameter. The raster export resolution width. |
pHeight |
Required |
Double |
Output parameter. The raster export resolution height. |
pResolutionUnits |
Required |
VisRasterExportResolutionUnits |
Output parameter. The units used to specify resolution. Can be either pixels per inch or pixels per centimeter. |
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
Name |
Required/Optional |
Data type |
Description |
---|---|---|---|
resolution |
Required |
VisRasterExportResolution |
The raster export resolution type. Can be printer, screen, source, or custom resolution. |
Width |
Optional |
Double |
The raster export resolution width. Must be greater than or equal to 1. |
Height |
Optional |
Double |
The raster export resolution height. Must be greater than or equal to 1. |
resolutionUnits |
Optional |
VisRasterExportResolutionUnits |
The units used to specify resolution. Can be either pixels per inch or pixels per centimeter. |
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
Name |
Required/Optional |
Data type |
Description |
---|---|---|---|
pSize |
Required |
VisRasterExportSize |
Output parameter. The raster export size target type. |
pWidth |
Required |
Double |
Output parameter. The raster export size width. |
pHeight |
Required |
Double |
Output parameter. The raster export size height. |
pSizeUnits |
Required |
VisRasterExportSizeUnits |
Output parameter. The units used to specify raster export size. Can be pixels, inches, or centimeters. |
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
Name |
Required/Optional |
Data type |
Description |
---|---|---|---|
size |
Required |
VisRasterExportSize |
The raster export size. |
Width |
Optional |
Double |
The raster export size width. Must be greater than or equal to 1. |
Height |
Optional |
Double |
The raster export size height. Must be greater than or equal to 1. |
sizeUnits |
Optional |
VisRasterExportSizeUnits |
The units used to specify size. Can be pixels, inches, or centimeters. |
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
Property |
Type |
Applicable export formats |
Description |
---|---|---|---|
OLE_COLOR |
All |
Determines the background color that is applied to the exported image. |
|
BMP, JPG, PNG, or TIFF (depending on the property value) |
Determines the color format that is applied to the exported image. |
||
BMP, GIF, PNG, or TIFF |
Determines the color reduction that is applied to the exported image. |
||
BMP or TIFF (depending on the property value) |
Determines the data compression algorithm that is applied to the exported image. |
||
GIF or PNG |
Determines whether the exported raster image is interlaced or non-interlaced. |
||
All |
Determines the flip that is applied to the exported image. |
||
JPG |
Determines the export operation that is applied to the exported image. |
||
Long |
JPG |
Determines the export quality that is applied to the exported image. |
|
All |
Determines the rotation that is applied to the exported image. |
||
OLE_COLOR |
GIF or PNG |
Determines the transparency color that is applied to the exported image. |
|
Boolean |
GIF or PNG |
Determines whether Visio 2010 applies to the exported image the transparency color that is specified in the RasterExportTransparencyColor property. |
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.