What's New in GrapeCity Documents v6.1

We are pleased to announce GrapeCity Documents v6.1 release. This release adds new features to existing GrapeCity Documents controls and APIs. Have a look at the key highlights below!

The v6.1 release of GrapeCity Documents for Excel (.NET and Java), which includes the GrapeCity Documents DataViewer, is just around the corner. Stay tuned for more details on the latest features and improvements.

Ready to Check Out All Our New Features? Download GrapeCity Documents Today!

GrapeCity Documents for PDF (GcPdf)

New ClonePage method

Merging PDF documents has been possible before using GcPdf API - GcPdfDocument.MergeWithDocument method. With the v6.1 release, it will also be possible to clone a page within a PDF document. Use the new PageCollection.ClonePage(..) method to duplicate a page of a PDF at a certain index and place it at another index within the same PDF. You can also control whether to include annotations or form fields in the cloned page.

The following code can be used to clone pages. The first parameter specifies the index of the page that needs to be cloned, while the next one is the target index at which the cloned page will be inserted. The optional parameters cloneAnnotations and cloneFields are omitted here. They are true by default, so any annotations and fields will also be cloned.

GcPdfDocument doc = new GcPdfDocument();
using (var fs = new FileStream("realestate-lease-pdf.pdf", FileMode.Open, FileAccess.Read))
    doc.Pages.ClonePage(0, 1);

Cloned Document

View Help | Demo

GrapeCity Documents PDF Viewer (GcPdfViewer)

Introducing 'PDF Organizer'

GcPdfViewer introduces new 'PDF Organizer' dialog to help you organize PDF pages in the viewer. The tool can help -

  • Reorder individual pages or page ranges of a PDF
  • Duplicate or remove individual pages or page ranges
  • Rotate all or some pages of a PDF
  • Merge external PDFs into the current document
  • Split the current document into several PDFs
  • Download the modified PDF to your local file system, or apply changes and continue editing the document

The PDF Organizer also provides an API that allows you to access all of its functionality programmatically from code.

PDF Organizer

The following code splits a PDF into two:

// Split PDF into two documents:
viewer.save("test_part1.pdf", { pages: "0-3" });
viewer.save("test_part2.pdf", { pages: "4-8" });

Note: PDF Organizer is available in Quick Edit Page tools, Annotation, and Form Editor. This tool is available only in Professional Version. To add this tool to the viewer, you must configure Support API.

Help | Demo

Support range of magnifications for optional content group (layers)

PDF documents can contain content in different layers, also known as optional content. A particular layer can be made visible or invisible as required. GcPdf allows you to work with layers and set their properties; refer to Layers for more information. In GcPdf Viewer, you can examine these layers and show or hide content associated with each layer using the 'Layers' panel in its sidebar. 

According to the PDF 2.0 spec, groups of optional content layers in a PDF can be associated with specific ranges of magnifications (zoom values) at which they should be made visible in a compliant viewer. GcPdfViewer now supports this, so if a PDF that has such zoom-dependent layers is loaded into the viewer, the layers will be automatically shown or hidden depending on the current zoom factor.

Help | Demo

Display PDF with Initial View settings

GcPdfViewer supports the display of PDF documents with initial view settings. Additionally, the viewer provides viewerPreferences client-side API to get information about the initial PDF view settings set by a user and opens the PDF document in those settings, similar to Acrobat. You can use the following settings through code:

1. viewerPreferences: Gets the initial viewer preferences information set by a user.

    a. openAction: Gets the initial open action information set by a user.

    b. pageMode: Gets the initial page mode information set by a user.

    c. pageLayout: Gets the initial page layout information set by a user.

    d. hideToolbar: A flag specifying whether to hide the toolbars when the document is active.

    e. hideMenubar: A flag specifying whether to hide the menu bar when the document is active.

    f. nonFullScreenPageMode: Used to specify the full-screen mode.

Display PDF with Initial View settings

Help | Demo

Digital Signature API

Support for Document Signing API

You can now sign PDF documents using the new Client-side document signing API. The new ‘SignatureInfo’ class is introduced to specify the signature information needed to sign the document. To sign a document, you can specify contact info, location, signer name, reason, and signature field. The client-side ‘viewer.save’ method includes an optional SaveSettings parameter that can be used to specify signature settings or 'SignatureInfo' for saving a document with a signature.

The following client-side code causes the current PDF to be electronically signed using the new API (note: the actual signing takes place on the server, the client code tells the server to sign the PDF and reloads the signed document):

