Skip to main content Skip to footer

What's New in Documents for Word v6

GcWord v6.2 -August 9, 2023

GrapeCity Documents for Word (GcWord)

Support for Office Math functions and conversion to MathML

GcWord now supports creating and editing Office Math content in Word documents. The OMath support in GcWord includes complete API to work with mathematical symbols, formulas and equations widely used in scientific, mathematical and general purpose Word documents. Following are key highlights of new API introduced with OMath support -

  • The two main classes used to represent Office Math content in GcWord are OMathParagraph and OMathOMathParagraph represents a paragraph with Office Math content, while OMath represents an inline Office Math zone, and can be included in an OMathParagraph or in a regular paragraph.

  • Specialized classes (such as OMathFunctionOMathEquationArrayOMathRadical, etc.) are provided to represent the various math structures living inside an OMath zone. These classes are derived from the common abstract OMathStruct base.

  • Access to Office Math content is provided by the new RangeBase properties: OMathParagraphsOMathsOMathStructsOMathElements and OMathMatrixRows.

  • To easily add built-in equations supported by MS Word, convenient Add/Insert methods are provided on RangeBaseOMathParagraphOMath and OMathElement classes accepting an OMathBuiltInEquation enum value identifying the desired equation.

  • A utility MathMLConverter class is included to allow for easy conversion between GcWord OMath content and MathML.

For the full details on OMath support in GcWord, please see the documentation.

Following code adds an equation to Word file with OMath class and it’s functions.

var sampleDoc = new GcWordDocument();
var om = sampleDoc.Body.AddParagraph().AddOMathParagraph().AddOMath();

om.AddRun("Γ").Font.Italic = false;
om.AddDelimiter(new string[] { "z" });

var nary = om.AddNary("", "0", "∞", "∫");
nary.Base.AddSuperscript("t", "z-1");
nary.Base.AddSuperscript("e", "-t");

var frac = om.AddFraction();
var superscript = frac.Numerator.AddSuperscript("e", "-");
superscript.Superscript.AddRun("γ").Font.Bidi = true; //w:cs was used

nary = om.AddNary("", "k=1", "∞", "∏");
superscript = nary.Base.AddSuperscript("", "-1");
var delimiter = superscript.Base.AddDelimiter();
var item = delimiter.Items.Add();
item.AddFraction("z", "k", null);

superscript = nary.Base.AddSuperscript("e", "z");
superscript.Superscript.AddRun("/").OMathFormat.IsLiteral = true; //m:lit used.

om.AddRun(",  γ≈0.577216");


Support for Office Math functions and conversion to MathML - .NET Word DOCX API

Help | Demo

New helper ‘Add<content object>(..)’ methods to add content to Word documents.

Till now, it was possible to add content objects in Word documents in one or more ways. For example - It was possible to add ‘runs’ of a paragraph either by paragraph creation constructor call - doc.Body.Paragraphs.Add(“text“) or using paragraph.GetRange().Runs.Add(…) and creating paragraph before this call. However, with v6.2 release it will now be possible to create runs directly on paragraph element using new ‘AddRun(..)’ method.

Similarly, GcWord adds ‘Add<content object>(..)’ methods to each kind of content in Word documents so that they can be directly added to their parent object making the code shorter and more effiicient. Each of these objects can now be directly added to different sections or content objects in Word documents using new Helper methods -

  • Table

  • Paragraph

  • ContentControl

  • SimpleField

  • Hyperlink

  • BidirectionalOverride

  • OMathParagraph

  • OMath

  • Run

  • Footnote

  • Endnote

  • ComplexField

  • GroupShape

  • Shape

  • Picture

  • InkShape

Have a look on the following code that adds a paragraph run to a paragraph with the new method ‘AddRun(..)’ -

GcWordDocument doc = new GcWordDocument();
// add paragraph with default formatted text
var p = doc.Body.AddParagraph("text1");
// add another text into the paragraph formatted with "Heading1" style
// previously code should look like: p.GetRange().Runs.Add("text2", doc.Styles[BuiltInStyleId.Heading1]);
// now the code is shorter and more clear what content can be added into the object
 p.AddRun("text2", doc.Styles[BuiltInStyleId.Heading1]);


Have a look on following resources to see complete list of newly supported helper methods.

