Drawing Object Features Supported on DOCX Import

Images

You can insert new images of any type into a document by using the DocumentBuilder.InsertImage method or by setting the image of an existing shape using the Shape.ImageData property.

All of the following image types listed in the table below this overview are supported. When a document contains multiple references to the same image from an from an external address (e.g the internet) then the image is only downloaded once.

It is useful to know how images are stored in the model when you insert a new image using Aspose.Words There are three classes of image from the Aspose.Words point-of-view.

  1. Microsoft Word Native (which can be stored directly in model without any changes). These are the JPEG, PNG, and PICT formats and are left untouched during insertion.

  2. Windows Metafiles (can also be stored directly in the model). These are the EMF and WMF vector formats and are left untouched during insertion.

  3. Microsoft Word Non-Native. These are not supported and have to be converted (to PNG) before being stored in the model. These are the GIF, TIFF and BMP formats.

Aspose.Words automatically converts the formats found in the third item if such a format is inserted into a document.

The reason why the formats found in the third item must be converted to PNG is because Microsoft Word formats don’t support the GIF or TIFF formats. It makes sense to store these in memory in a format that is supported by Microsoft Word. Note that when you insert an image of these types in Microsoft Word it also converts them to PNG in the same way behind the scenes.

BMP is the exception and is supported by Microsoft Word. However, since a BMP stored in memory is often very large it too is converted to PNG to save memory.

Note that PNG is a lossless compression format, so there is no degradation of image quality using the above techniques.

If you are using Aspose.Words for Java you may need to ensure that you have the appropriate JAI image libraries installed in order for Aspose.Words to convert GIF, TIFF and BMP formats to PNG. If the required functionality is missing you may receive a “Image type not supported” exception.

See the following links in the documentation for further information:

  • Shape.IsImage
  • LoadOptions.BaseUri
  • Shape.ImageData
  • ImageData.ImageType
  • ConvertUtil
Feature Supported Comment See Also
PNG Yes    
JPG Yes    
WMF Yes    
EMF Yes    
EMF+ Yes    
BMP Yes    
GIF Yes    
TIFF Yes    
Borders Yes   - ImageData.Borders
Cropping Yes  

- ImageData.CropLeft

- ImageData.CropRight

- ImageData.CropTop

- ImageData.CropBottom

Alternative text Yes   - Shape.AltText

Image Recoloring

Feature Supported Comment See Also
Brightness Yes   - ImageData.Brightness
Contrast Yes   - ImageData.Contrast
Recolor Yes    

Textboxes

See the following link in the documentation for further information:

  • Shape.TextBox
Feature Supported Comment See Also
Text Direction Yes   - TextBox.LayoutFlow
Linked Textboxes Yes Linked text boxes are supported in Aspose.Words model, however there is currently no API to access or modify these values.  
Internal Margins Yes  

- TextBox.InternalMarginLeft

- TextBox.InternalMarginRight

- TextBox.InternalMarginTop

- TextBox.InternalMarginBottom

Vertical Alignment Yes    
Resize To Fit Text Yes   - TextBox.FitShapeToText
Text in Other Shapes Yes    

OLE Objects

OLE Objects represent embedded content in a Microsoft Word document, such as an embedded Excel or Powerpoint document. The OLE object is dynamic and can be edited or updated through Microsoft Word. This feature is fully supported and preserved during document conversion.

OLE data can be accessed and modified through the properties of the Shape class. You can extract and save OLE data to stream or disk.

Currently embedding new or updating existing OLE Objects is not supported in Aspose.Words.

See the following links in the documentation for further information:

  • Shape.OleFormat
  • OleFormat.Save
Feature Supported Comment See Also
Linked Yes Note that Aspose.Words cannot update an OLE link. However you can modify a link only OLE object to point to a new location which can provide a partial way of changing OLE objects.

When such a document is saved and opened in Microsoft Word it will detect the change in the link and prompt the user to update the linked object. This results in the linked object appearing in the document.

Such a technique will only work for Word formats and if the document is opened in an editor which allows to update OLE objects (such as Microsoft Word). If the link is changed and the document to a different format such as PDF then the original content will still appear in the output.

- OleFormat.IsLink

- OleFormat.SourceFullName

Embedded Yes    
Draw Aspect Yes    
Auto Update Yes   - OleFormat.AutoUpdate
Lock Yes   - OleFormat.IsLocked
Ole Object Data Yes  

- OleFormat.GetOleEntry

- OleFormat.Save

Ole Object Picture Yes   - OleFormat.OleIcon
Source Range Yes   - OleFormat.SourceItem

ActiveX Controls

ActiveX Controls are preserved and supported during import. ActiveX is normally imported as a Shape node. Some ActiveX may also have an associated field.

You currently cannot create or modify existing ActiveX controls in a

document. You can however retrieve certain parts of data from controls (mostly parts assosicated with the graphic of the control).

Feature Supported Comment See Also
Persistent Properties Storage Yes    

Shapes

Aspose.Words supports almost all Shape and Image elements. References to external images such as ones on the internet are automatically downloaded as well. All of these elements are imported into Aspose.Words as Shape nodes.

Using Aspose.Words you can create any type of new shape including images, AutoShapes etc. you can also access, modify and remove such elements from a document.

The most common properties such as borders or position can be modified through the API. There is currently no API for modifying advanced shape properties e.g ArcSize of a RoundRectangle.

There is also no API for creating or modifying advanced features such as Diagrams, Ink Annotations or Charts. These elements are retained fully during conversion.

Shapes which are linked to external resources such as images on the internet can be automatically downloaded when required.

See the following links in the documentation for further information:

  • Shape
  • Shape.ShapeType
  • Shape.IsTopLevel
Feature Supported Comment See Also
Lines Yes    
Basic Shapes Yes    
Block Arrows Yes    
Flowcharts Yes    
Callouts Yes    
Stars and Banners Yes    
Group Shape Yes  

- GroupShape

- Shape.IsGroup

Drawing Canvas Yes    
Signature Line Planned Signature line content is currently preserved in image form only. You cannot access or validate the digital signature attached to a signature line yet or extract the signature as plain text.

Creating new signature lines is currently unsupported.

These features will be included as soon as possible.
- Shape.ImageData
Ink Annotation Yes    
Clip Art Yes    
Diagrams (VML) Yes VML graphics format is normally used in pre-OOXML formats such as DOC or RTF.  
SmartArt (VML) Yes Represented as a groupshape with child shapes representing the different elements.

You can add, modify or remove parts of the smart art. You can also extract the plain text content.
 
Charts (VML) Yes Currently there is no API for accessing or modifying the content of a chart.

You cannot retrieve the text of a chart.
 
Shape Customizations Yes    
Hyperlink on Shape Yes   - Shape.HRef
Watermark Yes A watermark in a Microsoft Word document is actually a text shape or image centered in the middle of the page but in the header or footer. This allows the watermark to appear behind all content and as faded. - How to Add a Watermark to a Document

WordArt

WordArt is imported as a Shape object in Aspose.Words. This class provides properties to extract and modify the properties of a WordArt object.

Using Aspose.Words you can create new WordArt graphics. Note that not all WordArt features are avalible through the API.

See the following links in the documentation for further information:

  • Shape.IsWordArt
  • Shape.TextPath
Feature Supported Comment See Also
Styles Yes    
Outline Yes    
Fill Yes    
3D Properties Yes    
Text Spacing Yes   - TextBox.Spacing
Vertical Text Yes   - TextBox.TextPathAlignment
Even Height Yes   - TextPath.SameLetterHeight
Align and Justify Text Yes   - Textbox.TextPathAlignment
WordArt Shape Yes    

Horizontal Line Object

Horizontal Line Objects are represented as a Shape node in Aspose.Words. Since a Shape can also represent an image there is a property which returns if this shape is a Horizontal Line Object.

Using Aspose.Words you can create new or modify existing Horizontal Rule objects.

See the following link in the documentation for further information:

  • Shape.IsHorizontalRule
Feature Supported Comment See Also
Width Yes Width appears in the API only as absolute points and not as percent as what Horizontal Line widths are normally calculated in.The percent value can be calculated by using the width of the page. - Shape.Width
Height Yes   - Shape.Height
Color Yes   - Shape.FillColor
Alignment Yes   - Shape.HorizontalAlignment
Hyperlink Yes   - Shape.HRef
Image Yes   - Shape.HRef

Position

Aspose.Words supports creating objects with a variety of different positioning settings. Almost all possible settings are supported in the Aspose.Words model

You can also access and modify the existing shape’s positioning.

See the following links in the documentation for further information:

  • Shape.Top
  • Shape.Width
Feature Supported Comment See Also
Inline Yes   - Shape.IsInline
Floating Yes In a Word document floating content is anchored to a paragraph. When a document is loaded into Aspose.Words this anchor is represented by the position of the Shape node in relation to Paragraph and the Runs of text.  
Wrap Type Yes   - Shape.WrapType
Wrap Sides Yes   - Shape.WrapSide
Distance from Text Yes  

- Shape.DistanceFromTextTop

- Shape.DistanceFromTextBottom

- Shape.DistanceFromTextLeft

- Shape.DistanceFromTextRight

Z-Order Yes   - Shape.ZOrder
Polygon Wrap Points Planned This property is currently lost upon import of Word documents.

This feature will be included a future verison.
 
Rotation Yes   - Shape.Rotation
Flip Yes   - Shape.FlipOrientation
Horizontal Alignment Yes   - Shape.HorizontalAlignment
Horizontal Position Relative To Yes   - Shape.RelativeHorizontalPosition
Vertical Alignment Yes   - Shape.VerticalAlignment
Vertical Position Relative To Yes   - Shape.RelativeVerticalPosition
Anchor Lock Yes   - Shape.AnchorLocked
Allow Overlap Yes   - Shape.AllowOverlap
Layout in Table Cell Yes There is currently no API to access this shape setting.  

Size

Feature Supported Comment See Also
Width and Height Yes  

- Shape.Width

- Shape.Height

Scale Yes There is currently no way to access the scale of Shape loaded in Aspose.Words.

The size of the shape after scale is applied is calculated and stored as the public size of the Shape. This size can be found using the Shape class.
- Shape.SizeInPoints
Relative Size Yes    
Lock Aspect Ratio Yes    

Fill

Using Aspose.Words you can access, modify and remove most fill properties of a shape.

See the following link in the documentation for further information:

  • Shape.Fill
Feature Supported Comment See Also
No Fill Yes   - Shape.Filled
Solid Fill Yes   - Shape.FillColor
Gradient Fill Yes There is currently no API for accessing or modifying the gradient fill of a shape.  
Pattern Fill Yes The raw bytes of the Pattern fill can be extracted only. A new pattern can not be set. - Fill.ImageBytes
Picture or Texture Fill Yes The raw bytes of the Texture fill can be extracted only. A new texture or image can not be set. - Fill.ImageBytes

Line Style

See the following links in the documentation for further information:

  • Shape.Stroke
  • Shape.Stroked
Feature Supported Comment See Also
Line Color Yes  

- Stroke.Color

- Stroke.Color2

Line Fill Yes   - Stroke.ImageBytes
Line Width Yes   - Stroke.Weight
Compound Type Yes   - Stroke.LineStyle
Dash Type Yes   - Stroke.DashStyle
Cap Type Yes   - Stroke.Cap
Join Type Yes   - Stroke.JoinStyle
Arrow Settings Yes  

- Stroke.StartArrowLength

- Stroke.StartArrowType

- Stroke.EndArrowLength

- Stroke.EndArrowType

Shadow

Most shadow properties are preserved during import. There is currently no API to access the shadow data of a graphic object.

This will be added in a future version.

Feature Supported Comment See Also
Shadow Yes    

3D Properties

Most 3D properties are retained during import. There is currently no API to access or modify these properties on graphic objects.

This will be added in a future version.

Feature Supported Comment See Also
3D Properties Yes