function configureViewerUI(viewer) {	
	viewer.toolbar.addItem({  text: "Apply employee signature", key: 'employee-signature', 
		title: 'Apply employee signature',enabled: false,
		action: function() {
			const locationName = location.hostname || "Unknown";
			viewer.save(undefined, { sign: { signatureField: "Employee", signerName: "Employee Name", location: locationName }, reload: true } );
		onUpdate: function() {
			return {
				enabled: viewer.hasDocument,
				title: 'Apply employee signature'

Digital Signature API

You can also find the server-side implementation of applying the .pfx certificate on the signature in the resources below.

Help | Demo

Check if a Document is Signed

GcPdfViewer allows you to check whether the current PDF is signed and, if so, which field was used to sign the document. The new asynchronous client-side method getSignatureInfo has been added for getting information about all signature fields available in a document. With the new method, you can -

  • Get signature information using the signatureInfo object
  • Test if the document is signed or not using signed property
  • Get the array of signature fields used to sign the document
  • Get the array of all signature fields in the document
  • Get Signature values using the signatureValue property like - signerName, location, and signedDate

The following code displays information about all signatures used in the document:

var viewer = GcPdfViewer.findControl("#root");
const signatureInfo = await viewer.getSignatureInfo();
if(signatureInfo.signed) {
  let s = "";
  for(let i = 0; i < signatureInfo.signedByFields.length; i++) {
    const signedField = signatureInfo.signedByFields[i], signatureValue = signedField.signatureValue;
    const signerName = signatureValue.name, location = signatureValue.location,
          signDate = viewer.pdfStringToDate(signatureValue.modificationDate).toDateString();
    s += `${i + 1}. Signed by field: ${signedField.fieldName}, signer name: ${signerName}, location: ${location}, sign date: ${signDate}\n`;
  alert("The document was signed using digital signature:\n" + s);
} else {
  alert("The document is not signed.");


See the complete usage of the signatureInfo method below.

Help | Demo

Save PDF Options

When saving a PDF, the GcPdfViewer’s save() method now allows you to save the document using incremental update (needed when signing an already signed PDF) or to save it as a linearized PDF file (optimized for fast internet viewing). The ‘viewer.save’ method has been enhanced with added optional SaveSettings class.

The SaveSettings class includes saveMode enum that can take in various save modes like ‘Default’, ‘Linearized’ and ‘IncrementalUpdate’.

viewer.save("test.pdf", { saveMode: "IncrementalUpdate" });

Help | Demo

GrapeCity Documents for Word (GcWord)

GcWord Templates

Enhanced Support of Using Multiple Expressions Within Aggregate Functions

In the last release, we added calculations to GcWord report templates using the new 'calc' templates feature, which allows using template data fields and literals in VBA-like expressions. Calc expressions support arithmetic, logical and other common operators, text and data aggregate functions, and more.

It will now be possible to use expressions as arguments of aggregate functions. The expression can use constants, aggregates, or two collections within the functions.

The following calculations are now possible:

  1. Using Constants - {{ calc Sum(2 + ds.value)}}
  2. Use Aggregates within Aggregate functions - {{ calc Average(ds.value+Sum(ds.value)/2)}}
  3. Using two collections within the functions - {{ calc Average(ds.value+ds2.value)}}

Look at the following invoice report, where the Total invoice Sum is calculated using multiple expressions within the Aggregate ‘Sum’ function.

Multiple Expressions Within Aggregate Functions

Help | Demo

Add Collection-Based State Functions

GcWord Templates now support the following collection state functions: IsFirst, IsLast, and Index, which can be applied to iterated ranges. These functions return the state of the current iteration over a collection. In your Word reports, you can implement scenarios like these -

  • Show only even elements of the collection
  • Show the number of elements and the current element
  • Check if a word is the first or last element in the collection
  • Insert a word at a certain location

The following code inserts a word at the end of a collection:

var p = doc.Body.Paragraphs.Add("{{if IsLast(ds)}} Employee List {{endif}} {{ds.value}}", doc.Styles[BuiltInStyleId.ListParagraph]);

Help | Demo

Support Linked Styles in Word (.docx) Files

This feature will allow developers to apply a linked style to both paragraphs or run in Word documents using the new GcWordDocument.Styles.AddLinkedStyle method. Also added is a boolean property HideLinkedCharacterStyles which can be used to hide linked character styles.

You can apply linked styles to the following API:

  • Run.Style - add a run and set the linked style to it
  • ContentControl.Style - set the linked style to content control
  • FormattedMark.Style - set the linked style to a paragraph’s mark (a glyph used to represent the physical location of the paragraph mark for a paragraph)
  • FindFormatting.Style - create find options and set the linked style to it

The following applies a common linked style to a paragraph and part of a paragraph, i.e., a run. Notice that the linked style is reflected in MS Word’s styles list.

GcWordDocument doc = new GcWordDocument();
doc.HideLinkedCharacterStyles = false; // change default value

// create linked style
Style linkedStyle = doc.Styles.AddLinkedStyle("Linked Style", doc.Styles[BuiltInStyleId.Heading1]);

// change linked style formatting (reflects on both linked styles)
linkedStyle.Font.Bold = true;

// apply linked style to paragraph
doc.Body.Paragraphs.Add("Paragraph formatted with paragraph linked style", linkedStyle);

// apply linked style to run
Paragraph paragraph = doc.Body.Paragraphs.Add("Paragraph ", doc.Styles[BuiltInStyleId.Normal]);
Run run = paragraph.GetRange().Runs.Add("formatted with character linked style", linkedStyle);

// switch HideLinkedCharacterStyles property
doc.HideLinkedCharacterStyles = true;


Support Linked styles in Word (.docx) files

Help | Demo

Support for 3-D Effects in Shapes and Fonts

GcWord now supports 3-D effects for shapes and fonts in the API.

The TextFrameFormat and Effects class of GcWord is extended to support ThreeDFormat and ThreeDScene effects.

ThreeDFormat class sets 3-D Format properties on Font or Shapes.

ThreeDScene class applies 3-D scene effects on objects like Lighting, Camera, Backdrop, etc.

Font, Shape, GroupShape, and Picture classes have the new ApplyEffectsPreset method to set built-in effects for text and shapes.

The following snapshot shows 3-D Format settings on text reflected in generated Word document:

Support for 3-D Effects in Shapes and Fonts

The following snapshot shows 3-D Format and 3-D Rotation settings applied on a shape which reflects in generated Word document:

3-D Format and 3-D Rotation settings

Help | Demo

Support for Effects When Exporting Word (.docx) Documents to PDF and Images

In the last release, we introduced adding various effects to shapes. These effects will now be supported when exporting Word (.docx) documents to PDF and Images.

GrapeCity Documents for Imaging (GcImaging)

Support for Gaussian Blur Effect in GcBitmap

Use the Gaussian Blur effect to create a blur based on the Gaussian function over the entire input image or part of the image. It is a widely used effect in graphics software, typically to reduce image noise and detail. The visual effect of this blurring technique is a smooth blur resembling that of viewing the image through a translucent screen. To apply the Gaussian Blur effect using GcImaging, create an instance of that class using the static GaussianBlurEffect.Get method, then pass it to the ApplyEffect method of GcBitmap class.

The effect is applied to either the whole GcBitmap or to a rectangular fragment of the image. The ApplyEffectmethod accepts the optional parameter specifying the target rectangle. The GaussianBlurEffect.Get method accepts the parameter - radius of the blur, which specifies the standard deviation of the Gaussian distribution as follows: sigma = radius / 3. When a blur effect is applied, the color of each pixel blends with all surrounding pixels at the distance of “radius” (pixels) in the X and Y direction.

The following code applies the Gaussian Blur effect on an image with a dark frame around it:

using GrapeCity.Documents.Imaging;

using var bmp = new GcBitmap("door.jpg");

Gaussian Blur

There are several scenarios you can apply with this support in GcImaging:

  • Blur an image with a frame around the image (specified by the radius of blur)
  • Blur an image with a specified colored frame around it
  • Blur just a part of the frame
  • Blur an image with a specified colored frame around it, together with the outer border color, using the GaussianBlurBorderMode.BorderColor parameter
  • Pass a GaussianBlurBorderMode.Wrap parameter to GaussianBlurEffect.Get method to change the output image
  • and many more..

Help | Demo

New Methods to Check If Image Pixels Are Black or White

GcImaging adds IsBlackAndWhite and IsGrayscale in GcBitmap class. These methods make it faster to check whether the image consists of black and white pixels or just shades of gray. The IsBlackAndWhitemethod checks whether all image pixels are either opaque black or opaque white. The IsGrayscale method checks whether all pixels of GcBitmap are shades of gray, i.e., their alpha channel is set to 0xFF (fully opaque), and their red, green, and blue channels have the same value.

Have a look at the following resources to learn more about the feature.


Draw Images with Shadow

GcImaging adds ApplyGaussianBlur and ToShadowBitmap methods in GrayscaleBitmap class to draw images with shadow. The ApplyGaussianBlur method with two overloads applies Gaussian blur to a grayscale bitmap. In addition, you can specify a border color which is the assumed level of opacity (from 0 to 255) for the pixels surrounding the image. The ToShadowBitmap also has two overloads, drawing transparency mask into an existing bitmap. With this method, you can specify a shadow color and an opacity factor. You can apply shadow on text or graphics.

The following code applies the Gaussian blur and shadow on a text. The code first converts the bitmap to grayscale, applies the Gaussian blur, draws the grayscale bitmap’s transparency mask into the existing bitmap object, and adds shadow on the bitmap accepting the bitmap, shadow color, and opacity.

using var bmp = new GcBitmap(800, 600, false);
using (var g = bmp.CreateGraphics(Color.Transparent))
//see demo for full code 
    Draw(g, 20, 50);

using var gs = bmp.ToGrayscaleBitmap(ColorChannel.Alpha);
gs.ToShadowBitmap(bmp, Color.CadetBlue, 0.5f);


using (var g = bmp.CreateGraphics())
    Draw(g, 0f, 0f);


Draw images with shadow

There are many other scenarios that you can achieve with these methods, for example, applying the Gaussian blur and shadow on other graphic objects. Have a look at the following resources for full code.

Help | Demo

Apply Glow and Soft Edges Effect on Text and Graphics on Grayscale Bitmap

With GcImaging, you can apply glow and soft edges effect on grayscale bitmap using the GrayscaleBitmap.ApplyGlow method takes in a radius of glow inflation (positive value) or deflation (negative value) and a blur radius. The glow and soft edges effects are similar to those in MS Word.

The following code applies glow and soft edges on graphics. For full code, see the demo here.

//Glow effect
using (var gs = bmp1.ToGrayscaleBitmap(ColorChannel.Alpha))
    gs.ApplyGlow(10, 20);
    gs.ToShadowBitmap(bmp1, Color.Aquamarine, 0.6f);

//Soft Edges effect
 using var gs = bmp.ToGrayscaleBitmap(ColorChannel.Alpha);
gs.ApplyGlow(-5, 7);

The image below depicts Glow Effect applied to graphics and text.

Glow Effect applied to graphics and text

Help | Demo - Glow | Demo Soft Edges

Line Breaking and Justification Settings in Text

GcImaging introduces LineBreakingRules and WordBoundaryRules properties in TextLayout class that allow the user to switch from the standard Unicode line-breaking/text segmentation algorithms to more simplified rules reproducing the behavior of the text renderer in GDI+ or the line-breaking rules in MS Excel. It is often helpful to avoid full-fledged algorithms from the Unicode standard when processing structured text data, for example, in XML format.

GcImaging also introduces the TextExtensionStrategy property to justify the text when TextLayout.TextAlignment property is set to either Justified or Distributed. The property offers enum values as Default, Normal, EastAsianExcel, and Excel, depending on whether the property value permits text extension for wide characters and white spaces or for white spaces only. 

The following snapshot shows text with simple and Unicode LineBreakingRule and TextExtensionStrategyExcel.

Text with simple and unicode LineBreakingRule

 var tl = g.CreateTextLayout();
 tl.LineBreakingRules = LineBreakingRules.Simplified;
 tl.WordBoundaryRules = WordBoundaryRules.Simplified;
 tl.TextExtensionStrategy = TextExtensionStrategy.Excel;
 var text = "abcdefg!1010101010abc;999999本列島で使され99 555";


Help | Demo

GrapeCity Documents Image Viewer (GcImageViewer)

Crop and Resize toolbars

You can now easily crop and resize images using the crop and resize options now present in the toolbar. The following options can be applied:

Crop Tool

Crop Tool

  • Custom aspect ratio
  • Crop at X/Y Coordinates
  • Crop with Image Width or Height
  • Use Apply or Cancel options

Resize Tool

Resize Tool

  • Keep aspect ratio (boolean)
  • Set the Width and Height of resized image
  • Use Apply or Cancel options

Help | Demo

Select/copy/search text content of SVG images

SVG can contain text elements, which are not images but real text. This text can now be selected, copied, or searched when the SVG image is displayed in the viewer.

Select SVG

Help | Demo

GcPdf, GcImaging

InterpolationMode Moved to GcGraphics

InterpolationMode property can now be set using the GcGraphics object. The property is also added to SaveAsImageOptions class when saving PDFs to images. The property now allows you to control interpolation mode in a similar manner for all implementations of GcGraphics, i.e., format-specific types of graphics such as GcPdfGraphics, GcBitmapGraphics, GcSvgGraphics, GcSkiaGraphics, GcWicBitmapGraphics, GcD2DBitmapGraphics.

GcPdf supports the InterpolationMode property in the SaveAsImageOptions class, which will be utilized to set interpolation mode while drawing images in PDF files or saving the PDF files as images. The default value of SaveAsImageOptions.InterpolationMode is InterpolationMode.Downscale.

Note: The interpolation mode only affects how raster images are drawn on a graphic, i.e., the result of the DrawImage method and raster image resizing.

The following code helps to set interpolation mode while saving the GcPdfDocument object to the image:

// set the interpolation mode when saving a PDF document to the image
SaveAsImageOptions opts = new SaveAsImageOptions();
opts.InterpolationMode = InterpolationMode.Linear;
doc.SaveAsPng("doc.png", null, opts);

The following code helps to set interpolation mode while drawing images on graphics using GcImaging:

// Load the image.
using var origBmp = new GcBitmap();
using (var stm = File.OpenRead(Path.Combine("Resources", "ImagesBis", "QRCode-57x57.png")))

// Enlarge and draw four copies of the image using the four different available interpolation modes.
using (var bmp = origBmp.Resize(twidth, theight, InterpolationMode.NearestNeighbor))
targetBmp.BitBlt(bmp, ip.X, ip.Y);
drawCaption("InterpolationMode.NearestNeighbor", ip.X, ip.Y + theight);


Help - GcPdf | Help - GcImaging | Demo - GcPdf 

New Layout Engine With a Flat Hierarchy to Draw Complex Layouts

GrapeCity Documents introduces a new layout engine that adds LayoutRect and other related classes in the GrapeCity.Documents.Layout namespace to implement a layout model based on constraints and a flat hierarchy of elements without obvious parent-child relations. With GcImaging API, there are no guidelines or other complications to drawing complex layouts. The new layout engine allows you to position and size elements flexibly.

There are various constraints that are supported to draw such layouts. A constraint represents a connection between two rectangles or a rectangle and its owner LayoutView. You can apply various constraint types with GcImaging. Please refer to the following features supported:

  • Simple Position Constraints
  • Chained Position Constraints
  • Min/Max Position Constraints
  • Anchor Points
  • Constraints based on other views
  • Dependent Views and Transformations
  • Contours

The following is an example of nested LayoutViews with different transformations.

Nested View

You can learn more about these Constraints in the following resources.


Draw a Table Using the New TableRenderer Class

The New TableRenderer class is added to render table layouts on PDF and images. With this class, you won’t need to know the size of table columns, merged cells, or the layout of rotated text. All complex details of table resizing are automatically adjusted by the layout engine. You must provide information about the desired layout, style, and content.

TableRenderer class is built on top of the new layout engine described in the topic before. LayoutHost, LayoutView, and LayoutRect provide the initial space for the TableRenderer. All table rows, columns, vertical and horizontal grid lines, and cells have the associated LayoutRect objects.

A TableRenderer instance takes multiple parameters. Please refer to the API for details of each parameter.

The following is the basic definition of defining a table using TableRendererAPI class.

var ta = new TableRenderer(
    tableRect, FixedTableSides.TopLeftRight,
    rowCount: 5,
    columnCount: 4,
    gridLineColor: Color.Coral,
    gridLineWidth: 3,
    rowMinHeight: 30);


You can also add cells to the table and add text to it using AddCells(..) method that accepts data as a parameter. Also included is the AddMissingCells(..) method that ensures no gaps around the cells and accepts data as a parameter.

Overall, with the various options in the new API, you can create a table with many complex layouts, one like the one below:

Draw Table using new TableRenderer class

The following are certain scenarios you can cover with TableRenderer API:

  1. Draw simple tables or tables with complex layout
  2. Merge table cells
  3. Rotate or set the flow direction of text in cells
  4. Draw custom content in the cell

Here are some detailed demos to check various codes on how to draw tables with different layouts.

Help - GcPdf | Help - GcImaging | Demo - GcPdf | Demo - GcImaging

What do you think about the new features? Leave a comment and let us know.

Ready to Check Out All Our New Features? Download GrapeCity Documents Today!

comments powered by Disqus