Help | Demo - Built-in Table Styles | Demo - Nested Table Helpers | Demo - Hyperlink Fields Helpers | Demo - Content Controls Helpers

Escape template tags in GcWord Templates

If you want to prevent a particular data template tag from being processed by the data template engine (i.e. quote it literally in your document after template expansion), insert a backslash before the tag’s opening double curly brace.

The following code snippet shows how to escape tags that would otherwise print the data values:

var dsPoint = new string[] { "2.2", "3.3", "4.4" };
var doc = new GcWordDocument();
doc.DataTemplate.DataSources.Add("dsPoint", dsPoint);

Additionally, in order to use backslashes before a template tag without disabling the template processing, GcWord allows you to insert two or more backslashes, depending on how many backslashes are needed. It will remove one backslash from prepending backslashes when processing template tags.

Following code adds double-slash to template syntax. This would add a single backslash in resultant Word file when the template syntax is processed:

var dsPoint = new string[] { "2.2", "3.3", "4.4" };

var doc = new GcWordDocument();
doc.DataTemplate.DataSources.Add("dsPoint", dsPoint);


GcWord v6.1 -April 19, 2023

GcWord Templates

Enhanced support of using multiple expressions within aggregate functions

In 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.

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)}}

Have a look on following invoice report, where Total invoice Sum is calculated by using multiple expression within the Aggregate ‘Sum’ function.

Enhanced support of using multiple expressions within aggregate functions within Word Templates

Help | Demo

Add collection-based state functions

GcWord Templates now support the following collection state functions: IsFirst, IsLast, Index that 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 collection.

  • Show number of elements and current element.

  • Check if a word is first or last element in the collection.

  • Insert a word at certain location.

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 linked style to both paragraphs or runs in Word documents using 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 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

Following applies a common linked style to a paragraph and part of paragraph i.e. a run. Notice 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;


Programmatically set Linked styles in Word (.docx) files - GrapeCity Documents for Word

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 effect on objects like Lighting, Camera, Backdrop etc.

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

Following snapshot shows 3-D Format settings on text which reflect in generated Word document.

Support for 3-D Effects in Shapes and Fonts in Programmatically Generated Word Documents (.docx)

Following snapshot shows 3-D Format as well as 3-D Rotation settings applied on a shape which reflect in generated Word document.

3-D Rotation settings applied to graphics is programmatically generated word documents

Help | Demo

Support for Effects when exporting Word (.docx) documents to PDF and Images

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


GcWord v6 -December 15, 2022

Conditionally show/hide multiple blocks of data

GcWord Report Templates adds new ‘if/else/endif’ statements to define conditions to show/hide whole block or multiple blocks at once. The condition defined is a set of template value operands combined with arithmetic or logic operations. Consider the following example, which shows retainer information from a Consulting Agreement document with a single if/endif condition (shows retainer information if payRetainer=1) instead of hiding specific blocks previously using hbi statements.

Conditionally show and hide blocks of data in a Word .docx template using a .NET Word API

View Help | Demo

Add calculations to Word Templates

You can now add calculations to GcWord report templates using the new 'calc' templates feature, which allows you to use 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.

Some examples of valid 'calc' expressions include:

   {{ calc 2 * 2 + 4 }}

   {{ calc ds.UnitPrice * ds.Quantity }}

   {{ calc Sum(ds.Price) }}

   {{ calc Max(ds.Price) }}

Also, calc and the new conditional construct can be used together, enabling complex conditions under if, e.g.

{{ if useLimit and Sum(ds.score) > limit }} you passed {{ else }} you failed {{ endif }}

Consider the following example where the Invoice report adds the total price of all items in the report using calc expression.

View Help | C1CalcEngine (GcWord uses C1CalcEngine for calculations) | Demo

Support for effects in shapes and font

Reflection Effect

GcWord adds Reflection class with detailed properties to apply reflection effect on shape or text. The effect looks like a water effect on the shape or text. You can set custom properties for Reflection effect through TextEffects, ShapeEffects or FormatScheme classes using ApplyBuiltInReflection method which can set one of 9 types of built-in reflection effects on text or drawing object. In addition, you can also set Reflection effect to shapes directly through Shape.Effects.Reflection property.  

