Drawing Shapes and Watermarks

Drawing Shapes and Watermarks

Word documents keep AutoShapes, pictures, text boxes, and OLE objects in a separate drawing layer, distinct from the paragraph/run text flow. Aspose.Words FOSS for .NET models this layer with the Shape class (concrete drawing objects) and its abstract base ShapeBase, both part of the Aspose.Words.Drawing namespace. This guide covers the shape model, inserting images and AutoShapes, positioning and wrapping, fills and effects, grouping, and watermarks.

The Shape and ShapeBase Model

Shape — sealed, and the type you work with directly — represents an AutoShape, text box, freeform, OLE object, ActiveX control, or picture in the drawing layer. It derives from the abstract ShapeBase, which supplies the properties shared by every drawing object: position (Left, Top, Width, Height, Rotation), the ShapeType enum value, and formatting sub-objects such as Fill, Stroke, ShadowFormat, Glow, and Reflection. GroupShape (also a ShapeBase) represents a group of shapes treated as one unit. Construct a standalone shape directly with new Shape(doc, shapeType), where shapeType is a ShapeType value such as Rectangle, Ellipse, Star, or TextBox, then insert it into the tree with DocumentBuilder.InsertNode(node).

Inserting Images and AutoShapes with DocumentBuilder

For pictures specifically, DocumentBuilder.InsertImage is the more direct route: overloads accept an Image, a file path, a Stream, or a raw byte array, with further overloads that set explicit width/height or full positioning (horzPos, left, vertPos, top, width, height, wrapType). The resulting Shape exposes its picture data through the ImageData property — ImageData.SetImage(...) to replace the image, plus CropTop/CropBottom/CropLeft/CropRight, Brightness, Contrast, and GrayScale for basic adjustments. GroupShape instances are created with DocumentBuilder.InsertGroupShape(shapes).

Positioning and Text Wrapping

A shape’s placement relative to the page is controlled by RelativeHorizontalPosition and RelativeVerticalPosition (each relative to Page, Margin, Column, or similar anchors), together with the Left/Top offset properties. HorizontalAlignment and VerticalAlignment handle simple relative alignment. How surrounding text flows around the shape is set with WrapType and, for side-specific wrapping, WrapSide. IsInline reports whether the shape flows with the text (inline) or floats independently.

Fills, Strokes, and Effects

Shape.Fill (a Fill object) controls how the shape’s interior is painted: Fill.Solid(color) for a flat color, Fill.OneColorGradient(...) / Fill.TwoColorGradient(...) for gradients, Fill.Patterned(patternType) for a pattern, and Fill.SetImage(...) for a picture fill; FillType reports which of these is active. The outline is controlled through the Stroke property, and visual effects are exposed as separate formatting objects — ShadowFormat, Glow (GlowFormat), Reflection (ReflectionFormat), and SoftEdge (SoftEdgeFormat) — each with its own Remove() method to clear the effect.

Grouping Shapes and Text Boxes

Multiple shapes can be combined into a GroupShape, which itself behaves as a single ShapeBase with its own Fill, ShadowFormat, Glow, and Reflection. For a shape that carries text, Shape.TextBox (a TextBox object) exposes text-specific layout: InternalMarginLeft/Right/Top/Bottom for padding, FitShapeToText to auto-size the shape, LayoutFlow for text direction, and VerticalAnchor for vertical text alignment within the shape.

Watermarks

Document.Watermark (a Watermark object) manages a document-wide watermark independent of any single shape. Call Watermark.SetText(text) or SetText(text, options) for a text watermark, or SetImage(...) for a picture watermark, and Watermark.Remove() to clear it. Watermark.Type reports the current WatermarkType (Text, Image, or None). TextWatermarkOptions controls FontFamily, FontSize, Color, and Layout (WatermarkLayout.Horizontal or Diagonal); ImageWatermarkOptions controls Scale and IsWashout.

Tips and Best Practices

• Use ShapeBase when writing code that should work over both single Shape and GroupShape instances; use Shape directly when you need picture- or AutoShape-specific members like ImageData or Chart.
• Set RelativeHorizontalPosition / RelativeVerticalPosition together with WrapType when floating a shape — an inline shape (the default for InsertImage) ignores positioning properties until you make it float.
• Prefer Document.Watermark for a single document-wide watermark rather than manually inserting and positioning a Shape behind the text.
• Clear an effect with its object’s Remove() method (ShadowFormat.Remove(), ReflectionFormat.Remove()) rather than setting individual properties to zero.
• Check Shape.HasImage, Shape.HasChart, or Shape.IsGroup before accessing ImageData, Chart, or group-specific members, since a Shape can represent any one of several drawing object kinds.

Common Issues

FAQ

What’s the difference between Shape and ShapeBase?

ShapeBase is the abstract base class shared by Shape and GroupShape. Use ShapeBase in code that should handle either kind uniformly; use Shape when you need members specific to a single drawing object, such as ImageData or Chart.

How do I add a picture to a document?

Use one of the DocumentBuilder.InsertImage overloads — pass an Image, a file path, a Stream, or a byte array, optionally with width/height or full positioning arguments.

How do I make a shape float instead of sit inline with text?

Set its WrapType to a non-inline value and set RelativeHorizontalPosition / RelativeVerticalPosition so the shape’s Left/Top offsets are interpreted relative to the page, margin, or column.

Can I add both a text and an image watermark?

Document.Watermark.Type reflects the current watermark type; setting a new watermark with SetText or SetImage replaces whatever was there before, so a document has at most one active watermark at a time.

How do I remove a shadow or reflection from a shape?

Call Remove() on the corresponding formatting object — Shape.ShadowFormat.Remove() or Shape.Reflection.Remove().

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation