What's New in Documents for Word v6

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.

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;

doc.Save("LinkedStyles.docx");

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.

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

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.

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.

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
  style.Font.Effects.ApplyBuiltInReflection(BuiltInReflectionId.HalfTouching);
  doc.Body.Paragraphs.Add("Wetlands", style);
  doc.Save("font-reflection-sample.docx");

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
style.Font.Effects.ApplyBuiltInGlow(BuiltInGlowId.Radius5Accent2);
doc.Body.Paragraphs.Add("Wetlands", style);
doc.Save("Article.docx");

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;
doc.Save(@"shape-filloverlay-style-pattern-mixed-sample.docx");

View Help Shape Format | ShapeStyles | Demo