The following code adds a ‘HalfTouching’ reflection effect on the title:

  GcWordDocument doc = new GcWordDocument();
  var style = doc.Styles.Add("My Style", StyleType.Paragraph);
  style.Font.Size = 48;
  // apply top half touching reflection effect to the text
  doc.Body.Paragraphs.Add("Wetlands", style);

View Help Text Effects | Shape Format | ShapeStyles | Demo

Glow Effect

This effect adds a hazy color perimeter outside the shape area or text. You can directly set the glow effect using shape.Effects.Glow property or use ApplyBuiltInGlow method of TextEffects, ShapeEffects class to set one of 24 types of built-in glow effects on text or drawing objects.

The following code adds the glow effect directly using the ApplyBuiltInGlow method:

var style = doc.Styles.Add("My Style", StyleType.Paragraph);
style.Font.Size = 48;
style.ParagraphFormat.Alignment = ParagraphAlignment.Center;
// apply 5 point accent 2 glow effect to the text
doc.Body.Paragraphs.Add("Wetlands", style);

View Help Text Effects | Shape Format | ShapeStyles | Demo

Blur Effect

To make certain shapes used in your Word document content stand out, GcWord adds the ability to add a blur effect. The ShapeEffects class is extended with the new Blur class. You can also set the Blur effect using FormatScheme class of Shape.

The following code uses a direct method of shape.Effects.Blur class to set blur effect on Shape.

Shape shape = run.GetRange().Shapes.Add(100, 100, GeometryType.Star4);
shape.Fill.Type = FillType.Solid;
shape.Fill.SolidFill.RGB = Color.Yellow;
shape.Line.Width = 4;
shape.Line.Fill.SolidFill.RGB = Color.Red;
// apply 7 point blur effect to the shape
shape.Effects.Blur.Radius = 7f;

View Help Shape Format | ShapeStyles | Demo

Soft Edge effect

GcWord adds another way to add artistic effect to your shapes programmatically in Word documents. The ShapeEffects class has been extended with the SoftEdge class. The soft edge effect is a subtle blur on the shape's edges. It can be applied through a SoftEdge.Radius value. The soft edge effect can be applied directly through Shape.Effects class of Shape class or FormatScheme class.

The code below applies the soft-edge effect to shape through shape style properties.

Shape shape = run.GetRange().Shapes.Add(100, 100, GeometryType.Star7);
shape.Fill.Type = FillType.Solid;
shape.Fill.SolidFill.RGB = Color.Yellow;
shape.Line.Width = 8;
shape.Line.Fill.SolidFill.RGB = Color.Red;
// apply 5 point soft edge effect to the style
var fmtEffect = doc.Theme.FormatScheme.Effects.Add();
shape.Style.Effects.ThemeEffects = fmtEffect;

View Help Shape Format | ShapeStyles | Demo

Fill Overlay Effect

A fill overlay can be used to specify an additional fill for an object and blend the two fills together. GcWord adds a fill overlay effect that can be applied over a shape. ShapeEffects class has been extended with the FillOverlay effect class. In addition, the effect can also be applied through FormatScheme class using fixed, placeholder, or pattern color usage.

The following code applies a pattern fill overlay of one shape over another.

GcWordDocument doc = new GcWordDocument();
Paragraph p = doc.Body.Paragraphs.Add();
Run run = p.GetRange().Runs.Add();
Shape shape = run.GetRange().Shapes.Add();
shape.Fill.Type = FillType.Solid;
shape.Fill.SolidFill.ThemeColor = ThemeColorId.Accent1;

// apply pattern fill overlay with another color to mix with the main fill
var fmtEffect = doc.Theme.FormatScheme.Effects.Add();
var overlay = fmtEffect.FillOverlay;
overlay.BlendMode = BlendMode.Multiply;

var foFill = overlay.Fill;
foFill.Type = FillType.Pattern;
foFill.PatternFill.Type = PatternFillType.DashedHorizontal;
foFill.PatternFill.ForeColor.ThemeColor = ThemeColorId.None;
foFill.PatternFill.BackColor.ThemeColor = ThemeColorId.Accent6;

shape.Style.Effects.PlaceholderColor.ThemeColor = ThemeColorId.Accent3;
shape.Style.Effects.PlaceholderColor.Transparency = 0.6f;

shape.Style.Effects.ThemeEffects = fmtEffect;

View Help Shape Format | ShapeStyles | Demo