Shapes Layout
Shapes
Shape is document element which is outlined by using geometric objects such as lines and/or curves (arcs, Bézier curves, etc.).
Shape's outline, besides geometry, can have additional properties, which are defined with object usually called Pen in drawing frameworks, such as width/thickness, fill/color and various other options (line join type, cap type, dash type, etc.). Shape's outline can even be invisible - if width is set to zero.
Shape's interior can be filled. Shape's fill, which is defined with object usually called Brush in drawing frameworks, can, for example, be specified as a solid color (single color), as a gradient of colors (smooth transition of color based on position) or even as a picture (colors/pixels from picture are used to fill the shape's interior). Shape can also be specified to not have any fill - to be transparent.
Additionally, Office Open XML shape can contain text (paragraphs and tables) with various properties such as vertical alignment, text direction, margin, etc.
Office Open XML shape may also have many additional properties/effects, such as transformation (rotation and flipping), shadow, reflection, 3-D format, etc.
Office Open XML specification also classifies picture as a shape, meaning that a picture can be clipped into a particular geometry with specific outline and fill properties (although picture cannot contain textual content).
Shape must have specific size and position in the document. Shape can be positioned in-line with the text or float around document content on a page. See Layout section for more information about shape positioning.
GemBox.Document Shapes
Entire GemBox.Document model is designed to support Microsoft Word documents (DOCX format) as much as possible. Since DOCX format is defined in Office Open XML specification, GemBox.Document shapes are also designed to support (or to be easily extended to support) previously described shape properties.
Office Open XML specification defines shapes in two different formats:
- DrawingML - primary format for shapes and pictures in Office Open XML formats (DOCX, XLSX and PPTX).
- VML - legacy format originally introduced with Office 2000 for defining graphical objects in cases where DrawingML does not apply.
Although VML should be considered a deprecated format, it is still used by millions of documents and it is worth noting that GemBox.Document has equally well support for when reading and writing Office Open XML (DOCX) documents.
GemBox.Document currently supports following shapes:
Drawings which are not shapes, text-boxes or pictures, are preserved as PreservedInline elements when read from DOCX format.
Shape's geometry is described with ShapeType property. GemBox.Document currently supports a subset of predefined geometries which are defined in ShapeType enumeration. Some predefined geometries can be adjusted using AdjustValues. Each ShapeType enumeration field contains additional documentation about its adjust values. Custom geometries are currently supported through preservation.
Shape's outline is described with Outline property which is represented as an instance of a Pen type. Currently supported outline properties are Width (thickness) and Fill.
Shape's fill is described with Fill property which is represented as an instance of a Brush type. Currently supported fill types are empty fill, which specifies that area won't be filled, and SolidColorBrush, which fills an area (shape or outline) with a single color.
Text box's format is described with TextBoxFormat property which is represented as an instance of a TextBoxFormat type.
Other shape properties, such as transformation (rotation and flipping), shadow, reflection, 3-D format, etc. are currently supported through preservation in DOCX format and are partially supported in PDF, XPS and other formats which require formatting and rendering a document.
For shapes created with GemBox.Document API, their properties will be equal to default properties of those shape types when inserted into document with Microsoft Word application (since shape styles are currently not available in GemBox.Document API):
- Shape will have geometry, outline and fill same as when inserted into document with Microsoft Word application.
- TextBox shape will have Rectangle geometry, thin black outline and white fill.
- Picture shape will have Rectangle geometry and won't have any outline nor fill.
Note
GemBox.Document allows shapes and other drawings to be organized into Groups. Each group has its own layout that affects all its children drawings.
Tip
For a demonstration example, check out Shapes example from GemBox.Document Examples.
Note
Support for shape outline properties (dash type, cap type, join type, etc.), fill types (gradient, picture / texture, pattern, etc.) and other shape properties (shadow, reflection, 3-D format, etc.) will be added in future versions of GemBox.Document, based on customer feedback.
Layout
Layout stands for the size and position of a document element in a document page.
Document elements which support layouting can be positioned in their current location inside document content flow or on a document page position outside of a document content flow.
Following GemBox.Document elements support layouting (can be positioned/sized):
- Drawings (Shape, TextBox and Picture) by using InlineLayout and FloatingLayout types (on Layout property).
- Table by using Positioning and PreferredWidth members (on TableFormat property).
Drawings can be positioned:
- In line with the text (InlineLayout type) - affects the line height and layout of its line (like a character glyph of similar size).
- Floating within the text relative to the page (FloatingLayout type) - affects the layout of its surrounding content which is either wrapped around or in-front / behind the floating element.
Besides position, drawings must also have size specified. Position and size are contained in Layout property.