Rendering in Aspose.Words
The rendering feature in Aspose.Words allows to:
- Convert any document or selected pages to PDF.
- Convert any document or selected pages to XPS.
- Convert any document or selected pages to SWF.
- Convert any page of a document into a raster image and save as BMP, PNG or JPEG.
- Convert any document or some pages into a multipage TIFF document.
- Convert any page of a document into a vector image and save as EMF.
- Convert any page of a document into a Scalable Vector Graphics image (SVG).
- Render (draw) any page of a document to a specified size or scale on the .NET Graphics object to create thumbnails, full sized or scaled images of document pages.
- Render (draw) any Shape object separately from the document to any raster or vector image format or to a .NET Graphics object.
- Display any page of a document in a Windows Form.
- Print or preview document pages using the standard .NET printing infrastructure.
All of the document formats that can be loaded into Aspose.Words are known as “flow-layout” formats. Flow-layout formats include DOC, OOXML, RTF, ODT, HTML. Documents in these formats consist of various elements e.g. paragraphs, tables, headers, footers, images, fields and their formatting e.g. bold, italic, font, size etc. However, the flow-layout formats do not contain information that specifies where on a page each particular paragraph or character is displayed.
To contrast, the “fixed-layout” formats, such as PDF and XPS, preserve the appearance of a document after it was laid out into pages so the viewing fidelity is preserved.
Aspose.Words implements its own page layout engine that takes a flow-layout document and formats it out into pages. Then, Aspose.Words implements a number of renderers that either produce a fixed-layout document, such as PDF or XPS or output pages into another medium, such as printing or drawing.
The most important advantage of the Aspose.Words page layout engine is that it tries to mimic the way the Microsoft Word’s page layout engine works. To you, this means that if you convert a Microsoft Word document into PDF, XPS or print it using Aspose.Words, the output will appear almost exactly as if it was done by Microsoft Word. But of course Aspose.Words does not utilize Microsoft Word.
How to Save Document as a Multipage TIFF
One of the useful things you may need to do with your document is a conversion to image file(s). For example if you have to present your document in a readable and printable but not editable format (e.g. for publication on the Web). One of the simple approaches you could use is a conversion to a multipage TIFF file.
Solution: Converting DOC to Multipage TIFF
In Aspose.Words such task can be performed literally by one line of code by simply passing the path of where to save including the file extension to the Document.Save method. The Document.Save method automatically derives the SaveFormat from the extension specified in the filename passed to it. Below example convert document to TIFF.
DOC to Multipage TIFF Result
All pages rendered by Aspose.Words to the TIFF format are shown side by side below. In the actual file each page of the document is rendered to one frame in the TIFF file.
Solution: Controlling the Output
Often you may also require specifying certain options with regards to how documents are rendered to image. The Document.Save method has overloads that accept an object of a class derived from the SaveOptions class. In this case we should pass an object which derives from the ImageSaveOptions class in order to control the options used for rendering. This class contains the properties which define the how a document is rendered to an image.
- Create a new instance of the ImageSaveOptions class and pass the SaveFormat type of the image type to be rendered. In this case we pass SaveFormat.Tiff to produce a TIFF image.
- Set the options that control how the document will be rendered, such as ImageSaveOptions.PaperColor .
- Pass the ImageSaveOptions object to one of the several Document.Save overloads that accept a SaveOptions object.
Below code sample convert to TIFF using customized options
There are many properties available in the ImageSaveOptions class which allows control over how the image is rendered. The ones that appear in this sample are discussed in detail below.
- The ImageSaveOptions.PageIndex property can be set to specify the start page to be rendered using the 0-base number format. For instance, in a three page document the first page would be referenced by the index “0” while the last page would be referenced by the index “2”. By default this property is set to “0”
- The ImageSaveOptions.PageCount property specifies the number of pages to convert. If you save a TIFF file and this parameter is greater than 1 then a multipage TIFF file will be created. If you save multiple pages in a format other than TIFF, i.e in JPEG format, then only the first page will be rendered. By default this is set to the total number of pages in the document.
- The ImageSaveOptions.Resolution property can be set to specify which resolution the document is rendered to. This setting affects any image format being rendered to. By default this is set to 96.
- The ImageSaveOptions.TiffCompression properly sets which compression method to apply when saving to the TIFF format. By default this is set as TiffCompression.Lzw
Controlling Output Result
The same document that was rendered at the beginning of this article has now been rendered using custom options as specified. The output is shown below.
How to Save Document's Page to Image with Horizontal and Vertical Resolution
The ImageSaveOptions class allows you to specify a variety of options which control how the image is rendered. ImageSaveOptions.HorizontalResolution and ImageSaveOptions.VerticalResolution are used to set and get the horizontal and vertical resolution for the generated image. Following code example shows how to set these properties for the generated image.
How to Specify the Default Font to use when Rendering
Aspose.Words requires access to TrueType fonts in order to properly render documents with high fidelity just as they appear in Microsoft Word. If a font is missing during rendering, Aspose.Words will not cause any error; instead the closest font is picked as a replacement to substitute for the missing font. This will produce a document that appears almost perfect; however the appearance of the text may be slightly different as the exact identical font in the original document is not being used.
Aspose.Words provides a setting to define what default font is used in this situation. Use this setting in situations such as:
- You want to generally specify the default font to fall back on if particular font in a document cannot be found during rendering.
- Your document uses fonts that non-English characters and you want to make sure any missing font is replaced with one that has the same character set available.
Default Font to Use Solution
Aspose.Words provides a static class called FontSettings that can be used to define the default fonts when rendering any document. This class caches fonts of documents when they are rendered using Aspose.Words. It also provides members to control how and where Aspose.Words looks for fonts. To specify the default font, we use the FontSettings.SubstitutionSettings.DefaultFontSubstitution.DefaultFontName property.
Default Font to Use Code
We have a simple program which takes a word document and converts it to PDF. This is achieved by loading the document into the Aspose.Words Document class and calling the Document.Save method with a “.pdf” extension. We can specify the default font to use by applying FontSubstitutionRule using the FontSubstitutionSettings by calling the FontSettings.SubstitutionSettings.DefaultFontSubstitution.DefaultFontName property before the document is rendered. Below example demonstrates how to specify what font to substitute for a missing font during rendering. You can download the template file of this example from here.
In a future version, we will provide a call back to allow specific fonts to be chosen dynamically, based on the font information such as font name or font type. This will further allow you to control how missing fonts are substituted. If you want to vote for such an option, please leave us some feedback through a comment on this page.
Enable or Disable Font Substitution
There are scenarios when you want to disable font substitution, you can use FontSettings.SubstitutionSettings.FontInfoSubstitution.Enabled property in such cases. Note that if a font substitution is disabled, Aspose.Words uses the DefaultFontName for the substitution of missing fonts. If font substitution is enabled, Aspose.Words evaluates all the related fields in FontInfo (Panose, Sig etc) for the missing font and finds the closest match among the available font sources. Note that the font substitution mechanism will override the DefaultFontName in cases when FontInfo for the missing font is available in the document. Below code example shows how to disable font substitution.
How to Specify How Fonts are Embedded in Adobe PDF Format
Fonts need to be embedded into any Adobe PDF document to ensure the document can be correctly read on any machine. By default, Aspose.Words embeds a subset of fonts used in the document into the generated PDF. This means only the glyphs (characters) that were used in the document being rendered are actually saved to the PDF.
When to Use Full Fonts and when to Subset?
There is a way to specify Aspose.Words to embed full fonts. Further details, along with the advantages and disadvantages of each setting is described in the table below.
Embed Fonts Mode
The PdfSaveOptions.EmbedFullFonts property is provided to specify how Aspose.Words embeds fonts into an output PDF document.
- Set PdfSaveOptions.EmbedFullFonts to true to embed full fonts into the output PDF document.
- Set PdfSaveOptions.EmbedFullFonts to false to subset fonts when saving to PDF.
The code below demonstrates how to create a new instance of the PdfSaveOptions class and specify the EmbedFullFonts property to control how fonts are embedded. Both examples of full font embedding and subsetting are provided. Below example demonstrates how to set Aspose.Words to embed full fonts in the output PDF document. You can download the template file of this example from here.
Below example demonstrates how to set Aspose.Words to subset fonts in the output PDF.
How to Control Embedding of Core and Windows Standard Fonts
Core fonts and Windows Standard fonts are sets of fonts that are “standard” and therefore are deemed common enough that to already be present on the target machine or provided by the reader that they do not need to be embedded in the output PDF. By not embedding these fonts, it helps to decrease the size of rendered PDF documents while still maintaining portability.
Aspose.Words provides options to choose how fonts are exported to PDF. You can choose to embed core and standard fonts into the output PDF or to skip embedding them and use standard core PDF fonts or system installed fonts on the target machine instead. Using either one of these options normally results in significant reduction in the file size of PDFs generated by Aspose.Words.
Embed Core Fonts
This option can be enabled or disabled by using PdfSaveOptions.UseCoreFonts property. When set to true, four of the most popular “True Type” fonts (Base 14 fonts) are not embedded in the output PDF document. They are replaced with corresponding core Type 1 fonts which are provided by the reader when the PDF is opened. These fonts are:
- Times New Roman
- Courier New
Below example shows how to set Aspose.Words to avoid embedding core fonts and let the reader substitute PDF Type 1 fonts instead. You can download the template file of this example from here.
Embed System Fonts
This option can be enabled or disabled by using the PdfSaveOptions.EmbedStandardWindowsFonts property. When this property is set to false, true type “Arial” and “Times New Roman” fonts are not embedded into PDF so the client viewer is forced to rely upon the fonts which are installed on client operating system. Below example shows how to set Aspose.Words to skip embedding Arial and Times New Roman fonts into a PDF document.
OOXML Chart Rendering Supported Features
This topic contains the features supported when rendering OOXML charts to fixed page formats.
Level of support
Area 3D Chart
Line 3D Chart
Pie 3D Chart
Bar 3D Chart
Of Pie Chart
Surface 3D Chart
Level of support
Rendering of chart legend is supported including custom formatting and manual layout.
Rendering of chart title is supported including custom formatting and manual layout.
Rendering of axis tiles is supported.
Data labels are rendered. Almost all features of data labels are supported.
Currently data table is not rendered. (WORDSNET-6943)
Rendering of trend lines is supported.
Rendering of error bars is supported.
Pictures, Shapes, Textboxes
Rendering of Pictures, Shapes and Textboxes are supported.
Level of support
There are 48 chart styles, these styles define the formatting of chart elements. All styles are supported and used as a default source of chart elements formatting upon rendering.
Series formatting specifies formatting of all data points within this series and overrides formatting applied to them using chart style.
Fill and borders of the plot area are supported.
Fill and borders of chart area are supported.
Using data point formatting you can override formatting of a concrete data point.
Custom fill and line formatting for the legend is supported.
Custom font formatting is supported.
You can drag and drop chart elements on the chart area. In this case, elements become absolutely positioned.
Overlapping of elements within the chart area is supported.
How to Hyphenate Words of Specified Languages
By default, if a word is too long to fit on the end of a line, Aspose.Words moves it to the beginning of the next line instead of hyphenating it. However, the hyphenation feature can be used to insert hyphens into words to eliminate gaps in justified text or to maintain an even line length in narrow columns.
Loading Hyphenation Dictionaries
To use the hyphenation feature, first register a hyphenation dictionary. The code example below shows how to load hyphenation dictionaries for specified languages from file. You can download the template file of this example from here.
The code below shows how to load a hyphenation dictionary for a specified language from a stream. You can download the template file of this example from here.
Escape the URI in Output PDF
If you want to escape the URI before writing it into PDF, you can use PdfSaveOptions.EscapeUri property. Note that if this option is set to false hyperlinks are written "as is", so valid (escaped) URI should be provided in document's model. Below code example shows how to use this property.
Export Bookmarks in Output PDF
If you want to export bookmarks in output PDF, you can use OutlineOptions.DefaultBookmarksOutlineLevel property. This property specifies the default level in the document outline at which to display Word bookmarks. If the document contains the bookmarks in the header/footer of the document, you can use PdfSaveOptions.HeaderFooterBookmarksExportMode property to specify how they are exported in output PDF. The bookmarks in headers/footers are not exported when HeaderFooterBookmarksExportMode is None. Below code example shows how to export bookmarks in the header/footer of the first section.
Working with Layout Options
LayoutOptions class holds the options that allow controlling the document layout process. You do not create instances of this class directly. Use Document.LayoutOptions property to access layout options for this document. Note that after changing any of the options present in this class, Document.UpdatePageLayout method should be called in order for the changed options to be applied to the layout. Below code example shows how to disable comments from rendering.
Below code example shows how to render revisions in the balloons.
WMF Fonts Scaling According to Metafile Size on the Page
If you want to control the scaling of fonts in WMF meta-file according to meta-file size on the page, you can use MetafileRenderingOptions.ScaleWmfFontsToMetafileSize property. Aspose.Words emulates font scaling according to meta-file size on the page when the value of this property is true and displays the fonts as meta-file is rendered to its default size when its value is false. Note that this property is used only when meta-file is rendered as vector graphics. Below code example shows how to use it.
Control Threshold for TIFF Binarization
When a document is converted to TIFF file format, you can control the threshold for TIFF binarization by using ImageSaveOptions.ThresholdForFloydSteinbergDithering property. The default value of this property is 128. The higher the value, the darker the image. Below code example shows how to use this property.