ShapeBase
Inheritance: java.lang.Object, com.aspose.words.Node, com.aspose.words.CompositeNode
public abstract class ShapeBase extends CompositeNode
Base class for objects in the drawing layer, such as an AutoShape, freeform, OLE object, ActiveX control, or picture.
To learn more, visit the Working with Shapes documentation article.
Remarks:
This is an abstract class. The two derived classes that you can instantiate are Shape and GroupShape.
A shape is a node in the document tree.
If the shape is a child of a Paragraph object, then the shape is said to be “top-level”. Top-level shapes are measured and positioned in points.
A shape can also occur as a child of a GroupShape object when several shapes are grouped. Child shapes of a group shape are positioned in the coordinate space and units defined by the getCoordSize() / setCoordSize(java.awt.Dimension) and getCoordOrigin() / setCoordOrigin(java.awt.Point) properties of the parent group shape.
A shape can be positioned inline with text or floating. The positioning method is controlled using the getWrapType() / setWrapType(int) property.
When a shape is floating, it is positioned relative to something (e.g the current paragraph, the margin or the page). The relative positioning of the shape is specified using the getRelativeHorizontalPosition() / setRelativeHorizontalPosition(int) and getRelativeVerticalPosition() / setRelativeVerticalPosition(int) properties.
A floating shape be positioned explicitly using the getLeft() / setLeft(double) and getTop() / setTop(double) properties or aligned relative to some other object using the getHorizontalAlignment() / setHorizontalAlignment(int) and getVerticalAlignment() / setVerticalAlignment(int) properties.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Methods
| Method | Description |
|---|---|
| accept(DocumentVisitor visitor) | Accepts a visitor. |
| acceptEnd(DocumentVisitor visitor) | When implemented in a derived class, calls the VisitXXXEnd method of the specified document visitor. |
| acceptStart(DocumentVisitor visitor) | When implemented in a derived class, calls the VisitXXXStart method of the specified document visitor. |
| adjustWithEffects(Rectangle2D.Float source) | Adds to the source rectangle values of the effect extent and returns the final rectangle. |
| appendChild(Node newChild) | Adds the specified node to the end of the list of child nodes for this node. |
| canHaveImage() | Returns true if the shape type allows the shape to have an image. |
| clearRunAttrs() | |
| dd() | |
| deepClone(boolean isCloneChildren) | Creates a duplicate of the node. |
| fetchInheritedRunAttr(int fontAttr) | |
| fetchInheritedShapeAttr(int key) | |
| fetchShapeAttr(int key) | |
| getAllowOverlap() | Gets a value that specifies whether this shape can overlap other shapes. |
| getAlternativeText() | Defines alternative text to be displayed instead of a graphic. |
| getAncestor(int ancestorType) | |
| getAncestor(Class ancestorType) | Gets the first ancestor of the specified object type. |
| getAnchorLocked() | Specifies whether the shape’s anchor is locked. |
| getAspectRatioLocked() | Specifies whether the shape’s aspect ratio is locked. |
| getBehindText() | Specifies whether the shape is below or above text. |
| getBlur() | |
| getBottom() | Gets the position of the bottom edge of the containing block of the shape. |
| getBounds() | Gets the location and size of the containing block of the shape. |
| getBoundsInPoints() | Gets the location and size of the containing block of the shape in points, relative to the anchor of the topmost shape. |
| getBoundsWithEffects() | Gets final extent that this shape object has after applying drawing effects. |
| getChild(int nodeType, int index, boolean isDeep) | |
| getChildNodes(int nodeType, boolean isDeep) | |
| getColor() | |
| getContainer() | |
| getCoordOrigin() | The coordinates at the top-left corner of the containing block of this shape. |
| getCoordSize() | The width and height of the coordinate space inside the containing block of this shape. |
| getCount() | Gets the number of immediate children of this node. |
| getCurrentNode() | |
| getCustomNodeId() | Specifies custom node identifier. |
| getDirectRunAttr(int fontAttr) | |
| getDirectRunAttr(int key, int revisionsView) | |
| getDirectShapeAttr(int key) | |
| getDistance() | |
| getDistanceBottom() | Gets the distance (in points) between the document text and the bottom edge of the shape. |
| getDistanceLeft() | Gets the distance (in points) between the document text and the left edge of the shape. |
| getDistanceRight() | Gets the distance (in points) between the document text and the right edge of the shape. |
| getDistanceTop() | Gets the distance (in points) between the document text and the top edge of the shape. |
| getDocument() | Gets the document to which this node belongs. |
| getDocument_IInline() | |
| getEdgeRadius() | |
| getFill() | Gets fill formatting for the shape. |
| getFillType() | |
| getFillableBackColor() | |
| getFillableBackThemeColor() | |
| getFillableBackTintAndShade() | |
| getFillableBaseForeColor() | |
| getFillableForeColor() | |
| getFillableForeThemeColor() | |
| getFillableForeTintAndShade() | |
| getFillableImageBytes() | |
| getFillableTransparency() | |
| getFillableVisible() | |
| getFilledColor() | |
| getFirstChild() | Gets the first child of the node. |
| getFlipOrientation() | Switches the orientation of a shape. |
| getFont() | Provides access to the font formatting of this object. |
| getGlow() | Gets glow formatting for the shape. |
| getGradientAngle() | |
| getGradientStops() | |
| getGradientStyle() | |
| getGradientVariant() | |
| getHRef() | Gets the full hyperlink address for a shape. |
| getHeight() | Gets the height of the containing block of the shape. |
| getHeightRelative() | Gets the value that represents the percentage of shape’s relative height. |
| getHidden() | Gets a boolean value indicating whether the shape is visible. |
| getHorizontalAlignment() | Specifies how the shape is positioned horizontally. |
| getLastChild() | Gets the last child of the node. |
| getLeft() | Gets the position of the left edge of the containing block of the shape. |
| getLeftRelative() | Gets the value that represents shape’s relative left position in percent. |
| getMarkupLanguage() | Gets MarkupLanguage used for this graphic object. |
| getName() | Gets the optional shape name. |
| getNextMatchingNode(Node curNode) | |
| getNextSibling() | Gets the node immediately following this node. |
| getNodeType() | Gets the type of this node. |
| getOldOn() | |
| getOldOpacity() | |
| getParentNode() | Gets the immediate parent of this node. |
| getParentParagraph() | Returns the immediate parent paragraph. |
| getParentParagraph_IInline() | |
| getPatternType() | |
| getPresetTexture() | |
| getPreviousSibling() | Gets the node immediately preceding this node. |
| getRadius() | |
| getRange() | Returns a Range object that represents the portion of a document that is contained in this node. |
| getReflection() | Gets reflection formatting for the shape. |
| getReflectionSize() | |
| getReflectionTransparency() | |
| getRelativeHorizontalPosition() | Specifies relative to what the shape is positioned horizontally. |
| getRelativeHorizontalSize() | Gets the value of shape’s relative size in horizontal direction. |
| getRelativeVerticalPosition() | Specifies relative to what the shape is positioned vertically. |
| getRelativeVerticalSize() | Gets the value of shape’s relative size in vertical direction. |
| getRight() | Gets the position of the right edge of the containing block of the shape. |
| getRotateWithObject() | |
| getRotation() | Defines the angle (in degrees) that a shape is rotated. |
| getScreenTip() | Defines the text displayed when the mouse pointer moves over the shape. |
| getShadowColors() | |
| getShadowFormat() | Gets shadow formatting for the shape. |
| getShadowType() | |
| getShapeRenderer() | Creates and returns an object that can be used to render this shape into an image. |
| getShapeType() | Gets the shape type. |
| getSizeInPoints() | Gets the size of the shape in points. |
| getSoftEdge() | Gets soft edge formatting for the shape. |
| getTarget() | Gets the target frame for the shape hyperlink. |
| getText() | Gets the text of this node and of all its children. |
| getTextureAlignment() | |
| getTitle() | Gets the title (caption) of the current shape object. |
| getTop() | Gets the position of the top edge of the containing block of the shape. |
| getTopRelative() | Gets the value that represents shape’s relative top position in percent. |
| getTransparency() | |
| getVerticalAlignment() | Specifies how the shape is positioned vertically. |
| getVisible() | |
| getWidth() | Gets the width of the containing block of the shape. |
| getWidthRelative() | Gets the value that represents the percentage of shape’s relative width. |
| getWrapSide() | Specifies how the text is wrapped around the shape. |
| getWrapType() | Defines whether the shape is inline or floating. |
| getZOrder() | Determines the display order of overlapping shapes. |
| getZOrder_IShape() | |
| hasChildNodes() | Returns true if this node has any child nodes. |
| indexOf(Node child) | Returns the index of the specified child node in the child node array. |
| insertAfter(Node newChild, Node refChild) | Inserts the specified node immediately after the specified reference node. |
| insertBefore(Node newChild, Node refChild) | Inserts the specified node immediately before the specified reference node. |
| isComposite() | Returns true as this node can have child nodes. |
| isDecorative() | Gets the flag that specifies whether the shape is decorative in the document. |
| isDecorative(boolean value) | Sets the flag that specifies whether the shape is decorative in the document. |
| isDeleteRevision() | Returns true if this object was deleted in Microsoft Word while change tracking was enabled. |
| isGroup() | Returns true if this is a group shape. |
| isHorizontalRule() | Returns true if this shape is a horizontal rule. |
| isImage() | Returns true if this shape is an image shape. |
| isInline() | A quick way to determine if this shape is positioned inline with text. |
| isInsertRevision() | Returns true if this object was inserted in Microsoft Word while change tracking was enabled. |
| isLayoutInCell() | Gets a flag indicating whether the shape is displayed inside a table or outside of it. |
| isLayoutInCell(boolean value) | Sets a flag indicating whether the shape is displayed inside a table or outside of it. |
| isMoveFromRevision() | Returns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled. |
| isMoveToRevision() | Returns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled. |
| isSignatureLine() | Indicates that shape is a SignatureLine. |
| isTopLevel() | Returns true if this shape is not a child of a group shape. |
| isWordArt() | Returns true if this shape is a WordArt object. |
| iterator() | Provides support for the for each style iteration over the child nodes of this node. |
| localToParent(Point2D.Float value) | Converts a value from the local coordinate space into the coordinate space of the parent shape. |
| nextPreOrder(Node rootNode) | Gets next node according to the pre-order tree traversal algorithm. |
| nodeTypeToString(int nodeType) | |
| oneColorGradient(int style, int variant, double degree) | |
| patterned(int patternType) | |
| prependChild(Node newChild) | Adds the specified node to the beginning of the list of child nodes for this node. |
| presetTextured(int presetTexture) | |
| previousPreOrder(Node rootNode) | Gets the previous node according to the pre-order tree traversal algorithm. |
| remove() | Removes itself from the parent. |
| removeAllChildren() | Removes all the child nodes of the current node. |
| removeChild(Node oldChild) | Removes the specified child node. |
| removeGlow() | |
| removeMoveRevisions() | |
| removeReflection() | |
| removeRunAttr(int key) | |
| removeShadow() | |
| removeShapeAttr(int key) | |
| removeSmartTags() | Removes all SmartTag descendant nodes of the current node. |
| removeSoftEdge() | |
| selectNodes(String xpath) | Selects a list of nodes matching the XPath expression. |
| selectSingleNode(String xpath) | Selects the first Node that matches the XPath expression. |
| setAllowOverlap(boolean value) | Sets a value that specifies whether this shape can overlap other shapes. |
| setAlternativeText(String value) | Defines alternative text to be displayed instead of a graphic. |
| setAnchorLocked(boolean value) | Specifies whether the shape’s anchor is locked. |
| setAspectRatioLocked(boolean value) | Specifies whether the shape’s aspect ratio is locked. |
| setBehindText(boolean value) | Specifies whether the shape is below or above text. |
| setBlur(double value) | |
| setBounds(Rectangle2D.Float value) | Sets the location and size of the containing block of the shape. |
| setColor(Color value) | |
| setCoordOrigin(Point value) | The coordinates at the top-left corner of the containing block of this shape. |
| setCoordSize(Dimension value) | The width and height of the coordinate space inside the containing block of this shape. |
| setCustomNodeId(int value) | Specifies custom node identifier. |
| setDistance(double value) | |
| setDistanceBottom(double value) | Sets the distance (in points) between the document text and the bottom edge of the shape. |
| setDistanceLeft(double value) | Sets the distance (in points) between the document text and the left edge of the shape. |
| setDistanceRight(double value) | Sets the distance (in points) between the document text and the right edge of the shape. |
| setDistanceTop(double value) | Sets the distance (in points) between the document text and the top edge of the shape. |
| setEdgeRadius(double value) | |
| setFillableBackColor(Color value) | |
| setFillableBackThemeColor(int value) | |
| setFillableBackTintAndShade(double value) | |
| setFillableForeColor(Color value) | |
| setFillableForeThemeColor(int value) | |
| setFillableForeTintAndShade(double value) | |
| setFillableTransparency(double value) | |
| setFillableVisible(boolean value) | |
| setFilledColor(Color value) | |
| setFlipOrientation(int value) | Switches the orientation of a shape. |
| setGradientAngle(double value) | |
| setHRef(String value) | Sets the full hyperlink address for a shape. |
| setHeight(double value) | Sets the height of the containing block of the shape. |
| setHeightRelative(float value) | Sets the value that represents the percentage of shape’s relative height. |
| setHidden(boolean value) | Sets a boolean value indicating whether the shape is visible. |
| setHorizontalAlignment(int value) | Specifies how the shape is positioned horizontally. |
| setImage(byte[] imageBytes) | |
| setLeft(double value) | Sets the position of the left edge of the containing block of the shape. |
| setLeftRelative(float value) | Sets the value that represents shape’s relative left position in percent. |
| setName(String value) | Sets the optional shape name. |
| setOldOn(boolean value) | |
| setOldOpacity(double value) | |
| setRadius(double value) | |
| setReflectionSize(double value) | |
| setReflectionTransparency(double value) | |
| setRelativeHorizontalPosition(int value) | Specifies relative to what the shape is positioned horizontally. |
| setRelativeHorizontalSize(int value) | Sets the value of shape’s relative size in horizontal direction. |
| setRelativeVerticalPosition(int value) | Specifies relative to what the shape is positioned vertically. |
| setRelativeVerticalSize(int value) | Sets the value of shape’s relative size in vertical direction. |
| setRotateWithObject(boolean value) | |
| setRotation(double value) | Defines the angle (in degrees) that a shape is rotated. |
| setRunAttr(int fontAttr, Object value) | |
| setScreenTip(String value) | Defines the text displayed when the mouse pointer moves over the shape. |
| setShadowType(int value) | |
| setShapeAttr(int key, Object value) | |
| setTarget(String value) | Sets the target frame for the shape hyperlink. |
| setTextureAlignment(int value) | |
| setTitle(String value) | Sets the title (caption) of the current shape object. |
| setTop(double value) | Sets the position of the top edge of the containing block of the shape. |
| setTopRelative(float value) | Sets the value that represents shape’s relative top position in percent. |
| setTransparency(double value) | |
| setVerticalAlignment(int value) | Specifies how the shape is positioned vertically. |
| setWidth(double value) | Sets the width of the containing block of the shape. |
| setWidthRelative(float value) | Sets the value that represents the percentage of shape’s relative width. |
| setWrapSide(int value) | Specifies how the text is wrapped around the shape. |
| setWrapType(int value) | Defines whether the shape is inline or floating. |
| setZOrder(int value) | Determines the display order of overlapping shapes. |
| setZOrder_IShape(int value) | |
| solid() | |
| toString() | |
| toString(SaveOptions saveOptions) | Exports the content of the node into a string using the specified save options. |
| toString(int saveFormat) | |
| twoColorGradient(int style, int variant) |
accept(DocumentVisitor visitor)
public abstract boolean accept(DocumentVisitor visitor)
Accepts a visitor.
Remarks:
Enumerates over this node and all of its children. Each node calls a corresponding method on DocumentVisitor.
For more info see the Visitor design pattern.
Examples:
Shows how to use a DocumentVisitor implementation to remove all hidden content from a document.
public void removeHiddenContentFromDocument() throws Exception {
Document doc = new Document(getMyDir() + "Hidden content.docx");
RemoveHiddenContentVisitor hiddenContentRemover = new RemoveHiddenContentVisitor();
// Below are three types of fields which can accept a document visitor,
// which will allow it to visit the accepting node, and then traverse its child nodes in a depth-first manner.
// 1 - Paragraph node:
Paragraph para = (Paragraph) doc.getChild(NodeType.PARAGRAPH, 4, true);
para.accept(hiddenContentRemover);
// 2 - Table node:
Table table = doc.getFirstSection().getBody().getTables().get(0);
table.accept(hiddenContentRemover);
// 3 - Document node:
doc.accept(hiddenContentRemover);
doc.save(getArtifactsDir() + "Font.RemoveHiddenContentFromDocument.docx");
}
///
/// Removes all visited nodes marked as "hidden content".
///
public static class RemoveHiddenContentVisitor extends DocumentVisitor {
///
/// Called when a FieldStart node is encountered in the document.
///
public int visitFieldStart(FieldStart fieldStart) {
if (fieldStart.getFont().getHidden())
fieldStart.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a FieldEnd node is encountered in the document.
///
public int visitFieldEnd(FieldEnd fieldEnd) {
if (fieldEnd.getFont().getHidden())
fieldEnd.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a FieldSeparator node is encountered in the document.
///
public int visitFieldSeparator(FieldSeparator fieldSeparator) {
if (fieldSeparator.getFont().getHidden())
fieldSeparator.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a Run node is encountered in the document.
///
public int visitRun(Run run) {
if (run.getFont().getHidden())
run.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a Paragraph node is encountered in the document.
///
public int visitParagraphStart(Paragraph paragraph) {
if (paragraph.getParagraphBreakFont().getHidden())
paragraph.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a FormField is encountered in the document.
///
public int visitFormField(FormField formField) {
if (formField.getFont().getHidden())
formField.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a GroupShape is encountered in the document.
///
public int visitGroupShapeStart(GroupShape groupShape) {
if (groupShape.getFont().getHidden())
groupShape.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a Shape is encountered in the document.
///
public int visitShapeStart(Shape shape) {
if (shape.getFont().getHidden())
shape.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a Comment is encountered in the document.
///
public int visitCommentStart(Comment comment) {
if (comment.getFont().getHidden())
comment.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a Footnote is encountered in the document.
///
public int visitFootnoteStart(Footnote footnote) {
if (footnote.getFont().getHidden())
footnote.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when a SpecialCharacter is encountered in the document.
///
public int visitSpecialChar(SpecialChar specialChar) {
if (specialChar.getFont().getHidden())
specialChar.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when visiting of a Table node is ended in the document.
///
public int visitTableEnd(Table table) {
// The content inside table cells may have the hidden content flag, but the tables themselves cannot.
// If this table had nothing but hidden content, this visitor would have removed all of it,
// and there would be no child nodes left.
// Thus, we can also treat the table itself as hidden content and remove it.
// Tables which are empty but do not have hidden content will have cells with empty paragraphs inside,
// which this visitor will not remove.
if (!table.hasChildNodes())
table.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when visiting of a Cell node is ended in the document.
///
public int visitCellEnd(Cell cell) {
if (!cell.hasChildNodes() && cell.getParentNode() != null)
cell.remove();
return VisitorAction.CONTINUE;
}
///
/// Called when visiting of a Row node is ended in the document.
///
public int visitRowEnd(Row row) {
if (!row.hasChildNodes() && row.getParentNode() != null)
row.remove();
return VisitorAction.CONTINUE;
}
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| visitor | DocumentVisitor | The visitor that will visit the nodes. |
Returns: boolean - True if all nodes were visited; false if DocumentVisitor stopped the operation before visiting all nodes.
acceptEnd(DocumentVisitor visitor)
public abstract int acceptEnd(DocumentVisitor visitor)
When implemented in a derived class, calls the VisitXXXEnd method of the specified document visitor.
Examples:
Shows how to use a document visitor to print a document’s node structure.
public void docStructureToText() throws Exception {
Document doc = new Document(getMyDir() + "DocumentVisitor-compatible features.docx");
DocStructurePrinter visitor = new DocStructurePrinter();
// When we get a composite node to accept a document visitor, the visitor visits the accepting node,
// and then traverses all the node's children in a depth-first manner.
// The visitor can read and modify each visited node.
doc.accept(visitor);
System.out.println(visitor.getText());
}
///
/// Traverses a node's tree of child nodes.
/// Creates a map of this tree in the form of a string.
///
public static class DocStructurePrinter extends DocumentVisitor {
public DocStructurePrinter() {
mAcceptingNodeChildTree = new StringBuilder();
}
public String getText() {
return mAcceptingNodeChildTree.toString();
}
///
/// Called when a Document node is encountered.
///
public int visitDocumentStart(Document doc) {
int childNodeCount = doc.getChildNodes(NodeType.ANY, true).getCount();
indentAndAppendLine("[Document start] Child nodes: " + childNodeCount);
mDocTraversalDepth++;
// Allow the visitor to continue visiting other nodes.
return VisitorAction.CONTINUE;
}
///
/// Called after all the child nodes of a Document node have been visited.
///
public int visitDocumentEnd(Document doc) {
mDocTraversalDepth--;
indentAndAppendLine("[Document end]");
return VisitorAction.CONTINUE;
}
///
/// Called when a Section node is encountered in the document.
///
public int visitSectionStart(final Section section) {
// Get the index of our section within the document
NodeCollection docSections = section.getDocument().getChildNodes(NodeType.SECTION, false);
int sectionIndex = docSections.indexOf(section);
indentAndAppendLine("[Section start] Section index: " + sectionIndex);
mDocTraversalDepth++;
return VisitorAction.CONTINUE;
}
///
/// Called after all the child nodes of a Section node have been visited.
///
public int visitSectionEnd(final Section section) {
mDocTraversalDepth--;
indentAndAppendLine("[Section end]");
return VisitorAction.CONTINUE;
}
///
/// Called when a Body node is encountered in the document.
///
public int visitBodyStart(final Body body) {
int paragraphCount = body.getParagraphs().getCount();
indentAndAppendLine("[Body start] Paragraphs: " + paragraphCount);
mDocTraversalDepth++;
return VisitorAction.CONTINUE;
}
///
/// Called after all the child nodes of a Body node have been visited.
///
public int visitBodyEnd(final Body body) {
mDocTraversalDepth--;
indentAndAppendLine("[Body end]");
return VisitorAction.CONTINUE;
}
///
/// Called when a Paragraph node is encountered in the document.
///
public int visitParagraphStart(final Paragraph paragraph) {
indentAndAppendLine("[Paragraph start]");
mDocTraversalDepth++;
return VisitorAction.CONTINUE;
}
///
/// Called after all the child nodes of a Paragraph node have been visited.
///
public int visitParagraphEnd(final Paragraph paragraph) {
mDocTraversalDepth--;
indentAndAppendLine("[Paragraph end]");
return VisitorAction.CONTINUE;
}
///
/// Called when a Run node is encountered in the document.
///
public int visitRun(final Run run) {
indentAndAppendLine("[Run] \"" + run.getText() + "\"");
return VisitorAction.CONTINUE;
}
///
/// Called when a SubDocument node is encountered in the document.
///
public int visitSubDocument(final SubDocument subDocument) {
indentAndAppendLine("[SubDocument]");
return VisitorAction.CONTINUE;
}
///
/// Called when a SubDocument node is encountered in the document.
///
public int visitStructuredDocumentTagRangeStart(StructuredDocumentTagRangeStart sdtRangeStart)
{
indentAndAppendLine("[SdtRangeStart]");
return VisitorAction.CONTINUE;
}
///
/// Called when a SubDocument node is encountered in the document.
///
public int visitStructuredDocumentTagRangeEnd(StructuredDocumentTagRangeEnd sdtRangeEnd)
{
indentAndAppendLine("[SdtRangeEnd]");
return VisitorAction.CONTINUE;
}
///
/// Append a line to the StringBuilder and indent it depending on how deep the visitor is into the document tree.
///
///
private void indentAndAppendLine(final String text) {
for (int i = 0; i < mDocTraversalDepth; i++) {
mAcceptingNodeChildTree.append("| ");
}
mAcceptingNodeChildTree.append(text + "\r\n");
}
private int mDocTraversalDepth;
private final StringBuilder mAcceptingNodeChildTree;
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| visitor | DocumentVisitor |
Returns: int
acceptStart(DocumentVisitor visitor)
public abstract int acceptStart(DocumentVisitor visitor)
When implemented in a derived class, calls the VisitXXXStart method of the specified document visitor.
Examples:
Shows how to use a document visitor to print a document’s node structure.
public void docStructureToText() throws Exception {
Document doc = new Document(getMyDir() + "DocumentVisitor-compatible features.docx");
DocStructurePrinter visitor = new DocStructurePrinter();
// When we get a composite node to accept a document visitor, the visitor visits the accepting node,
// and then traverses all the node's children in a depth-first manner.
// The visitor can read and modify each visited node.
doc.accept(visitor);
System.out.println(visitor.getText());
}
///
/// Traverses a node's tree of child nodes.
/// Creates a map of this tree in the form of a string.
///
public static class DocStructurePrinter extends DocumentVisitor {
public DocStructurePrinter() {
mAcceptingNodeChildTree = new StringBuilder();
}
public String getText() {
return mAcceptingNodeChildTree.toString();
}
///
/// Called when a Document node is encountered.
///
public int visitDocumentStart(Document doc) {
int childNodeCount = doc.getChildNodes(NodeType.ANY, true).getCount();
indentAndAppendLine("[Document start] Child nodes: " + childNodeCount);
mDocTraversalDepth++;
// Allow the visitor to continue visiting other nodes.
return VisitorAction.CONTINUE;
}
///
/// Called after all the child nodes of a Document node have been visited.
///
public int visitDocumentEnd(Document doc) {
mDocTraversalDepth--;
indentAndAppendLine("[Document end]");
return VisitorAction.CONTINUE;
}
///
/// Called when a Section node is encountered in the document.
///
public int visitSectionStart(final Section section) {
// Get the index of our section within the document
NodeCollection docSections = section.getDocument().getChildNodes(NodeType.SECTION, false);
int sectionIndex = docSections.indexOf(section);
indentAndAppendLine("[Section start] Section index: " + sectionIndex);
mDocTraversalDepth++;
return VisitorAction.CONTINUE;
}
///
/// Called after all the child nodes of a Section node have been visited.
///
public int visitSectionEnd(final Section section) {
mDocTraversalDepth--;
indentAndAppendLine("[Section end]");
return VisitorAction.CONTINUE;
}
///
/// Called when a Body node is encountered in the document.
///
public int visitBodyStart(final Body body) {
int paragraphCount = body.getParagraphs().getCount();
indentAndAppendLine("[Body start] Paragraphs: " + paragraphCount);
mDocTraversalDepth++;
return VisitorAction.CONTINUE;
}
///
/// Called after all the child nodes of a Body node have been visited.
///
public int visitBodyEnd(final Body body) {
mDocTraversalDepth--;
indentAndAppendLine("[Body end]");
return VisitorAction.CONTINUE;
}
///
/// Called when a Paragraph node is encountered in the document.
///
public int visitParagraphStart(final Paragraph paragraph) {
indentAndAppendLine("[Paragraph start]");
mDocTraversalDepth++;
return VisitorAction.CONTINUE;
}
///
/// Called after all the child nodes of a Paragraph node have been visited.
///
public int visitParagraphEnd(final Paragraph paragraph) {
mDocTraversalDepth--;
indentAndAppendLine("[Paragraph end]");
return VisitorAction.CONTINUE;
}
///
/// Called when a Run node is encountered in the document.
///
public int visitRun(final Run run) {
indentAndAppendLine("[Run] \"" + run.getText() + "\"");
return VisitorAction.CONTINUE;
}
///
/// Called when a SubDocument node is encountered in the document.
///
public int visitSubDocument(final SubDocument subDocument) {
indentAndAppendLine("[SubDocument]");
return VisitorAction.CONTINUE;
}
///
/// Called when a SubDocument node is encountered in the document.
///
public int visitStructuredDocumentTagRangeStart(StructuredDocumentTagRangeStart sdtRangeStart)
{
indentAndAppendLine("[SdtRangeStart]");
return VisitorAction.CONTINUE;
}
///
/// Called when a SubDocument node is encountered in the document.
///
public int visitStructuredDocumentTagRangeEnd(StructuredDocumentTagRangeEnd sdtRangeEnd)
{
indentAndAppendLine("[SdtRangeEnd]");
return VisitorAction.CONTINUE;
}
///
/// Append a line to the StringBuilder and indent it depending on how deep the visitor is into the document tree.
///
///
private void indentAndAppendLine(final String text) {
for (int i = 0; i < mDocTraversalDepth; i++) {
mAcceptingNodeChildTree.append("| ");
}
mAcceptingNodeChildTree.append(text + "\r\n");
}
private int mDocTraversalDepth;
private final StringBuilder mAcceptingNodeChildTree;
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| visitor | DocumentVisitor |
Returns: int
adjustWithEffects(Rectangle2D.Float source)
public Rectangle2D.Float adjustWithEffects(Rectangle2D.Float source)
Adds to the source rectangle values of the effect extent and returns the final rectangle.
Examples:
Shows how to check how a shape’s bounds are affected by shape effects.
Document doc = new Document(getMyDir() + "Shape shadow effect.docx");
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(shapeList.size(), 2);
Shape firstShape = shapeList.get(0);
Shape secondShape = shapeList.get(1);
// The two shapes are identical in terms of dimensions and shape type.
Assert.assertEquals(firstShape.getWidth(), secondShape.getWidth());
Assert.assertEquals(firstShape.getHeight(), secondShape.getHeight());
Assert.assertEquals(firstShape.getShapeType(), secondShape.getShapeType());
// The first shape has no effects, and the second one has a shadow and thick outline.
// These effects make the size of the second shape's silhouette bigger than that of the first.
// Even though the rectangle's size shows up when we click on these shapes in Microsoft Word,
// the visible outer bounds of the second shape are affected by the shadow and outline and thus are bigger.
// We can use the "AdjustWithEffects" method to see the true size of the shape.
Assert.assertEquals(0.0, firstShape.getStrokeWeight());
Assert.assertEquals(20.0, secondShape.getStrokeWeight());
Assert.assertFalse(firstShape.getShadowEnabled());
Assert.assertTrue(secondShape.getShadowEnabled());
Shape shape = firstShape;
// Run this method to get the size of the rectangle adjusted for all our shape effects.
Rectangle2D.Float rectangleFOut = shape.adjustWithEffects(new Rectangle2D.Float(200f, 200f, 1000f, 1000f));
// Since the shape has no border-changing effects, its boundary dimensions are unaffected.
Assert.assertEquals(200.0, rectangleFOut.getX());
Assert.assertEquals(200.0, rectangleFOut.getY());
Assert.assertEquals(1000.0, rectangleFOut.getWidth());
Assert.assertEquals(1000.0, rectangleFOut.getHeight());
// Verify the final extent of the first shape, in points.
Assert.assertEquals(0.0, shape.getBoundsWithEffects().getX());
Assert.assertEquals(0.0, shape.getBoundsWithEffects().getY());
Assert.assertEquals(147.0, shape.getBoundsWithEffects().getWidth());
Assert.assertEquals(147.0, shape.getBoundsWithEffects().getHeight());
shape = secondShape;
rectangleFOut = shape.adjustWithEffects(new Rectangle2D.Float(200f, 200f, 1000f, 1000f));
// The shape effects have moved the apparent top left corner of the shape slightly.
Assert.assertEquals(171.5, rectangleFOut.getX());
Assert.assertEquals(167.0, rectangleFOut.getY());
// The effects have also affected the visible dimensions of the shape.
Assert.assertEquals(1045.0, rectangleFOut.getWidth());
Assert.assertEquals(1133.5, rectangleFOut.getHeight());
// The effects have also affected the visible bounds of the shape.
Assert.assertEquals(-28.5, shape.getBoundsWithEffects().getX());
Assert.assertEquals(-33.0, shape.getBoundsWithEffects().getY());
Assert.assertEquals(192.0, shape.getBoundsWithEffects().getWidth());
Assert.assertEquals(280.5, shape.getBoundsWithEffects().getHeight());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| source | java.awt.geom.Rectangle2D.Float |
Returns: java.awt.geom.Rectangle2D.Float
appendChild(Node newChild)
public Node appendChild(Node newChild)
Adds the specified node to the end of the list of child nodes for this node.
Remarks:
If the newChild is already in the tree, it is first removed.
If the node being inserted was created from another document, you should use M:Aspose.Words.DocumentBase.ImportNode(Aspose.Words.Node,System.Boolean,Aspose.Words.ImportFormatMode) to import the node to the current document. The imported node can then be inserted into the current document.
Examples:
Shows how to construct an Aspose.Words document by hand.
Document doc = new Document();
// A blank document contains one section, one body and one paragraph.
// Call the "RemoveAllChildren" method to remove all those nodes,
// and end up with a document node with no children.
doc.removeAllChildren();
// This document now has no composite child nodes that we can add content to.
// If we wish to edit it, we will need to repopulate its node collection.
// First, create a new section, and then append it as a child to the root document node.
Section section = new Section(doc);
doc.appendChild(section);
// Set some page setup properties for the section.
section.getPageSetup().setSectionStart(SectionStart.NEW_PAGE);
section.getPageSetup().setPaperSize(PaperSize.LETTER);
// A section needs a body, which will contain and display all its contents
// on the page between the section's header and footer.
Body body = new Body(doc);
section.appendChild(body);
// Create a paragraph, set some formatting properties, and then append it as a child to the body.
Paragraph para = new Paragraph(doc);
para.getParagraphFormat().setStyleName("Heading 1");
para.getParagraphFormat().setAlignment(ParagraphAlignment.CENTER);
body.appendChild(para);
// Finally, add some content to do the document. Create a run,
// set its appearance and contents, and then append it as a child to the paragraph.
Run run = new Run(doc);
run.setText("Hello World!");
run.getFont().setColor(Color.RED);
para.appendChild(run);
Assert.assertEquals("Hello World!", doc.getText().trim());
doc.save(getArtifactsDir() + "Section.CreateManually.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| newChild | Node | The node to add. |
Returns: Node - The node added.
canHaveImage()
public boolean canHaveImage()
Returns true if the shape type allows the shape to have an image.
Remarks:
Although Microsoft Word has a special shape type for images, it appears that in Microsoft Word documents any shape except a group shape can have an image, therefore this property returns true for all shapes except GroupShape.
Examples:
Shows how to insert and rotate an image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a shape with an image.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
Assert.assertTrue(shape.canHaveImage());
Assert.assertTrue(shape.hasImage());
// Rotate the image 45 degrees clockwise.
shape.setRotation(45.0);
doc.save(getArtifactsDir() + "Shape.Rotate.docx");
Returns: boolean - true if the shape type allows the shape to have an image.
clearRunAttrs()
public void clearRunAttrs()
dd()
public void dd()
deepClone(boolean isCloneChildren)
public Node deepClone(boolean isCloneChildren)
Creates a duplicate of the node.
Remarks:
This method serves as a copy constructor for nodes. The cloned node has no parent, but belongs to the same document as the original node.
This method always performs a deep copy of the node. The isCloneChildren parameter specifies whether to perform copy all child nodes as well.
Examples:
Shows how to clone a composite node.
Document doc = new Document();
Paragraph para = doc.getFirstSection().getBody().getFirstParagraph();
para.appendChild(new Run(doc, "Hello world!"));
// Below are two ways of cloning a composite node.
// 1 - Create a clone of a node, and create a clone of each of its child nodes as well.
Node cloneWithChildren = para.deepClone(true);
Assert.assertTrue(((CompositeNode) cloneWithChildren).hasChildNodes());
Assert.assertEquals("Hello world!", cloneWithChildren.getText().trim());
// 2 - Create a clone of a node just by itself without any children.
Node cloneWithoutChildren = para.deepClone(false);
Assert.assertFalse(((CompositeNode) cloneWithoutChildren).hasChildNodes());
Assert.assertEquals("", cloneWithoutChildren.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| isCloneChildren | boolean | True to recursively clone the subtree under the specified node; false to clone only the node itself. |
Returns: Node - The cloned node.
fetchInheritedRunAttr(int fontAttr)
public Object fetchInheritedRunAttr(int fontAttr)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| fontAttr | int |
Returns: java.lang.Object
fetchInheritedShapeAttr(int key)
public Object fetchInheritedShapeAttr(int key)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | int |
Returns: java.lang.Object
fetchShapeAttr(int key)
public Object fetchShapeAttr(int key)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | int |
Returns: java.lang.Object
getAllowOverlap()
public boolean getAllowOverlap()
Gets a value that specifies whether this shape can overlap other shapes.
Remarks:
This property affects behavior of the shape in Microsoft Word. Aspose.Words ignores the value of this property.
This property is applicable only to top level shapes.
The default value is true .
Examples:
Shows how to work with floating tables properties.
Document doc = new Document(getMyDir() + "Table wrapped by text.docx");
Table table = doc.getFirstSection().getBody().getTables().get(0);
if (table.getTextWrapping() == TextWrapping.AROUND) {
Assert.assertEquals(RelativeHorizontalPosition.MARGIN, table.getHorizontalAnchor());
Assert.assertEquals(RelativeVerticalPosition.PARAGRAPH, table.getVerticalAnchor());
Assert.assertEquals(false, table.getAllowOverlap());
// Only Margin, Page, Column available in RelativeHorizontalPosition for HorizontalAnchor setter.
// The ArgumentException will be thrown for any other values.
table.setHorizontalAnchor(RelativeHorizontalPosition.COLUMN);
// Only Margin, Page, Paragraph available in RelativeVerticalPosition for VerticalAnchor setter.
// The ArgumentException will be thrown for any other values.
table.setVerticalAnchor(RelativeVerticalPosition.PAGE);
}
Returns: boolean - A value that specifies whether this shape can overlap other shapes.
getAlternativeText()
public String getAlternativeText()
Defines alternative text to be displayed instead of a graphic.
Remarks:
The default value is an empty string.
Examples:
Shows how to use a shape’s alternative text.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertShape(ShapeType.CUBE, 150.0, 150.0);
shape.setName("MyCube");
shape.setAlternativeText("Alt text for MyCube.");
// We can access the alternative text of a shape by right-clicking it, and then via "Format AutoShape" -> "Alt Text".
doc.save(getArtifactsDir() + "Shape.AltText.docx");
// Save the document to HTML, and then delete the linked image that belongs to our shape.
// The browser that is reading our HTML will display the alt text in place of the missing image.
doc.save(getArtifactsDir() + "Shape.AltText.html");
new File(getArtifactsDir() + "Shape.AltText.001.png").delete();
Returns: java.lang.String - The corresponding java.lang.String value.
getAncestor(int ancestorType)
public CompositeNode getAncestor(int ancestorType)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| ancestorType | int |
Returns: CompositeNode
getAncestor(Class ancestorType)
public CompositeNode getAncestor(Class ancestorType)
Gets the first ancestor of the specified object type.
Remarks:
The ancestor type matches if it is equal to ancestorType or derived from ancestorType .
Examples:
Shows how to find out if a tables are nested.
public void calculateDepthOfNestedTables() throws Exception {
Document doc = new Document(getMyDir() + "Nested tables.docx");
NodeCollection tables = doc.getChildNodes(NodeType.TABLE, true);
for (int i = 0; i < tables.getCount(); i++) {
Table table = (Table) tables.get(i);
// Find out if any cells in the table have other tables as children.
int count = getChildTableCount(table);
System.out.print(MessageFormat.format("Table #{0} has {1} tables directly within its cells", i, count));
// Find out if the table is nested inside another table, and, if so, at what depth.
int tableDepth = getNestedDepthOfTable(table);
if (tableDepth > 0)
System.out.println(MessageFormat.format("Table #{0} is nested inside another table at depth of {1}", i, tableDepth));
else
System.out.println(MessageFormat.format("Table #{0} is a non nested table (is not a child of another table)", i));
}
}
// Calculates what level a table is nested inside other tables.
//
// Returns An integer containing the level the table is nested at.
// 0 = Table is not nested inside any other table
// 1 = Table is nested within one parent table
// 2 = Table is nested within two parent tables etc..
private static int getNestedDepthOfTable(final Table table) {
int depth = 0;
Node parent = table.getAncestor(table.getNodeType());
while (parent != null) {
depth++;
parent = parent.getAncestor(Table.class);
}
return depth;
}
// Determines if a table contains any immediate child table within its cells.
// Does not recursively traverse through those tables to check for further tables.
//
// Returns true if at least one child cell contains a table.
// Returns false if no cells in the table contains a table.
private static int getChildTableCount(final Table table) {
int childTableCount = 0;
for (Row row : table.getRows()) {
for (Cell cell : row.getCells()) {
TableCollection childTables = cell.getTables();
if (childTables.getCount() > 0) childTableCount++;
}
}
return childTableCount;
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| ancestorType | java.lang.Class | The object type of the ancestor to retrieve. |
Returns: CompositeNode - The ancestor of the specified type or null if no ancestor of this type was found.
getAnchorLocked()
public boolean getAnchorLocked()
Specifies whether the shape’s anchor is locked.
Remarks:
The default value is false .
Has effect only for top level shapes.
This property affects behavior of the shape’s anchor in Microsoft Word. When the anchor is not locked, moving the shape in Microsoft Word can move the shape’s anchor too.
Examples:
Shows how to lock or unlock a shape’s paragraph anchor.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
builder.write("Our shape will have an anchor attached to this paragraph.");
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 200.0, 160.0);
shape.setWrapType(WrapType.NONE);
builder.insertBreak(BreakType.PARAGRAPH_BREAK);
builder.writeln("Hello again!");
// Set the "AnchorLocked" property to "true" to prevent the shape's anchor
// from moving when moving the shape in Microsoft Word.
// Set the "AnchorLocked" property to "false" to allow any movement of the shape
// to also move its anchor to any other paragraph that the shape ends up close to.
shape.setAnchorLocked(anchorLocked);
// If the shape does not have a visible anchor symbol to its left,
// we will need to enable visible anchors via "Options" -> "Display" -> "Object Anchors".
doc.save(getArtifactsDir() + "Shape.AnchorLocked.docx");
Returns: boolean - The corresponding boolean value.
getAspectRatioLocked()
public boolean getAspectRatioLocked()
Specifies whether the shape’s aspect ratio is locked.
Remarks:
The default value depends on the ShapeType, for the ShapeType.IMAGE it is true but for the other shape types it is false .
Has effect for top level shapes only.
Examples:
Shows how to lock/unlock a shape’s aspect ratio.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a shape. If we open this document in Microsoft Word, we can left click the shape to reveal
// eight sizing handles around its perimeter, which we can click and drag to change its size.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
// Set the "AspectRatioLocked" property to "true" to preserve the shape's aspect ratio
// when using any of the four diagonal sizing handles, which change both the image's height and width.
// Using any orthogonal sizing handles that either change the height or width will still change the aspect ratio.
// Set the "AspectRatioLocked" property to "false" to allow us to
// freely change the image's aspect ratio with all sizing handles.
shape.setAspectRatioLocked(lockAspectRatio);
doc.save(getArtifactsDir() + "Shape.AspectRatio.docx");
Returns: boolean - The corresponding boolean value.
getBehindText()
public boolean getBehindText()
Specifies whether the shape is below or above text.
Remarks:
Has effect only for top level shapes.
The default value is false .
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Returns: boolean - The corresponding boolean value.
getBlur()
public double getBlur()
Returns: double
getBottom()
public double getBottom()
Gets the position of the bottom edge of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points and relative to the shape anchor.
For shapes in a group, the value is in the coordinate space and units of the parent group.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Returns: double - The position of the bottom edge of the containing block of the shape.
getBounds()
public Rectangle2D.Float getBounds()
Gets the location and size of the containing block of the shape.
Remarks:
Ignores aspect ratio lock upon setting.
For a top-level shape, the value is in points and relative to the shape anchor.
For shapes in a group, the value is in the coordinate space and units of the parent group.
Examples:
Shows how to verify shape containing block boundaries.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertShape(ShapeType.LINE, RelativeHorizontalPosition.LEFT_MARGIN, 50.0,
RelativeVerticalPosition.TOP_MARGIN, 50.0, 100.0, 100.0, WrapType.NONE);
shape.setStrokeColor(Color.ORANGE);
// Even though the line itself takes up little space on the document page,
// it occupies a rectangular containing block, the size of which we can determine using the "Bounds" properties.
Assert.assertEquals(new Rectangle2D.Float(50f, 50f, 100f, 100f), shape.getBounds());
Assert.assertEquals(new Rectangle2D.Float(50f, 50f, 100f, 100f), shape.getBoundsInPoints());
// Create a group shape, and then set the size of its containing block using the "Bounds" property.
GroupShape group = new GroupShape(doc);
group.setBounds(new Rectangle2D.Float(0f, 100f, 250f, 250f));
Assert.assertEquals(new Rectangle2D.Float(0f, 100f, 250f, 250f), group.getBoundsInPoints());
// Create a rectangle, verify the size of its bounding block, and then add it to the group shape.
shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(700.0);
shape.setTop(700.0);
}
Assert.assertEquals(new Rectangle2D.Float(700f, 700f, 100f, 100f), shape.getBoundsInPoints());
group.appendChild(shape);
// The group shape's coordinate plane has its origin on the top left-hand side corner of its containing block,
// and the x and y coordinates of (1000, 1000) on the bottom right-hand side corner.
// Our group shape is 250x250pt in size, so every 4pt on the group shape's coordinate plane
// translates to 1pt in the document body's coordinate plane.
// Every shape that we insert will also shrink in size by a factor of 4.
// The change in the shape's "BoundsInPoints" property will reflect this.
Assert.assertEquals(new Rectangle2D.Float(175f, 275f, 25f, 25f), shape.getBoundsInPoints());
doc.getFirstSection().getBody().getFirstParagraph().appendChild(group);
// Insert a shape and place it outside of the bounds of the group shape's containing block.
shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(1000.0);
shape.setTop(1000.0);
}
group.appendChild(shape);
// The group shape's footprint in the document body has increased, but the containing block remains the same.
Assert.assertEquals(new Rectangle2D.Float(0f, 100f, 250f, 250f), group.getBoundsInPoints());
Assert.assertEquals(new Rectangle2D.Float(250f, 350f, 25f, 25f), shape.getBoundsInPoints());
doc.save(getArtifactsDir() + "Shape.Bounds.docx");
Shows how to create and populate a group shape.
Document doc = new Document();
// Create a group shape. A group shape can display a collection of child shape nodes.
// In Microsoft Word, clicking within the group shape's boundary or on one of the group shape's child shapes will
// select all the other child shapes within this group and allow us to scale and move all the shapes at once.
GroupShape group = new GroupShape(doc);
Assert.assertEquals(WrapType.NONE, group.getWrapType());
// Create a 400pt x 400pt group shape and place it at the document's floating shape coordinate origin.
group.setBounds(new Rectangle2D.Float(0f, 0f, 400f, 400f));
// Set the group's internal coordinate plane size to 500 x 500pt.
// The top left corner of the group will have an x and y coordinate of (0, 0),
// and the bottom right corner will have an x and y coordinate of (500, 500).
group.setCoordSize(new Dimension(500, 500));
// Set the coordinates of the top left corner of the group to (-250, -250).
// The group's center will now have an x and y coordinate value of (0, 0),
// and the bottom right corner will be at (250, 250).
group.setCoordOrigin(new Point(-250, -250));
Shape rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(group.getCoordSize().width);
rectangleShape.setHeight(group.getCoordSize().height);
rectangleShape.setLeft(group.getCoordOrigin().x);
rectangleShape.setTop(group.getCoordOrigin().y);
// Create a rectangle that will display the boundary of this group shape and add it to the group.
group.appendChild(rectangleShape);
// Once a shape is a part of a group shape, we can access it as a child node and then modify it.
((Shape) group.getChild(NodeType.SHAPE, 0, true)).getStroke().setDashStyle(DashStyle.DASH);
Shape starShape = new Shape(doc, ShapeType.STAR);
starShape.setWidth(20.0);
starShape.setHeight(20.0);
starShape.setLeft(-10);
starShape.setTop(-10);
starShape.setFillColor(Color.RED);
// Create a small red star and insert it into the group.
// Line up the shape with the group's coordinate origin, which we have moved to the center.
group.appendChild(starShape);
rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(250.0);
rectangleShape.setHeight(250.0);
rectangleShape.setLeft(-250);
rectangleShape.setTop(-250);
rectangleShape.setFillColor(Color.BLUE);
// Insert a rectangle, and then insert a slightly smaller rectangle in the same place with an image.
// Newer shapes that we add to the group overlap older shapes. The light blue rectangle will partially overlap the red star,
// and then the shape with the image will overlap the light blue rectangle, using it as a frame.
// We cannot use the "ZOrder" properties of shapes to manipulate their arrangement within a group shape.
group.appendChild(rectangleShape);
Shape imageShape = new Shape(doc, ShapeType.IMAGE);
imageShape.setWidth(200.0);
imageShape.setHeight(200.0);
imageShape.setLeft(-225);
imageShape.setTop(-225);
group.appendChild(imageShape);
((Shape) group.getChild(NodeType.SHAPE, 3, true)).getImageData().setImage(getImageDir() + "Logo.jpg");
Shape textboxShape = new Shape(doc, ShapeType.TEXT_BOX);
textboxShape.setWidth(200.0);
textboxShape.setHeight(50.0);
textboxShape.setLeft(group.getCoordSize().width + new Point(group.getCoordOrigin()).x - 200);
textboxShape.setTop(group.getCoordSize().height + new Point(group.getCoordOrigin()).y);
// Insert a text box into the group shape. Set the "Left" property so that the text box's right edge
// touches the right boundary of the group shape. Set the "Top" property so that the text box sits outside
// the boundary of the group shape, with its top size lined up along the group shape's bottom margin.
group.appendChild(textboxShape);
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertNode(group);
builder.moveTo(((Shape) group.getChild(NodeType.SHAPE, 4, true)).appendChild(new Paragraph(doc)));
builder.write("Hello world!");
doc.save(getArtifactsDir() + "Shape.GroupShape.docx");
Returns: java.awt.geom.Rectangle2D.Float - The location and size of the containing block of the shape.
getBoundsInPoints()
public Rectangle2D.Float getBoundsInPoints()
Gets the location and size of the containing block of the shape in points, relative to the anchor of the topmost shape.
Examples:
Shows how to verify shape containing block boundaries.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertShape(ShapeType.LINE, RelativeHorizontalPosition.LEFT_MARGIN, 50.0,
RelativeVerticalPosition.TOP_MARGIN, 50.0, 100.0, 100.0, WrapType.NONE);
shape.setStrokeColor(Color.ORANGE);
// Even though the line itself takes up little space on the document page,
// it occupies a rectangular containing block, the size of which we can determine using the "Bounds" properties.
Assert.assertEquals(new Rectangle2D.Float(50f, 50f, 100f, 100f), shape.getBounds());
Assert.assertEquals(new Rectangle2D.Float(50f, 50f, 100f, 100f), shape.getBoundsInPoints());
// Create a group shape, and then set the size of its containing block using the "Bounds" property.
GroupShape group = new GroupShape(doc);
group.setBounds(new Rectangle2D.Float(0f, 100f, 250f, 250f));
Assert.assertEquals(new Rectangle2D.Float(0f, 100f, 250f, 250f), group.getBoundsInPoints());
// Create a rectangle, verify the size of its bounding block, and then add it to the group shape.
shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(700.0);
shape.setTop(700.0);
}
Assert.assertEquals(new Rectangle2D.Float(700f, 700f, 100f, 100f), shape.getBoundsInPoints());
group.appendChild(shape);
// The group shape's coordinate plane has its origin on the top left-hand side corner of its containing block,
// and the x and y coordinates of (1000, 1000) on the bottom right-hand side corner.
// Our group shape is 250x250pt in size, so every 4pt on the group shape's coordinate plane
// translates to 1pt in the document body's coordinate plane.
// Every shape that we insert will also shrink in size by a factor of 4.
// The change in the shape's "BoundsInPoints" property will reflect this.
Assert.assertEquals(new Rectangle2D.Float(175f, 275f, 25f, 25f), shape.getBoundsInPoints());
doc.getFirstSection().getBody().getFirstParagraph().appendChild(group);
// Insert a shape and place it outside of the bounds of the group shape's containing block.
shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(1000.0);
shape.setTop(1000.0);
}
group.appendChild(shape);
// The group shape's footprint in the document body has increased, but the containing block remains the same.
Assert.assertEquals(new Rectangle2D.Float(0f, 100f, 250f, 250f), group.getBoundsInPoints());
Assert.assertEquals(new Rectangle2D.Float(250f, 350f, 25f, 25f), shape.getBoundsInPoints());
doc.save(getArtifactsDir() + "Shape.Bounds.docx");
Returns: java.awt.geom.Rectangle2D.Float - The location and size of the containing block of the shape in points, relative to the anchor of the topmost shape.
getBoundsWithEffects()
public Rectangle2D.Float getBoundsWithEffects()
Gets final extent that this shape object has after applying drawing effects. Value is measured in points.
Examples:
Shows how to check how a shape’s bounds are affected by shape effects.
Document doc = new Document(getMyDir() + "Shape shadow effect.docx");
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(shapeList.size(), 2);
Shape firstShape = shapeList.get(0);
Shape secondShape = shapeList.get(1);
// The two shapes are identical in terms of dimensions and shape type.
Assert.assertEquals(firstShape.getWidth(), secondShape.getWidth());
Assert.assertEquals(firstShape.getHeight(), secondShape.getHeight());
Assert.assertEquals(firstShape.getShapeType(), secondShape.getShapeType());
// The first shape has no effects, and the second one has a shadow and thick outline.
// These effects make the size of the second shape's silhouette bigger than that of the first.
// Even though the rectangle's size shows up when we click on these shapes in Microsoft Word,
// the visible outer bounds of the second shape are affected by the shadow and outline and thus are bigger.
// We can use the "AdjustWithEffects" method to see the true size of the shape.
Assert.assertEquals(0.0, firstShape.getStrokeWeight());
Assert.assertEquals(20.0, secondShape.getStrokeWeight());
Assert.assertFalse(firstShape.getShadowEnabled());
Assert.assertTrue(secondShape.getShadowEnabled());
Shape shape = firstShape;
// Run this method to get the size of the rectangle adjusted for all our shape effects.
Rectangle2D.Float rectangleFOut = shape.adjustWithEffects(new Rectangle2D.Float(200f, 200f, 1000f, 1000f));
// Since the shape has no border-changing effects, its boundary dimensions are unaffected.
Assert.assertEquals(200.0, rectangleFOut.getX());
Assert.assertEquals(200.0, rectangleFOut.getY());
Assert.assertEquals(1000.0, rectangleFOut.getWidth());
Assert.assertEquals(1000.0, rectangleFOut.getHeight());
// Verify the final extent of the first shape, in points.
Assert.assertEquals(0.0, shape.getBoundsWithEffects().getX());
Assert.assertEquals(0.0, shape.getBoundsWithEffects().getY());
Assert.assertEquals(147.0, shape.getBoundsWithEffects().getWidth());
Assert.assertEquals(147.0, shape.getBoundsWithEffects().getHeight());
shape = secondShape;
rectangleFOut = shape.adjustWithEffects(new Rectangle2D.Float(200f, 200f, 1000f, 1000f));
// The shape effects have moved the apparent top left corner of the shape slightly.
Assert.assertEquals(171.5, rectangleFOut.getX());
Assert.assertEquals(167.0, rectangleFOut.getY());
// The effects have also affected the visible dimensions of the shape.
Assert.assertEquals(1045.0, rectangleFOut.getWidth());
Assert.assertEquals(1133.5, rectangleFOut.getHeight());
// The effects have also affected the visible bounds of the shape.
Assert.assertEquals(-28.5, shape.getBoundsWithEffects().getX());
Assert.assertEquals(-33.0, shape.getBoundsWithEffects().getY());
Assert.assertEquals(192.0, shape.getBoundsWithEffects().getWidth());
Assert.assertEquals(280.5, shape.getBoundsWithEffects().getHeight());
Returns: java.awt.geom.Rectangle2D.Float - Final extent that this shape object has after applying drawing effects.
getChild(int nodeType, int index, boolean isDeep)
public Node getChild(int nodeType, int index, boolean isDeep)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| nodeType | int | |
| index | int | |
| isDeep | boolean |
Returns: Node
getChildNodes(int nodeType, boolean isDeep)
public NodeCollection getChildNodes(int nodeType, boolean isDeep)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| nodeType | int | |
| isDeep | boolean |
Returns: NodeCollection
getColor()
public Color getColor()
Returns: java.awt.Color
getContainer()
public CompositeNode getContainer()
Returns: CompositeNode
getCoordOrigin()
public Point getCoordOrigin()
The coordinates at the top-left corner of the containing block of this shape.
Remarks:
The default value is (0,0).
Examples:
Shows how to translate the x and y coordinate location on a shape’s coordinate plane to a location on the parent shape’s coordinate plane.
Document doc = new Document();
// Insert a group shape, and place it 100 points below and to the right of
// the document's x and Y coordinate origin point.
GroupShape group = new GroupShape(doc);
group.setBounds(new Rectangle2D.Float(100f, 100f, 500f, 500f));
// Use the "LocalToParent" method to determine that (0, 0) on the group's internal x and y coordinates
// lies on (100, 100) of its parent shape's coordinate system. The group shape's parent is the document itself.
Assert.assertEquals(new Point2D.Float(100f, 100f), group.localToParent(new Point2D.Float(0f, 0f)));
// By default, a shape's internal coordinate plane has the top left corner at (0, 0),
// and the bottom right corner at (1000, 1000). Due to its size, our group shape covers an area of 500pt x 500pt
// in the document's plane. This means that a movement of 1pt on the document's coordinate plane will translate
// to a movement of 2pts on the group shape's coordinate plane.
Assert.assertEquals(new Point2D.Float(150f, 150f), group.localToParent(new Point2D.Float(100f, 100f)));
Assert.assertEquals(new Point2D.Float(200f, 200f), group.localToParent(new Point2D.Float(200f, 200f)));
Assert.assertEquals(new Point2D.Float(250f, 250f), group.localToParent(new Point2D.Float(300f, 300f)));
// Move the group shape's x and y axis origin from the top left corner to the center.
// This will offset the group's internal coordinates relative to the document's coordinates even further.
group.setCoordOrigin(new Point(-250, -250));
Assert.assertEquals(new Point2D.Float(375f, 375f), group.localToParent(new Point2D.Float(300f, 300f)));
// Changing the scale of the coordinate plane will also affect relative locations.
group.setCoordSize(new Dimension(500, 500));
Assert.assertEquals(new Point2D.Float(650f, 650f), group.localToParent(new Point2D.Float(300f, 300f)));
// If we wish to add a shape to this group while defining its location based on a location in the document,
// we will need to first confirm a location in the group shape that will match the document's location.
Assert.assertEquals(new Point2D.Float(700f, 700f), group.localToParent(new Point2D.Float(350f, 350f)));
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(700.0);
shape.setTop(700.0);
}
group.appendChild(shape);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(group);
doc.save(getArtifactsDir() + "Shape.LocalToParent.docx");
Shows how to create and populate a group shape.
Document doc = new Document();
// Create a group shape. A group shape can display a collection of child shape nodes.
// In Microsoft Word, clicking within the group shape's boundary or on one of the group shape's child shapes will
// select all the other child shapes within this group and allow us to scale and move all the shapes at once.
GroupShape group = new GroupShape(doc);
Assert.assertEquals(WrapType.NONE, group.getWrapType());
// Create a 400pt x 400pt group shape and place it at the document's floating shape coordinate origin.
group.setBounds(new Rectangle2D.Float(0f, 0f, 400f, 400f));
// Set the group's internal coordinate plane size to 500 x 500pt.
// The top left corner of the group will have an x and y coordinate of (0, 0),
// and the bottom right corner will have an x and y coordinate of (500, 500).
group.setCoordSize(new Dimension(500, 500));
// Set the coordinates of the top left corner of the group to (-250, -250).
// The group's center will now have an x and y coordinate value of (0, 0),
// and the bottom right corner will be at (250, 250).
group.setCoordOrigin(new Point(-250, -250));
Shape rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(group.getCoordSize().width);
rectangleShape.setHeight(group.getCoordSize().height);
rectangleShape.setLeft(group.getCoordOrigin().x);
rectangleShape.setTop(group.getCoordOrigin().y);
// Create a rectangle that will display the boundary of this group shape and add it to the group.
group.appendChild(rectangleShape);
// Once a shape is a part of a group shape, we can access it as a child node and then modify it.
((Shape) group.getChild(NodeType.SHAPE, 0, true)).getStroke().setDashStyle(DashStyle.DASH);
Shape starShape = new Shape(doc, ShapeType.STAR);
starShape.setWidth(20.0);
starShape.setHeight(20.0);
starShape.setLeft(-10);
starShape.setTop(-10);
starShape.setFillColor(Color.RED);
// Create a small red star and insert it into the group.
// Line up the shape with the group's coordinate origin, which we have moved to the center.
group.appendChild(starShape);
rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(250.0);
rectangleShape.setHeight(250.0);
rectangleShape.setLeft(-250);
rectangleShape.setTop(-250);
rectangleShape.setFillColor(Color.BLUE);
// Insert a rectangle, and then insert a slightly smaller rectangle in the same place with an image.
// Newer shapes that we add to the group overlap older shapes. The light blue rectangle will partially overlap the red star,
// and then the shape with the image will overlap the light blue rectangle, using it as a frame.
// We cannot use the "ZOrder" properties of shapes to manipulate their arrangement within a group shape.
group.appendChild(rectangleShape);
Shape imageShape = new Shape(doc, ShapeType.IMAGE);
imageShape.setWidth(200.0);
imageShape.setHeight(200.0);
imageShape.setLeft(-225);
imageShape.setTop(-225);
group.appendChild(imageShape);
((Shape) group.getChild(NodeType.SHAPE, 3, true)).getImageData().setImage(getImageDir() + "Logo.jpg");
Shape textboxShape = new Shape(doc, ShapeType.TEXT_BOX);
textboxShape.setWidth(200.0);
textboxShape.setHeight(50.0);
textboxShape.setLeft(group.getCoordSize().width + new Point(group.getCoordOrigin()).x - 200);
textboxShape.setTop(group.getCoordSize().height + new Point(group.getCoordOrigin()).y);
// Insert a text box into the group shape. Set the "Left" property so that the text box's right edge
// touches the right boundary of the group shape. Set the "Top" property so that the text box sits outside
// the boundary of the group shape, with its top size lined up along the group shape's bottom margin.
group.appendChild(textboxShape);
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertNode(group);
builder.moveTo(((Shape) group.getChild(NodeType.SHAPE, 4, true)).appendChild(new Paragraph(doc)));
builder.write("Hello world!");
doc.save(getArtifactsDir() + "Shape.GroupShape.docx");
Returns: java.awt.Point - The corresponding java.awt.Point value.
getCoordSize()
public Dimension getCoordSize()
The width and height of the coordinate space inside the containing block of this shape.
Remarks:
The default value is (1000, 1000).
Examples:
Shows how to translate the x and y coordinate location on a shape’s coordinate plane to a location on the parent shape’s coordinate plane.
Document doc = new Document();
// Insert a group shape, and place it 100 points below and to the right of
// the document's x and Y coordinate origin point.
GroupShape group = new GroupShape(doc);
group.setBounds(new Rectangle2D.Float(100f, 100f, 500f, 500f));
// Use the "LocalToParent" method to determine that (0, 0) on the group's internal x and y coordinates
// lies on (100, 100) of its parent shape's coordinate system. The group shape's parent is the document itself.
Assert.assertEquals(new Point2D.Float(100f, 100f), group.localToParent(new Point2D.Float(0f, 0f)));
// By default, a shape's internal coordinate plane has the top left corner at (0, 0),
// and the bottom right corner at (1000, 1000). Due to its size, our group shape covers an area of 500pt x 500pt
// in the document's plane. This means that a movement of 1pt on the document's coordinate plane will translate
// to a movement of 2pts on the group shape's coordinate plane.
Assert.assertEquals(new Point2D.Float(150f, 150f), group.localToParent(new Point2D.Float(100f, 100f)));
Assert.assertEquals(new Point2D.Float(200f, 200f), group.localToParent(new Point2D.Float(200f, 200f)));
Assert.assertEquals(new Point2D.Float(250f, 250f), group.localToParent(new Point2D.Float(300f, 300f)));
// Move the group shape's x and y axis origin from the top left corner to the center.
// This will offset the group's internal coordinates relative to the document's coordinates even further.
group.setCoordOrigin(new Point(-250, -250));
Assert.assertEquals(new Point2D.Float(375f, 375f), group.localToParent(new Point2D.Float(300f, 300f)));
// Changing the scale of the coordinate plane will also affect relative locations.
group.setCoordSize(new Dimension(500, 500));
Assert.assertEquals(new Point2D.Float(650f, 650f), group.localToParent(new Point2D.Float(300f, 300f)));
// If we wish to add a shape to this group while defining its location based on a location in the document,
// we will need to first confirm a location in the group shape that will match the document's location.
Assert.assertEquals(new Point2D.Float(700f, 700f), group.localToParent(new Point2D.Float(350f, 350f)));
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(700.0);
shape.setTop(700.0);
}
group.appendChild(shape);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(group);
doc.save(getArtifactsDir() + "Shape.LocalToParent.docx");
Shows how to create and populate a group shape.
Document doc = new Document();
// Create a group shape. A group shape can display a collection of child shape nodes.
// In Microsoft Word, clicking within the group shape's boundary or on one of the group shape's child shapes will
// select all the other child shapes within this group and allow us to scale and move all the shapes at once.
GroupShape group = new GroupShape(doc);
Assert.assertEquals(WrapType.NONE, group.getWrapType());
// Create a 400pt x 400pt group shape and place it at the document's floating shape coordinate origin.
group.setBounds(new Rectangle2D.Float(0f, 0f, 400f, 400f));
// Set the group's internal coordinate plane size to 500 x 500pt.
// The top left corner of the group will have an x and y coordinate of (0, 0),
// and the bottom right corner will have an x and y coordinate of (500, 500).
group.setCoordSize(new Dimension(500, 500));
// Set the coordinates of the top left corner of the group to (-250, -250).
// The group's center will now have an x and y coordinate value of (0, 0),
// and the bottom right corner will be at (250, 250).
group.setCoordOrigin(new Point(-250, -250));
Shape rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(group.getCoordSize().width);
rectangleShape.setHeight(group.getCoordSize().height);
rectangleShape.setLeft(group.getCoordOrigin().x);
rectangleShape.setTop(group.getCoordOrigin().y);
// Create a rectangle that will display the boundary of this group shape and add it to the group.
group.appendChild(rectangleShape);
// Once a shape is a part of a group shape, we can access it as a child node and then modify it.
((Shape) group.getChild(NodeType.SHAPE, 0, true)).getStroke().setDashStyle(DashStyle.DASH);
Shape starShape = new Shape(doc, ShapeType.STAR);
starShape.setWidth(20.0);
starShape.setHeight(20.0);
starShape.setLeft(-10);
starShape.setTop(-10);
starShape.setFillColor(Color.RED);
// Create a small red star and insert it into the group.
// Line up the shape with the group's coordinate origin, which we have moved to the center.
group.appendChild(starShape);
rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(250.0);
rectangleShape.setHeight(250.0);
rectangleShape.setLeft(-250);
rectangleShape.setTop(-250);
rectangleShape.setFillColor(Color.BLUE);
// Insert a rectangle, and then insert a slightly smaller rectangle in the same place with an image.
// Newer shapes that we add to the group overlap older shapes. The light blue rectangle will partially overlap the red star,
// and then the shape with the image will overlap the light blue rectangle, using it as a frame.
// We cannot use the "ZOrder" properties of shapes to manipulate their arrangement within a group shape.
group.appendChild(rectangleShape);
Shape imageShape = new Shape(doc, ShapeType.IMAGE);
imageShape.setWidth(200.0);
imageShape.setHeight(200.0);
imageShape.setLeft(-225);
imageShape.setTop(-225);
group.appendChild(imageShape);
((Shape) group.getChild(NodeType.SHAPE, 3, true)).getImageData().setImage(getImageDir() + "Logo.jpg");
Shape textboxShape = new Shape(doc, ShapeType.TEXT_BOX);
textboxShape.setWidth(200.0);
textboxShape.setHeight(50.0);
textboxShape.setLeft(group.getCoordSize().width + new Point(group.getCoordOrigin()).x - 200);
textboxShape.setTop(group.getCoordSize().height + new Point(group.getCoordOrigin()).y);
// Insert a text box into the group shape. Set the "Left" property so that the text box's right edge
// touches the right boundary of the group shape. Set the "Top" property so that the text box sits outside
// the boundary of the group shape, with its top size lined up along the group shape's bottom margin.
group.appendChild(textboxShape);
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertNode(group);
builder.moveTo(((Shape) group.getChild(NodeType.SHAPE, 4, true)).appendChild(new Paragraph(doc)));
builder.write("Hello world!");
doc.save(getArtifactsDir() + "Shape.GroupShape.docx");
Returns: java.awt.Dimension - The corresponding java.awt.Dimension value.
getCount()
public int getCount()
Gets the number of immediate children of this node.
Examples:
Shows how to add, update and delete child nodes in a CompositeNode’s collection of children.
Document doc = new Document();
// An empty document, by default, has one paragraph.
Assert.assertEquals(1, doc.getFirstSection().getBody().getParagraphs().getCount());
// Composite nodes such as our paragraph can contain other composite and inline nodes as children.
Paragraph paragraph = doc.getFirstSection().getBody().getFirstParagraph();
Run paragraphText = new Run(doc, "Initial text. ");
paragraph.appendChild(paragraphText);
// Create three more run nodes.
Run run1 = new Run(doc, "Run 1. ");
Run run2 = new Run(doc, "Run 2. ");
Run run3 = new Run(doc, "Run 3. ");
// The document body will not display these runs until we insert them into a composite node
// that itself is a part of the document's node tree, as we did with the first run.
// We can determine where the text contents of nodes that we insert
// appears in the document by specifying an insertion location relative to another node in the paragraph.
Assert.assertEquals("Initial text.", paragraph.getText().trim());
// Insert the second run into the paragraph in front of the initial run.
paragraph.insertBefore(run2, paragraphText);
Assert.assertEquals("Run 2. Initial text.", paragraph.getText().trim());
// Insert the third run after the initial run.
paragraph.insertAfter(run3, paragraphText);
Assert.assertEquals("Run 2. Initial text. Run 3.", paragraph.getText().trim());
// Insert the first run to the start of the paragraph's child nodes collection.
paragraph.prependChild(run1);
Assert.assertEquals("Run 1. Run 2. Initial text. Run 3.", paragraph.getText().trim());
Assert.assertEquals(4, paragraph.getChildNodes(NodeType.ANY, true).getCount());
// We can modify the contents of the run by editing and deleting existing child nodes.
((Run) paragraph.getChildNodes(NodeType.RUN, true).get(1)).setText("Updated run 2. ");
paragraph.getChildNodes(NodeType.RUN, true).remove(paragraphText);
Assert.assertEquals("Run 1. Updated run 2. Run 3.", paragraph.getText().trim());
Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, true).getCount());
Returns: int - The number of immediate children of this node.
getCurrentNode()
public Node getCurrentNode()
Returns: Node
getCustomNodeId()
public int getCustomNodeId()
Specifies custom node identifier.
Remarks:
Default is zero.
This identifier can be set and used arbitrarily. For example, as a key to get external data.
Important note, specified value is not saved to an output file and exists only during the node lifetime.
Examples:
Shows how to traverse through a composite node’s collection of child nodes.
Document doc = new Document();
// Add two runs and one shape as child nodes to the first paragraph of this document.
Paragraph paragraph = (Paragraph) doc.getChild(NodeType.PARAGRAPH, 0, true);
paragraph.appendChild(new Run(doc, "Hello world! "));
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
shape.setWidth(200.0);
shape.setHeight(200.0);
// Note that the 'CustomNodeId' is not saved to an output file and exists only during the node lifetime.
shape.setCustomNodeId(100);
shape.setWrapType(WrapType.INLINE);
paragraph.appendChild(shape);
paragraph.appendChild(new Run(doc, "Hello again!"));
// Iterate through the paragraph's collection of immediate children,
// and print any runs or shapes that we find within.
NodeCollection children = paragraph.getChildNodes(NodeType.ANY, false);
Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, false).getCount());
for (Node child : (Iterable) children)
switch (child.getNodeType()) {
case NodeType.RUN:
System.out.println("Run contents:");
System.out.println(MessageFormat.format("\t\"{0}\"", child.getText().trim()));
break;
case NodeType.SHAPE:
Shape childShape = (Shape)child;
System.out.println("Shape:");
System.out.println(MessageFormat.format("\t{0}, {1}x{2}", childShape.getShapeType(), childShape.getWidth(), childShape.getHeight()));
break;
}
Returns: int - The corresponding int value.
getDirectRunAttr(int fontAttr)
public Object getDirectRunAttr(int fontAttr)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| fontAttr | int |
Returns: java.lang.Object
getDirectRunAttr(int key, int revisionsView)
public Object getDirectRunAttr(int key, int revisionsView)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | int | |
| revisionsView | int |
Returns: java.lang.Object
getDirectShapeAttr(int key)
public Object getDirectShapeAttr(int key)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | int |
Returns: java.lang.Object
getDistance()
public double getDistance()
Returns: double
getDistanceBottom()
public double getDistanceBottom()
Gets the distance (in points) between the document text and the bottom edge of the shape.
Remarks:
The default value is 0.
Has effect only for top level shapes.
Examples:
Shows how to set the wrapping distance for a text that surrounds a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a rectangle and, get the text to wrap tightly around its bounds.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 150.0, 150.0);
shape.setWrapType(WrapType.TIGHT);
// Set the minimum distance between the shape and surrounding text to 40pt from all sides.
shape.setDistanceTop(40.0);
shape.setDistanceBottom(40.0);
shape.setDistanceLeft(40.0);
shape.setDistanceRight(40.0);
// Move the shape closer to the center of the page, and then rotate the shape 60 degrees clockwise.
shape.setTop(75.0);
shape.setLeft(150.0);
shape.setRotation(60.0);
// Add text that will wrap around the shape.
builder.getFont().setSize(24.0d);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
doc.save(getArtifactsDir() + "Shape.Coordinates.docx");
Returns: double - The distance (in points) between the document text and the bottom edge of the shape.
getDistanceLeft()
public double getDistanceLeft()
Gets the distance (in points) between the document text and the left edge of the shape.
Remarks:
The default value is 1/8 inch.
Has effect only for top level shapes.
Examples:
Shows how to set the wrapping distance for a text that surrounds a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a rectangle and, get the text to wrap tightly around its bounds.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 150.0, 150.0);
shape.setWrapType(WrapType.TIGHT);
// Set the minimum distance between the shape and surrounding text to 40pt from all sides.
shape.setDistanceTop(40.0);
shape.setDistanceBottom(40.0);
shape.setDistanceLeft(40.0);
shape.setDistanceRight(40.0);
// Move the shape closer to the center of the page, and then rotate the shape 60 degrees clockwise.
shape.setTop(75.0);
shape.setLeft(150.0);
shape.setRotation(60.0);
// Add text that will wrap around the shape.
builder.getFont().setSize(24.0d);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
doc.save(getArtifactsDir() + "Shape.Coordinates.docx");
Returns: double - The distance (in points) between the document text and the left edge of the shape.
getDistanceRight()
public double getDistanceRight()
Gets the distance (in points) between the document text and the right edge of the shape.
Remarks:
The default value is 1/8 inch.
Has effect only for top level shapes.
Examples:
Shows how to set the wrapping distance for a text that surrounds a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a rectangle and, get the text to wrap tightly around its bounds.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 150.0, 150.0);
shape.setWrapType(WrapType.TIGHT);
// Set the minimum distance between the shape and surrounding text to 40pt from all sides.
shape.setDistanceTop(40.0);
shape.setDistanceBottom(40.0);
shape.setDistanceLeft(40.0);
shape.setDistanceRight(40.0);
// Move the shape closer to the center of the page, and then rotate the shape 60 degrees clockwise.
shape.setTop(75.0);
shape.setLeft(150.0);
shape.setRotation(60.0);
// Add text that will wrap around the shape.
builder.getFont().setSize(24.0d);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
doc.save(getArtifactsDir() + "Shape.Coordinates.docx");
Returns: double - The distance (in points) between the document text and the right edge of the shape.
getDistanceTop()
public double getDistanceTop()
Gets the distance (in points) between the document text and the top edge of the shape.
Remarks:
The default value is 0.
Has effect only for top level shapes.
Examples:
Shows how to set the wrapping distance for a text that surrounds a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a rectangle and, get the text to wrap tightly around its bounds.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 150.0, 150.0);
shape.setWrapType(WrapType.TIGHT);
// Set the minimum distance between the shape and surrounding text to 40pt from all sides.
shape.setDistanceTop(40.0);
shape.setDistanceBottom(40.0);
shape.setDistanceLeft(40.0);
shape.setDistanceRight(40.0);
// Move the shape closer to the center of the page, and then rotate the shape 60 degrees clockwise.
shape.setTop(75.0);
shape.setLeft(150.0);
shape.setRotation(60.0);
// Add text that will wrap around the shape.
builder.getFont().setSize(24.0d);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
doc.save(getArtifactsDir() + "Shape.Coordinates.docx");
Returns: double - The distance (in points) between the document text and the top edge of the shape.
getDocument()
public DocumentBase getDocument()
Gets the document to which this node belongs.
Remarks:
The node always belongs to a document even if it has just been created and not yet added to the tree, or if it has been removed from the tree.
Examples:
Shows how to create a node and set its owning document.
Document doc = new Document();
Paragraph para = new Paragraph(doc);
para.appendChild(new Run(doc, "Hello world!"));
// We have not yet appended this paragraph as a child to any composite node.
Assert.assertNull(para.getParentNode());
// If a node is an appropriate child node type of another composite node,
// we can attach it as a child only if both nodes have the same owner document.
// The owner document is the document we passed to the node's constructor.
// We have not attached this paragraph to the document, so the document does not contain its text.
Assert.assertEquals(para.getDocument(), doc);
Assert.assertEquals("", doc.getText().trim());
// Since the document owns this paragraph, we can apply one of its styles to the paragraph's contents.
para.getParagraphFormat().setStyleName("Heading 1");
// Add this node to the document, and then verify its contents.
doc.getFirstSection().getBody().appendChild(para);
Assert.assertEquals(doc.getFirstSection().getBody(), para.getParentNode());
Assert.assertEquals("Hello world!", doc.getText().trim());
Returns: DocumentBase - The document to which this node belongs.
getDocument_IInline()
public DocumentBase getDocument_IInline()
Returns: DocumentBase
getEdgeRadius()
public double getEdgeRadius()
Returns: double
getFill()
public Fill getFill()
Gets fill formatting for the shape.
Examples:
Shows how to fill a shape with a solid color.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Write some text, and then cover it with a floating shape.
builder.getFont().setSize(32.0);
builder.writeln("Hello world!");
Shape shape = builder.insertShape(ShapeType.CLOUD_CALLOUT, RelativeHorizontalPosition.LEFT_MARGIN, 25.0,
RelativeVerticalPosition.TOP_MARGIN, 25.0, 250.0, 150.0, WrapType.NONE);
// Use the "StrokeColor" property to set the color of the outline of the shape.
shape.setStrokeColor(Color.BLACK);
// Use the "FillColor" property to set the color of the inside area of the shape.
shape.setFillColor(Color.BLUE);
// The "Opacity" property determines how transparent the color is on a 0-1 scale,
// with 1 being fully opaque, and 0 being invisible.
// The shape fill by default is fully opaque, so we cannot see the text that this shape is on top of.
Assert.assertEquals(1.0d, shape.getFill().getOpacity());
// Set the shape fill color's opacity to a lower value so that we can see the text underneath it.
shape.getFill().setOpacity(0.3);
doc.save(getArtifactsDir() + "Shape.Fill.docx");
Returns: Fill - Fill formatting for the shape.
getFillType()
public int getFillType()
Returns: int
getFillableBackColor()
public Color getFillableBackColor()
Returns: java.awt.Color
getFillableBackThemeColor()
public int getFillableBackThemeColor()
Returns: int
getFillableBackTintAndShade()
public double getFillableBackTintAndShade()
Returns: double
getFillableBaseForeColor()
public Color getFillableBaseForeColor()
Returns: java.awt.Color
getFillableForeColor()
public Color getFillableForeColor()
Returns: java.awt.Color
getFillableForeThemeColor()
public int getFillableForeThemeColor()
Returns: int
getFillableForeTintAndShade()
public double getFillableForeTintAndShade()
Returns: double
getFillableImageBytes()
public byte[] getFillableImageBytes()
Returns: byte[]
getFillableTransparency()
public double getFillableTransparency()
Returns: double
getFillableVisible()
public boolean getFillableVisible()
Returns: boolean
getFilledColor()
public Color getFilledColor()
Returns: java.awt.Color
getFirstChild()
public Node getFirstChild()
Gets the first child of the node.
Remarks:
If there is no first child node, a null is returned.
Examples:
Shows how to use a node’s NextSibling property to enumerate through its immediate children.
Document doc = new Document(getMyDir() + "Paragraphs.docx");
for (Node node = doc.getFirstSection().getBody().getFirstChild(); node != null; node = node.getNextSibling()) {
System.out.println(Node.nodeTypeToString(node.getNodeType()));
}
Shows how to traverse a composite node’s tree of child nodes.
public void recurseChildren() throws Exception {
Document doc = new Document(getMyDir() + "Paragraphs.docx");
// Any node that can contain child nodes, such as the document itself, is composite.
Assert.assertTrue(doc.isComposite());
// Invoke the recursive function that will go through and print all the child nodes of a composite node.
traverseAllNodes(doc, 0);
}
///
/// Recursively traverses a node tree while printing the type of each node
/// with an indent depending on depth as well as the contents of all inline nodes.
///
public void traverseAllNodes(CompositeNode parentNode, int depth) {
for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
System.out.println(MessageFormat.format("{0}{1}", String.format(" ", depth), Node.nodeTypeToString(childNode.getNodeType())));
// Recurse into the node if it is a composite node. Otherwise, print its contents if it is an inline node.
if (childNode.isComposite()) {
System.out.println();
traverseAllNodes((CompositeNode) childNode, depth + 1);
} else if (childNode instanceof Inline) {
System.out.println(MessageFormat.format(" - \"{0}\"", childNode.getText().trim()));
} else {
System.out.println();
}
}
}
Returns: Node - The first child of the node.
getFlipOrientation()
public int getFlipOrientation()
Switches the orientation of a shape.
Remarks:
The default value is FlipOrientation.NONE.
Examples:
Shows how to flip a shape on an axis.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert an image shape and leave its orientation in its default state.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 100.0,
RelativeVerticalPosition.TOP_MARGIN, 100.0, 100.0, 100.0, WrapType.NONE);
shape.getImageData().setImage(getImageDir() + "Logo.jpg");
Assert.assertEquals(FlipOrientation.NONE, shape.getFlipOrientation());
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 250.0,
RelativeVerticalPosition.TOP_MARGIN, 100.0, 100.0, 100.0, WrapType.NONE);
shape.getImageData().setImage(getImageDir() + "Logo.jpg");
// Set the "FlipOrientation" property to "FlipOrientation.Horizontal" to flip the second shape on the y-axis,
// making it into a horizontal mirror image of the first shape.
shape.setFlipOrientation(FlipOrientation.HORIZONTAL);
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 100.0,
RelativeVerticalPosition.TOP_MARGIN, 250.0, 100.0, 100.0, WrapType.NONE);
shape.getImageData().setImage(getImageDir() + "Logo.jpg");
// Set the "FlipOrientation" property to "FlipOrientation.Horizontal" to flip the third shape on the x-axis,
// making it into a vertical mirror image of the first shape.
shape.setFlipOrientation(FlipOrientation.VERTICAL);
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 250.0,
RelativeVerticalPosition.TOP_MARGIN, 250.0, 100.0, 100.0, WrapType.NONE);
shape.getImageData().setImage(getImageDir() + "Logo.jpg");
// Set the "FlipOrientation" property to "FlipOrientation.Horizontal" to flip the fourth shape on both the x and y axes,
// making it into a horizontal and vertical mirror image of the first shape.
shape.setFlipOrientation(FlipOrientation.BOTH);
doc.save(getArtifactsDir() + "Shape.FlipShapeOrientation.docx");
Returns: int - The corresponding int value. The returned value is a bitwise combination of FlipOrientation constants.
getFont()
public Font getFont()
Provides access to the font formatting of this object.
Examples:
Shows how to insert a text box, and set the font of its contents.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
Shape shape = builder.insertShape(ShapeType.TEXT_BOX, 300.0, 50.0);
builder.moveTo(shape.getLastParagraph());
builder.write("This text is inside the text box.");
// Set the "Hidden" property of the shape's "Font" object to "true" to hide the text box from sight
// and collapse the space that it would normally occupy.
// Set the "Hidden" property of the shape's "Font" object to "false" to leave the text box visible.
shape.getFont().setHidden(hideShape);
// If the shape is visible, we will modify its appearance via the font object.
if (!hideShape) {
shape.getFont().setHighlightColor(Color.LIGHT_GRAY);
shape.getFont().setColor(Color.RED);
shape.getFont().setUnderline(Underline.DASH);
}
// Move the builder out of the text box back into the main document.
builder.moveTo(shape.getParentParagraph());
builder.writeln("\nThis text is outside the text box.");
doc.save(getArtifactsDir() + "Shape.Font.docx");
Returns: Font - The corresponding Font value.
getGlow()
public GlowFormat getGlow()
Gets glow formatting for the shape.
Examples:
Shows how to interact with glow shape effect.
Document doc = new Document(getMyDir() + "Various shapes.docx");
Shape shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
// Apply glow effect to the shape.
shape.getGlow().setColor(new Color(0xFFFA8072));
shape.getGlow().setRadius(30.0);
shape.getGlow().setTransparency(0.15);
doc.save(getArtifactsDir() + "Shape.Glow.docx");
doc = new Document(getArtifactsDir() + "Shape.Glow.docx");
shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
// Check glow effect attributes.
Assert.assertEquals(new Color((250), (128), (114), (217)).getRGB(), shape.getGlow().getColor().getRGB());
Assert.assertEquals(30, shape.getGlow().getRadius());
Assert.assertEquals(0.15d, shape.getGlow().getTransparency(), 0.01d);
// Remove glow effect from the shape.
shape.getGlow().remove();
Assert.assertEquals(Color.BLACK.getRGB(), shape.getGlow().getColor().getRGB());
Assert.assertEquals(0, shape.getGlow().getRadius());
Assert.assertEquals(0, shape.getGlow().getTransparency());
Returns: GlowFormat - Glow formatting for the shape.
getGradientAngle()
public double getGradientAngle()
Returns: double
getGradientStops()
public GradientStopCollection getGradientStops()
Returns: GradientStopCollection
getGradientStyle()
public int getGradientStyle()
Returns: int
getGradientVariant()
public int getGradientVariant()
Returns: int
getHRef()
public String getHRef()
Gets the full hyperlink address for a shape.
Remarks:
The default value is an empty string.
Below are examples of valid values for this property:
Full URI: https://www.aspose.com/ .
Full file name: C:\\My Documents\\SalesReport.doc .
Relative URI: ../../../resource.txt
Relative file name: ..\\My Documents\\SalesReport.doc .
Bookmark within another document: https://www.aspose.com/Products/Default.aspx#Suites
Bookmark within this document: #BookmakName .
Examples:
Shows how to insert a shape which contains an image, and is also a hyperlink.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setHRef("https://forum.aspose.com/");
shape.setTarget("New Window");
shape.setScreenTip("Aspose.Words Support Forums");
// Ctrl + left-clicking the shape in Microsoft Word will open a new web browser window
// and take us to the hyperlink in the "HRef" property.
doc.save(getArtifactsDir() + "Image.InsertImageWithHyperlink.docx");
Returns: java.lang.String - The full hyperlink address for a shape.
getHeight()
public double getHeight()
Gets the height of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points.
For shapes in a group, the value is in the coordinate space and units of the parent group.
The default value is 0.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Shows how to resize a shape with an image.
// When we insert an image using the "InsertImage" method, the builder scales the shape that displays the image so that,
// when we view the document using 100% zoom in Microsoft Word, the shape displays the image in its actual size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
// A 400x400 image will create an ImageData object with an image size of 300x300pt.
ImageSize imageSize = shape.getImageData().getImageSize();
Assert.assertEquals(300.0d, imageSize.getWidthPoints());
Assert.assertEquals(300.0d, imageSize.getHeightPoints());
// If a shape's dimensions match the image data's dimensions,
// then the shape is displaying the image in its original size.
Assert.assertEquals(300.0d, shape.getWidth());
Assert.assertEquals(300.0d, shape.getHeight());
// Reduce the overall size of the shape by 50%.
shape.setWidth(shape.getWidth() * 0.5);
// Scaling factors apply to both the width and the height at the same time to preserve the shape's proportions.
Assert.assertEquals(150.0d, shape.getWidth());
Assert.assertEquals(150.0d, shape.getHeight());
// When we resize the shape, the size of the image data remains the same.
Assert.assertEquals(300.0d, imageSize.getWidthPoints());
Assert.assertEquals(300.0d, imageSize.getHeightPoints());
// We can reference the image data dimensions to apply a scaling based on the size of the image.
shape.setWidth(imageSize.getWidthPoints() * 1.1);
Assert.assertEquals(330.0d, shape.getWidth());
Assert.assertEquals(330.0d, shape.getHeight());
doc.save(getArtifactsDir() + "Image.ScaleImage.docx");
Returns: double - The height of the containing block of the shape.
getHeightRelative()
public float getHeightRelative()
Gets the value that represents the percentage of shape’s relative height.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Returns: float - The value that represents the percentage of shape’s relative height.
getHidden()
public boolean getHidden()
Gets a boolean value indicating whether the shape is visible.
Remarks:
The default value is false .
Examples:
Shows how to hide the shape.
Document doc = new Document(getMyDir() + "Shadow color.docx");
Shape shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
if (!shape.getHidden())
shape.setHidden(true);
doc.save(getArtifactsDir() + "Shape.Hidden.docx");
Returns: boolean - A boolean value indicating whether the shape is visible.
getHorizontalAlignment()
public int getHorizontalAlignment()
Specifies how the shape is positioned horizontally.
Remarks:
The default value is HorizontalAlignment.NONE.
Has effect only for top level floating shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Returns: int - The corresponding int value. The returned value is one of HorizontalAlignment constants.
getLastChild()
public Node getLastChild()
Gets the last child of the node.
Remarks:
If there is no last child node, a null is returned.
Examples:
Shows how to use of methods of Node and CompositeNode to remove a section before the last section in the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Section 1 text.");
builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
builder.writeln("Section 2 text.");
// Both sections are siblings of each other.
Section lastSection = (Section) doc.getLastChild();
Section firstSection = (Section) lastSection.getPreviousSibling();
// Remove a section based on its sibling relationship with another section.
if (lastSection.getPreviousSibling() != null)
doc.removeChild(firstSection);
// The section we removed was the first one, leaving the document with only the second.
Assert.assertEquals("Section 2 text.", doc.getText().trim());
Returns: Node - The last child of the node.
getLeft()
public double getLeft()
Gets the position of the left edge of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points and relative to the shape anchor.
For shapes in a group, the value is in the coordinate space and units of the parent group.
The default value is 0.
Has effect only for floating shapes.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Returns: double - The position of the left edge of the containing block of the shape.
getLeftRelative()
public float getLeftRelative()
Gets the value that represents shape’s relative left position in percent.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Returns: float - The value that represents shape’s relative left position in percent.
getMarkupLanguage()
public byte getMarkupLanguage()
Gets MarkupLanguage used for this graphic object.
Examples:
Shows how to verify a shape’s size and markup language.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Transparent background logo.png");
Assert.assertEquals(ShapeMarkupLanguage.DML, shape.getMarkupLanguage());
Assert.assertEquals(new Point2D.Float(300f, 300f), shape.getSizeInPoints());
Returns: byte - MarkupLanguage used for this graphic object. The returned value is one of ShapeMarkupLanguage constants.
getName()
public String getName()
Gets the optional shape name.
Remarks:
Default is empty string.
Cannot be null , but can be an empty string.
Examples:
Shows how to use a shape’s alternative text.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertShape(ShapeType.CUBE, 150.0, 150.0);
shape.setName("MyCube");
shape.setAlternativeText("Alt text for MyCube.");
// We can access the alternative text of a shape by right-clicking it, and then via "Format AutoShape" -> "Alt Text".
doc.save(getArtifactsDir() + "Shape.AltText.docx");
// Save the document to HTML, and then delete the linked image that belongs to our shape.
// The browser that is reading our HTML will display the alt text in place of the missing image.
doc.save(getArtifactsDir() + "Shape.AltText.html");
new File(getArtifactsDir() + "Shape.AltText.001.png").delete();
Returns: java.lang.String - The optional shape name.
getNextMatchingNode(Node curNode)
public Node getNextMatchingNode(Node curNode)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| curNode | Node |
Returns: Node
getNextSibling()
public Node getNextSibling()
Gets the node immediately following this node.
Remarks:
If there is no next node, a null is returned.
Examples:
Shows how to use a node’s NextSibling property to enumerate through its immediate children.
Document doc = new Document(getMyDir() + "Paragraphs.docx");
for (Node node = doc.getFirstSection().getBody().getFirstChild(); node != null; node = node.getNextSibling()) {
System.out.println(Node.nodeTypeToString(node.getNodeType()));
}
Shows how to traverse a composite node’s tree of child nodes.
public void recurseChildren() throws Exception {
Document doc = new Document(getMyDir() + "Paragraphs.docx");
// Any node that can contain child nodes, such as the document itself, is composite.
Assert.assertTrue(doc.isComposite());
// Invoke the recursive function that will go through and print all the child nodes of a composite node.
traverseAllNodes(doc, 0);
}
///
/// Recursively traverses a node tree while printing the type of each node
/// with an indent depending on depth as well as the contents of all inline nodes.
///
public void traverseAllNodes(CompositeNode parentNode, int depth) {
for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
System.out.println(MessageFormat.format("{0}{1}", String.format(" ", depth), Node.nodeTypeToString(childNode.getNodeType())));
// Recurse into the node if it is a composite node. Otherwise, print its contents if it is an inline node.
if (childNode.isComposite()) {
System.out.println();
traverseAllNodes((CompositeNode) childNode, depth + 1);
} else if (childNode instanceof Inline) {
System.out.println(MessageFormat.format(" - \"{0}\"", childNode.getText().trim()));
} else {
System.out.println();
}
}
}
Returns: Node - The node immediately following this node.
getNodeType()
public abstract int getNodeType()
Gets the type of this node.
Examples:
Shows how to use a node’s NextSibling property to enumerate through its immediate children.
Document doc = new Document(getMyDir() + "Paragraphs.docx");
for (Node node = doc.getFirstSection().getBody().getFirstChild(); node != null; node = node.getNextSibling()) {
System.out.println(Node.nodeTypeToString(node.getNodeType()));
}
Shows how to remove all child nodes of a specific type from a composite node.
Document doc = new Document(getMyDir() + "Tables.docx");
Assert.assertEquals(2, doc.getChildNodes(NodeType.TABLE, true).getCount());
Node curNode = doc.getFirstSection().getBody().getFirstChild();
while (curNode != null) {
// Save the next sibling node as a variable in case we want to move to it after deleting this node.
Node nextNode = curNode.getNextSibling();
// A section body can contain Paragraph and Table nodes.
// If the node is a Table, remove it from the parent.
if (curNode.getNodeType() == NodeType.TABLE) {
curNode.remove();
}
curNode = nextNode;
}
Assert.assertEquals(0, doc.getChildNodes(NodeType.TABLE, true).getCount());
Shows how to traverse a composite node’s tree of child nodes.
public void recurseChildren() throws Exception {
Document doc = new Document(getMyDir() + "Paragraphs.docx");
// Any node that can contain child nodes, such as the document itself, is composite.
Assert.assertTrue(doc.isComposite());
// Invoke the recursive function that will go through and print all the child nodes of a composite node.
traverseAllNodes(doc, 0);
}
///
/// Recursively traverses a node tree while printing the type of each node
/// with an indent depending on depth as well as the contents of all inline nodes.
///
public void traverseAllNodes(CompositeNode parentNode, int depth) {
for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
System.out.println(MessageFormat.format("{0}{1}", String.format(" ", depth), Node.nodeTypeToString(childNode.getNodeType())));
// Recurse into the node if it is a composite node. Otherwise, print its contents if it is an inline node.
if (childNode.isComposite()) {
System.out.println();
traverseAllNodes((CompositeNode) childNode, depth + 1);
} else if (childNode instanceof Inline) {
System.out.println(MessageFormat.format(" - \"{0}\"", childNode.getText().trim()));
} else {
System.out.println();
}
}
}
Returns: int - The type of this node. The returned value is one of NodeType constants.
getOldOn()
public boolean getOldOn()
Returns: boolean
getOldOpacity()
public double getOldOpacity()
Returns: double
getParentNode()
public CompositeNode getParentNode()
Gets the immediate parent of this node.
Remarks:
If a node has just been created and not yet added to the tree, or if it has been removed from the tree, the parent is null .
Examples:
Shows how to access a node’s parent node.
Document doc = new Document();
Paragraph para = doc.getFirstSection().getBody().getFirstParagraph();
// Append a child Run node to the document's first paragraph.
Run run = new Run(doc, "Hello world!");
para.appendChild(run);
// The paragraph is the parent node of the run node. We can trace this lineage
// all the way to the document node, which is the root of the document's node tree.
Assert.assertEquals(para, run.getParentNode());
Assert.assertEquals(doc.getFirstSection().getBody(), para.getParentNode());
Assert.assertEquals(doc.getFirstSection(), doc.getFirstSection().getBody().getParentNode());
Assert.assertEquals(doc, doc.getFirstSection().getParentNode());
Shows how to create a node and set its owning document.
Document doc = new Document();
Paragraph para = new Paragraph(doc);
para.appendChild(new Run(doc, "Hello world!"));
// We have not yet appended this paragraph as a child to any composite node.
Assert.assertNull(para.getParentNode());
// If a node is an appropriate child node type of another composite node,
// we can attach it as a child only if both nodes have the same owner document.
// The owner document is the document we passed to the node's constructor.
// We have not attached this paragraph to the document, so the document does not contain its text.
Assert.assertEquals(para.getDocument(), doc);
Assert.assertEquals("", doc.getText().trim());
// Since the document owns this paragraph, we can apply one of its styles to the paragraph's contents.
para.getParagraphFormat().setStyleName("Heading 1");
// Add this node to the document, and then verify its contents.
doc.getFirstSection().getBody().appendChild(para);
Assert.assertEquals(doc.getFirstSection().getBody(), para.getParentNode());
Assert.assertEquals("Hello world!", doc.getText().trim());
Returns: CompositeNode - The immediate parent of this node.
getParentParagraph()
public Paragraph getParentParagraph()
Returns the immediate parent paragraph.
Remarks:
For child shapes of a group shape and child shapes of an Office Math object always returns null .
Examples:
Shows how to insert a text box, and set the font of its contents.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
Shape shape = builder.insertShape(ShapeType.TEXT_BOX, 300.0, 50.0);
builder.moveTo(shape.getLastParagraph());
builder.write("This text is inside the text box.");
// Set the "Hidden" property of the shape's "Font" object to "true" to hide the text box from sight
// and collapse the space that it would normally occupy.
// Set the "Hidden" property of the shape's "Font" object to "false" to leave the text box visible.
shape.getFont().setHidden(hideShape);
// If the shape is visible, we will modify its appearance via the font object.
if (!hideShape) {
shape.getFont().setHighlightColor(Color.LIGHT_GRAY);
shape.getFont().setColor(Color.RED);
shape.getFont().setUnderline(Underline.DASH);
}
// Move the builder out of the text box back into the main document.
builder.moveTo(shape.getParentParagraph());
builder.writeln("\nThis text is outside the text box.");
doc.save(getArtifactsDir() + "Shape.Font.docx");
Returns: Paragraph - The immediate parent paragraph.
getParentParagraph_IInline()
public Paragraph getParentParagraph_IInline()
Returns: Paragraph
getPatternType()
public int getPatternType()
Returns: int
getPresetTexture()
public int getPresetTexture()
Returns: int
getPreviousSibling()
public Node getPreviousSibling()
Gets the node immediately preceding this node.
Remarks:
If there is no preceding node, a null is returned.
Examples:
Shows how to use of methods of Node and CompositeNode to remove a section before the last section in the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Section 1 text.");
builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
builder.writeln("Section 2 text.");
// Both sections are siblings of each other.
Section lastSection = (Section) doc.getLastChild();
Section firstSection = (Section) lastSection.getPreviousSibling();
// Remove a section based on its sibling relationship with another section.
if (lastSection.getPreviousSibling() != null)
doc.removeChild(firstSection);
// The section we removed was the first one, leaving the document with only the second.
Assert.assertEquals("Section 2 text.", doc.getText().trim());
Returns: Node - The node immediately preceding this node.
getRadius()
public double getRadius()
Returns: double
getRange()
public Range getRange()
Returns a Range object that represents the portion of a document that is contained in this node.
Examples:
Shows how to delete all the nodes from a range.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Add text to the first section in the document, and then add another section.
builder.write("Section 1. ");
builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
builder.write("Section 2.");
Assert.assertEquals("Section 1. \fSection 2.", doc.getText().trim());
// Remove the first section entirely by removing all the nodes
// within its range, including the section itself.
doc.getSections().get(0).getRange().delete();
Assert.assertEquals(1, doc.getSections().getCount());
Assert.assertEquals("Section 2.", doc.getText().trim());
Returns: Range - A Range object that represents the portion of a document that is contained in this node.
getReflection()
public ReflectionFormat getReflection()
Gets reflection formatting for the shape.
Examples:
Shows how to interact with reflection shape effect.
Document doc = new Document(getMyDir() + "Various shapes.docx");
Shape shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
// Apply reflection effect to the shape.
shape.getReflection().setTransparency(0.37);
shape.getReflection().setSize(0.48);
shape.getReflection().setBlur(17.5);
shape.getReflection().setDistance(9.2);
doc.save(getArtifactsDir() + "Shape.Reflection.docx");
doc = new Document(getArtifactsDir() + "Shape.Reflection.docx");
shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
// Check reflection effect attributes.
Assert.assertEquals(0.37d, shape.getReflection().getTransparency(), 0.01d);
Assert.assertEquals(0.48d, shape.getReflection().getSize(), 0.01d);
Assert.assertEquals(17.5d, shape.getReflection().getBlur(), 0.01d);
Assert.assertEquals(9.2d, shape.getReflection().getDistance(), 0.01d);
// Remove reflection effect from the shape.
shape.getReflection().remove();
Assert.assertEquals(0, shape.getReflection().getTransparency());
Assert.assertEquals(0, shape.getReflection().getSize());
Assert.assertEquals(0, shape.getReflection().getBlur());
Assert.assertEquals(0, shape.getReflection().getDistance());
Returns: ReflectionFormat - Reflection formatting for the shape.
getReflectionSize()
public double getReflectionSize()
Returns: double
getReflectionTransparency()
public double getReflectionTransparency()
Returns: double
getRelativeHorizontalPosition()
public int getRelativeHorizontalPosition()
Specifies relative to what the shape is positioned horizontally.
Remarks:
The default value is RelativeHorizontalPosition.COLUMN.
Has effect only for top level floating shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Returns: int - The corresponding int value. The returned value is one of RelativeHorizontalPosition constants.
getRelativeHorizontalSize()
public int getRelativeHorizontalSize()
Gets the value of shape’s relative size in horizontal direction.
Remarks:
The default value is RelativeHorizontalSize.
Has effect only if getWidthRelative() / setWidthRelative(float) is set.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Returns: int - The value of shape’s relative size in horizontal direction. The returned value is one of RelativeHorizontalSize constants.
getRelativeVerticalPosition()
public int getRelativeVerticalPosition()
Specifies relative to what the shape is positioned vertically.
Remarks:
The default value is RelativeVerticalPosition.PARAGRAPH.
Has effect only for top level floating shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Returns: int - The corresponding int value. The returned value is one of RelativeVerticalPosition constants.
getRelativeVerticalSize()
public int getRelativeVerticalSize()
Gets the value of shape’s relative size in vertical direction.
Remarks:
The default value is RelativeVerticalSize.MARGIN.
Has effect only if getHeightRelative() / setHeightRelative(float) is set.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Returns: int - The value of shape’s relative size in vertical direction. The returned value is one of RelativeVerticalSize constants.
getRight()
public double getRight()
Gets the position of the right edge of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points and relative to the shape anchor.
For shapes in a group, the value is in the coordinate space and units of the parent group.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Returns: double - The position of the right edge of the containing block of the shape.
getRotateWithObject()
public boolean getRotateWithObject()
Returns: boolean
getRotation()
public double getRotation()
Defines the angle (in degrees) that a shape is rotated. Positive value corresponds to clockwise rotation angle.
Remarks:
The default value is 0.
Examples:
Shows how to insert and rotate an image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a shape with an image.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
Assert.assertTrue(shape.canHaveImage());
Assert.assertTrue(shape.hasImage());
// Rotate the image 45 degrees clockwise.
shape.setRotation(45.0);
doc.save(getArtifactsDir() + "Shape.Rotate.docx");
Returns: double - The corresponding double value.
getScreenTip()
public String getScreenTip()
Defines the text displayed when the mouse pointer moves over the shape.
Remarks:
The default value is an empty string.
Examples:
Shows how to insert a shape which contains an image, and is also a hyperlink.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setHRef("https://forum.aspose.com/");
shape.setTarget("New Window");
shape.setScreenTip("Aspose.Words Support Forums");
// Ctrl + left-clicking the shape in Microsoft Word will open a new web browser window
// and take us to the hyperlink in the "HRef" property.
doc.save(getArtifactsDir() + "Image.InsertImageWithHyperlink.docx");
Returns: java.lang.String - The corresponding java.lang.String value.
getShadowColors()
public Color getShadowColors()
Returns: java.awt.Color
getShadowFormat()
public ShadowFormat getShadowFormat()
Gets shadow formatting for the shape.
Examples:
Shows how to get shadow color.
Document doc = new Document(getMyDir() + "Shadow color.docx");
Shape shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
ShadowFormat shadowFormat = shape.getShadowFormat();
Assert.assertEquals(Color.RED.getRGB(), shadowFormat.getColor().getRGB());
Assert.assertEquals(ShadowType.SHADOW_MIXED, shadowFormat.getType());
Returns: ShadowFormat - Shadow formatting for the shape.
getShadowType()
public int getShadowType()
Returns: int
getShapeRenderer()
public ShapeRenderer getShapeRenderer()
Creates and returns an object that can be used to render this shape into an image.
Remarks:
This method just invokes the ShapeRenderer constructor and passes this object as a parameter.
Examples:
Shows how to use a shape renderer to export shapes to files in the local file system.
Document doc = new Document(getMyDir() + "Various shapes.docx");
NodeCollection shapes = doc.getChildNodes(NodeType.SHAPE, true);
Assert.assertEquals(7, shapes.getCount());
// There are 7 shapes in the document, including one group shape with 2 child shapes.
// We will render every shape to an image file in the local file system
// while ignoring the group shapes since they have no appearance.
// This will produce 6 image files.
for (Shape shape : (Iterable) doc.getChildNodes(NodeType.SHAPE, true)) {
ShapeRenderer renderer = shape.getShapeRenderer();
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.PNG);
renderer.save(getArtifactsDir() + MessageFormat.format("Shape.RenderAllShapes.{0}.png", shape.getName()), options);
}
Returns: ShapeRenderer - The renderer object for this shape.
getShapeType()
public int getShapeType()
Gets the shape type.
Examples:
Shows how to create a group of shapes, and print its contents using a document visitor.
public void groupOfShapes() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// If you need to create "NonPrimitive" shapes, such as SingleCornerSnipped, TopCornersSnipped, DiagonalCornersSnipped,
// TopCornersOneRoundedOneSnipped, SingleCornerRounded, TopCornersRounded, DiagonalCornersRounded
// please use DocumentBuilder.InsertShape methods.
Shape balloon = new Shape(doc, ShapeType.BALLOON);
balloon.setWidth(200.0);
balloon.setHeight(200.0);
balloon.setStrokeColor(Color.RED);
Shape cube = new Shape(doc, ShapeType.CUBE);
cube.setWidth(100.0);
cube.setHeight(100.0);
cube.setStrokeColor(Color.BLUE);
GroupShape group = new GroupShape(doc);
group.appendChild(balloon);
group.appendChild(cube);
Assert.assertTrue(group.isGroup());
builder.insertNode(group);
ShapeInfoPrinter printer = new ShapeInfoPrinter();
group.accept(printer);
System.out.println(printer.getText());
}
///
/// Prints the contents of a visited shape group to the console.
///
public static class ShapeInfoPrinter extends DocumentVisitor {
public ShapeInfoPrinter() {
mBuilder = new StringBuilder();
}
public String getText() {
return mBuilder.toString();
}
public int visitGroupShapeStart(final GroupShape groupShape) {
mBuilder.append("Shape group started:\r\n");
return VisitorAction.CONTINUE;
}
public int visitGroupShapeEnd(final GroupShape groupShape) {
mBuilder.append("End of shape group\r\n");
return VisitorAction.CONTINUE;
}
public int visitShapeStart(final Shape shape) {
mBuilder.append("\tShape - " + shape.getShapeType() + ":\r\n");
mBuilder.append("\t\tWidth: " + shape.getWidth() + "\r\n");
mBuilder.append("\t\tHeight: " + shape.getHeight() + "\r\n");
mBuilder.append("\t\tStroke color: " + shape.getStroke().getColor() + "\r\n");
mBuilder.append("\t\tFill color: " + shape.getFill().getForeColor() + "\r\n");
return VisitorAction.CONTINUE;
}
public int visitShapeEnd(final Shape shape) {
mBuilder.append("\tEnd of shape\r\n");
return VisitorAction.CONTINUE;
}
private final StringBuilder mBuilder;
}
Returns: int - The shape type. The returned value is one of ShapeType constants.
getSizeInPoints()
public Point2D.Float getSizeInPoints()
Gets the size of the shape in points. Gets the size of the shape in points.
Remarks:
Point2D.Float is used as return type because we need in float dimension values here. One should to assume that Point2D’s x == width and y == height.
Examples:
Shows how to verify a shape’s size and markup language.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Transparent background logo.png");
Assert.assertEquals(ShapeMarkupLanguage.DML, shape.getMarkupLanguage());
Assert.assertEquals(new Point2D.Float(300f, 300f), shape.getSizeInPoints());
Returns: java.awt.geom.Point2D.Float - The size of the shape in points.
getSoftEdge()
public SoftEdgeFormat getSoftEdge()
Gets soft edge formatting for the shape.
Examples:
Shows how to set limit for image resolution.
Document doc = new Document(getMyDir() + "Rendering.docx");
SvgSaveOptions saveOptions = new SvgSaveOptions();
saveOptions.setMaxImageResolution(72);
doc.save(getArtifactsDir() + "SvgSaveOptions.MaxImageResolution.svg", saveOptions);
Shows how to work with soft edge formatting.
DocumentBuilder builder = new DocumentBuilder();
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 200.0, 200.0);
// Apply soft edge to the shape.
shape.getSoftEdge().setRadius(30.0);
builder.getDocument().save(getArtifactsDir() + "Shape.SoftEdge.docx");
// Load document with rectangle shape with soft edge.
Document doc = new Document(getArtifactsDir() + "Shape.SoftEdge.docx");
shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
// Check soft edge radius.
Assert.assertEquals(30, shape.getSoftEdge().getRadius());
// Remove soft edge from the shape.
shape.getSoftEdge().remove();
// Check radius of the removed soft edge.
Assert.assertEquals(0, shape.getSoftEdge().getRadius());
Returns: SoftEdgeFormat - Soft edge formatting for the shape.
getTarget()
public String getTarget()
Gets the target frame for the shape hyperlink.
Remarks:
The default value is an empty string.
Examples:
Shows how to insert a shape which contains an image, and is also a hyperlink.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setHRef("https://forum.aspose.com/");
shape.setTarget("New Window");
shape.setScreenTip("Aspose.Words Support Forums");
// Ctrl + left-clicking the shape in Microsoft Word will open a new web browser window
// and take us to the hyperlink in the "HRef" property.
doc.save(getArtifactsDir() + "Image.InsertImageWithHyperlink.docx");
Returns: java.lang.String - The target frame for the shape hyperlink.
getText()
public String getText()
Gets the text of this node and of all its children.
Remarks:
The returned string includes all control and special characters as described in ControlChar.
Examples:
Shows the difference between calling the GetText and ToString methods on a node.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField("MERGEFIELD Field");
// GetText will retrieve the visible text as well as field codes and special characters.
Assert.assertEquals("MERGEFIELD FieldField\f", doc.getText());
// ToString will give us the document's appearance if saved to a passed save format.
Assert.assertEquals("Field\r\n", doc.toString(SaveFormat.TEXT));
Shows how to output all paragraphs in a document that are list items.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.getListFormat().applyNumberDefault();
builder.writeln("Numbered list item 1");
builder.writeln("Numbered list item 2");
builder.writeln("Numbered list item 3");
builder.getListFormat().removeNumbers();
builder.getListFormat().applyBulletDefault();
builder.writeln("Bulleted list item 1");
builder.writeln("Bulleted list item 2");
builder.writeln("Bulleted list item 3");
builder.getListFormat().removeNumbers();
NodeCollection paras = doc.getChildNodes(NodeType.PARAGRAPH, true);
for (Paragraph para : (Iterable) paras) {
if (para.getListFormat().isListItem()) {
System.out.println(java.text.MessageFormat.format("*** A paragraph belongs to list {0}", para.getListFormat().getList().getListId()));
System.out.println(para.getText());
}
}
Returns: java.lang.String
getTextureAlignment()
public int getTextureAlignment()
Returns: int
getTitle()
public String getTitle()
Gets the title (caption) of the current shape object.
Remarks:
Default is empty string.
Cannot be null , but can be an empty string.
Examples:
Shows how to set the title of a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create a shape, give it a title, and then add it to the document.
Shape shape = new Shape(doc, ShapeType.CUBE);
shape.setWidth(200.0);
shape.setHeight(200.0);
shape.setTitle("My cube");
builder.insertNode(shape);
// When we save a document with a shape that has a title,
// Aspose.Words will store that title in the shape's Alt Text.
doc.save(getArtifactsDir() + "Shape.Title.docx");
doc = new Document(getArtifactsDir() + "Shape.Title.docx");
shape = (Shape) doc.getChild(NodeType.SHAPE, 0, true);
Assert.assertEquals("", shape.getTitle());
Assert.assertEquals("Title: My cube", shape.getAlternativeText());
Returns: java.lang.String - The title (caption) of the current shape object.
getTop()
public double getTop()
Gets the position of the top edge of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points and relative to the shape anchor.
For shapes in a group, the value is in the coordinate space and units of the parent group.
The default value is 0.
Has effect only for floating shapes.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Returns: double - The position of the top edge of the containing block of the shape.
getTopRelative()
public float getTopRelative()
Gets the value that represents shape’s relative top position in percent.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Returns: float - The value that represents shape’s relative top position in percent.
getTransparency()
public double getTransparency()
Returns: double
getVerticalAlignment()
public int getVerticalAlignment()
Specifies how the shape is positioned vertically.
Remarks:
The default value is VerticalAlignment.NONE.
Has effect only for top level floating shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Returns: int - The corresponding int value. The returned value is one of VerticalAlignment constants.
getVisible()
public boolean getVisible()
Returns: boolean
getWidth()
public double getWidth()
Gets the width of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points.
For shapes in a group, the value is in the coordinate space and units of the parent group.
The default value is 0.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Shows how to resize a shape with an image.
// When we insert an image using the "InsertImage" method, the builder scales the shape that displays the image so that,
// when we view the document using 100% zoom in Microsoft Word, the shape displays the image in its actual size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
// A 400x400 image will create an ImageData object with an image size of 300x300pt.
ImageSize imageSize = shape.getImageData().getImageSize();
Assert.assertEquals(300.0d, imageSize.getWidthPoints());
Assert.assertEquals(300.0d, imageSize.getHeightPoints());
// If a shape's dimensions match the image data's dimensions,
// then the shape is displaying the image in its original size.
Assert.assertEquals(300.0d, shape.getWidth());
Assert.assertEquals(300.0d, shape.getHeight());
// Reduce the overall size of the shape by 50%.
shape.setWidth(shape.getWidth() * 0.5);
// Scaling factors apply to both the width and the height at the same time to preserve the shape's proportions.
Assert.assertEquals(150.0d, shape.getWidth());
Assert.assertEquals(150.0d, shape.getHeight());
// When we resize the shape, the size of the image data remains the same.
Assert.assertEquals(300.0d, imageSize.getWidthPoints());
Assert.assertEquals(300.0d, imageSize.getHeightPoints());
// We can reference the image data dimensions to apply a scaling based on the size of the image.
shape.setWidth(imageSize.getWidthPoints() * 1.1);
Assert.assertEquals(330.0d, shape.getWidth());
Assert.assertEquals(330.0d, shape.getHeight());
doc.save(getArtifactsDir() + "Image.ScaleImage.docx");
Returns: double - The width of the containing block of the shape.
getWidthRelative()
public float getWidthRelative()
Gets the value that represents the percentage of shape’s relative width.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Returns: float - The value that represents the percentage of shape’s relative width.
getWrapSide()
public int getWrapSide()
Specifies how the text is wrapped around the shape.
Remarks:
The default value is WrapSide.BOTH.
Has effect only for top level shapes.
Examples:
Shows how to replace all textbox shapes with image shapes.
Document doc = new Document(getMyDir() + "Textboxes in drawing canvas.docx");
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(3, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.TEXT_BOX));
Assert.assertEquals(1, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.IMAGE));
for (Shape shape : shapeList) {
if (((shape.getShapeType()) == (ShapeType.TEXT_BOX))) {
Shape replacementShape = new Shape(doc, ShapeType.IMAGE);
replacementShape.getImageData().setImage(getImageDir() + "Logo.jpg");
replacementShape.setLeft(shape.getLeft());
replacementShape.setTop(shape.getTop());
replacementShape.setWidth(shape.getWidth());
replacementShape.setHeight(shape.getHeight());
replacementShape.setRelativeHorizontalPosition(shape.getRelativeHorizontalPosition());
replacementShape.setRelativeVerticalPosition(shape.getRelativeVerticalPosition());
replacementShape.setHorizontalAlignment(shape.getHorizontalAlignment());
replacementShape.setVerticalAlignment(shape.getVerticalAlignment());
replacementShape.setWrapType(shape.getWrapType());
replacementShape.setWrapSide(shape.getWrapSide());
shape.getParentNode().insertAfter(replacementShape, shape);
shape.remove();
}
}
shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(0, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.TEXT_BOX));
Assert.assertEquals(4, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.IMAGE));
doc.save(getArtifactsDir() + "Shape.ReplaceTextboxesWithImages.docx");
Returns: int - The corresponding int value. The returned value is one of WrapSide constants.
getWrapType()
public int getWrapType()
Defines whether the shape is inline or floating. For floating shapes defines the wrapping mode for text around the shape.
Remarks:
The default value is WrapType.NONE.
Has effect only for top level shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Shows how to create and format a text box.
Document doc = new Document();
// Create a floating text box.
Shape textBox = new Shape(doc, ShapeType.TEXT_BOX);
textBox.setWrapType(WrapType.NONE);
textBox.setHeight(50.0);
textBox.setWidth(200.0);
// Set the horizontal, and vertical alignment of the text inside the shape.
textBox.setHorizontalAlignment(HorizontalAlignment.CENTER);
textBox.setVerticalAlignment(VerticalAlignment.TOP);
// Add a paragraph to the text box and add a run of text that the text box will display.
textBox.appendChild(new Paragraph(doc));
Paragraph para = textBox.getFirstParagraph();
para.getParagraphFormat().setAlignment(ParagraphAlignment.CENTER);
Run run = new Run(doc);
run.setText("Hello world!");
para.appendChild(run);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(textBox);
doc.save(getArtifactsDir() + "Shape.CreateTextBox.docx");
Returns: int - The corresponding int value. The returned value is one of WrapType constants.
getZOrder()
public int getZOrder()
Determines the display order of overlapping shapes.
Remarks:
Has effect only for top level shapes.
The default value is 0.
The number represents the stacking precedence. A shape with a higher number will be displayed as if it were overlapping (in “front” of) a shape with a lower number.
The order of overlapping shapes is independent for shapes in the header and in the main text of the document.
The display order of child shapes in a group shape is determined by their order inside the group shape.
Examples:
Shows how to manipulate the order of shapes.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert three different colored rectangles that partially overlap each other.
// When we insert a shape that overlaps another shape, Aspose.Words places the newer shape on top of the old one.
// The light green rectangle will overlap the light blue rectangle and partially obscure it,
// and the light blue rectangle will obscure the orange rectangle.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 100.0,
RelativeVerticalPosition.TOP_MARGIN, 100.0, 200.0, 200.0, WrapType.NONE);
shape.setFillColor(Color.ORANGE);
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 150.0,
RelativeVerticalPosition.TOP_MARGIN, 150.0, 200.0, 200.0, WrapType.NONE);
shape.setFillColor(Color.BLUE);
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 200.0,
RelativeVerticalPosition.TOP_MARGIN, 200.0, 200.0, 200.0, WrapType.NONE);
shape.setFillColor(Color.GREEN);
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
// The "ZOrder" property of a shape determines its stacking priority among other overlapping shapes.
// If two overlapping shapes have different "ZOrder" values,
// Microsoft Word will place the shape with a higher value over the shape with the lower value.
// Set the "ZOrder" values of our shapes to place the first orange rectangle over the second light blue one
// and the second light blue rectangle over the third light green rectangle.
// This will reverse their original stacking order.
shapeList.get(0).setZOrder(3);
shapeList.get(1).setZOrder(2);
shapeList.get(2).setZOrder(1);
doc.save(getArtifactsDir() + "Shape.ZOrder.docx");
Returns: int - The corresponding int value.
getZOrder_IShape()
public int getZOrder_IShape()
Returns: int
hasChildNodes()
public boolean hasChildNodes()
Returns true if this node has any child nodes.
Examples:
Shows how to combine the rows from two tables into one.
Document doc = new Document(getMyDir() + "Tables.docx");
// Below are two ways of getting a table from a document.
// 1 - From the "Tables" collection of a Body node:
Table firstTable = doc.getFirstSection().getBody().getTables().get(0);
// 2 - Using the "GetChild" method:
Table secondTable = (Table) doc.getChild(NodeType.TABLE, 1, true);
// Append all rows from the current table to the next.
while (secondTable.hasChildNodes())
firstTable.getRows().add(secondTable.getFirstRow());
// Remove the empty table container.
secondTable.remove();
doc.save(getArtifactsDir() + "Table.CombineTables.docx");
Returns: boolean - true if this node has any child nodes.
indexOf(Node child)
public int indexOf(Node child)
Returns the index of the specified child node in the child node array.
Remarks:
Returns -1 if the node is not found in the child nodes.
Examples:
Shows how to get the index of a given child node from its parent.
Document doc = new Document(getMyDir() + "Rendering.docx");
Body body = doc.getFirstSection().getBody();
// Retrieve the index of the last paragraph in the body of the first section.
Assert.assertEquals(24, body.getChildNodes(NodeType.ANY, false).indexOf(body.getLastParagraph()));
Parameters:
| Parameter | Type | Description |
|---|---|---|
| child | Node |
Returns: int
insertAfter(Node newChild, Node refChild)
public Node insertAfter(Node newChild, Node refChild)
Inserts the specified node immediately after the specified reference node.
Remarks:
If refChild is null , inserts newChild at the beginning of the list of child nodes.
If the newChild is already in the tree, it is first removed.
If the node being inserted was created from another document, you should use M:Aspose.Words.DocumentBase.ImportNode(Aspose.Words.Node,System.Boolean,Aspose.Words.ImportFormatMode) to import the node to the current document. The imported node can then be inserted into the current document.
Examples:
Shows how to replace all textbox shapes with image shapes.
Document doc = new Document(getMyDir() + "Textboxes in drawing canvas.docx");
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(3, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.TEXT_BOX));
Assert.assertEquals(1, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.IMAGE));
for (Shape shape : shapeList) {
if (((shape.getShapeType()) == (ShapeType.TEXT_BOX))) {
Shape replacementShape = new Shape(doc, ShapeType.IMAGE);
replacementShape.getImageData().setImage(getImageDir() + "Logo.jpg");
replacementShape.setLeft(shape.getLeft());
replacementShape.setTop(shape.getTop());
replacementShape.setWidth(shape.getWidth());
replacementShape.setHeight(shape.getHeight());
replacementShape.setRelativeHorizontalPosition(shape.getRelativeHorizontalPosition());
replacementShape.setRelativeVerticalPosition(shape.getRelativeVerticalPosition());
replacementShape.setHorizontalAlignment(shape.getHorizontalAlignment());
replacementShape.setVerticalAlignment(shape.getVerticalAlignment());
replacementShape.setWrapType(shape.getWrapType());
replacementShape.setWrapSide(shape.getWrapSide());
shape.getParentNode().insertAfter(replacementShape, shape);
shape.remove();
}
}
shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(0, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.TEXT_BOX));
Assert.assertEquals(4, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.IMAGE));
doc.save(getArtifactsDir() + "Shape.ReplaceTextboxesWithImages.docx");
Shows how to add, update and delete child nodes in a CompositeNode’s collection of children.
Document doc = new Document();
// An empty document, by default, has one paragraph.
Assert.assertEquals(1, doc.getFirstSection().getBody().getParagraphs().getCount());
// Composite nodes such as our paragraph can contain other composite and inline nodes as children.
Paragraph paragraph = doc.getFirstSection().getBody().getFirstParagraph();
Run paragraphText = new Run(doc, "Initial text. ");
paragraph.appendChild(paragraphText);
// Create three more run nodes.
Run run1 = new Run(doc, "Run 1. ");
Run run2 = new Run(doc, "Run 2. ");
Run run3 = new Run(doc, "Run 3. ");
// The document body will not display these runs until we insert them into a composite node
// that itself is a part of the document's node tree, as we did with the first run.
// We can determine where the text contents of nodes that we insert
// appears in the document by specifying an insertion location relative to another node in the paragraph.
Assert.assertEquals("Initial text.", paragraph.getText().trim());
// Insert the second run into the paragraph in front of the initial run.
paragraph.insertBefore(run2, paragraphText);
Assert.assertEquals("Run 2. Initial text.", paragraph.getText().trim());
// Insert the third run after the initial run.
paragraph.insertAfter(run3, paragraphText);
Assert.assertEquals("Run 2. Initial text. Run 3.", paragraph.getText().trim());
// Insert the first run to the start of the paragraph's child nodes collection.
paragraph.prependChild(run1);
Assert.assertEquals("Run 1. Run 2. Initial text. Run 3.", paragraph.getText().trim());
Assert.assertEquals(4, paragraph.getChildNodes(NodeType.ANY, true).getCount());
// We can modify the contents of the run by editing and deleting existing child nodes.
((Run) paragraph.getChildNodes(NodeType.RUN, true).get(1)).setText("Updated run 2. ");
paragraph.getChildNodes(NodeType.RUN, true).remove(paragraphText);
Assert.assertEquals("Run 1. Updated run 2. Run 3.", paragraph.getText().trim());
Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, true).getCount());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| newChild | Node | The Node to insert. |
| refChild | Node | The Node that is the reference node. The newChild is placed after the refChild . |
Returns: Node - The inserted node.
insertBefore(Node newChild, Node refChild)
public Node insertBefore(Node newChild, Node refChild)
Inserts the specified node immediately before the specified reference node.
Remarks:
If refChild is null , inserts newChild at the end of the list of child nodes.
If the newChild is already in the tree, it is first removed.
If the node being inserted was created from another document, you should use M:Aspose.Words.DocumentBase.ImportNode(Aspose.Words.Node,System.Boolean,Aspose.Words.ImportFormatMode) to import the node to the current document. The imported node can then be inserted into the current document.
Examples:
Shows how to add, update and delete child nodes in a CompositeNode’s collection of children.
Document doc = new Document();
// An empty document, by default, has one paragraph.
Assert.assertEquals(1, doc.getFirstSection().getBody().getParagraphs().getCount());
// Composite nodes such as our paragraph can contain other composite and inline nodes as children.
Paragraph paragraph = doc.getFirstSection().getBody().getFirstParagraph();
Run paragraphText = new Run(doc, "Initial text. ");
paragraph.appendChild(paragraphText);
// Create three more run nodes.
Run run1 = new Run(doc, "Run 1. ");
Run run2 = new Run(doc, "Run 2. ");
Run run3 = new Run(doc, "Run 3. ");
// The document body will not display these runs until we insert them into a composite node
// that itself is a part of the document's node tree, as we did with the first run.
// We can determine where the text contents of nodes that we insert
// appears in the document by specifying an insertion location relative to another node in the paragraph.
Assert.assertEquals("Initial text.", paragraph.getText().trim());
// Insert the second run into the paragraph in front of the initial run.
paragraph.insertBefore(run2, paragraphText);
Assert.assertEquals("Run 2. Initial text.", paragraph.getText().trim());
// Insert the third run after the initial run.
paragraph.insertAfter(run3, paragraphText);
Assert.assertEquals("Run 2. Initial text. Run 3.", paragraph.getText().trim());
// Insert the first run to the start of the paragraph's child nodes collection.
paragraph.prependChild(run1);
Assert.assertEquals("Run 1. Run 2. Initial text. Run 3.", paragraph.getText().trim());
Assert.assertEquals(4, paragraph.getChildNodes(NodeType.ANY, true).getCount());
// We can modify the contents of the run by editing and deleting existing child nodes.
((Run) paragraph.getChildNodes(NodeType.RUN, true).get(1)).setText("Updated run 2. ");
paragraph.getChildNodes(NodeType.RUN, true).remove(paragraphText);
Assert.assertEquals("Run 1. Updated run 2. Run 3.", paragraph.getText().trim());
Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, true).getCount());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| newChild | Node | The Node to insert. |
| refChild | Node | The Node that is the reference node. The newChild is placed before this node. |
Returns: Node - The inserted node.
isComposite()
public boolean isComposite()
Returns true as this node can have child nodes.
Examples:
Shows how to traverse a composite node’s tree of child nodes.
public void recurseChildren() throws Exception {
Document doc = new Document(getMyDir() + "Paragraphs.docx");
// Any node that can contain child nodes, such as the document itself, is composite.
Assert.assertTrue(doc.isComposite());
// Invoke the recursive function that will go through and print all the child nodes of a composite node.
traverseAllNodes(doc, 0);
}
///
/// Recursively traverses a node tree while printing the type of each node
/// with an indent depending on depth as well as the contents of all inline nodes.
///
public void traverseAllNodes(CompositeNode parentNode, int depth) {
for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
System.out.println(MessageFormat.format("{0}{1}", String.format(" ", depth), Node.nodeTypeToString(childNode.getNodeType())));
// Recurse into the node if it is a composite node. Otherwise, print its contents if it is an inline node.
if (childNode.isComposite()) {
System.out.println();
traverseAllNodes((CompositeNode) childNode, depth + 1);
} else if (childNode instanceof Inline) {
System.out.println(MessageFormat.format(" - \"{0}\"", childNode.getText().trim()));
} else {
System.out.println();
}
}
}
Returns: boolean - true as this node can have child nodes.
isDecorative()
public boolean isDecorative()
Gets the flag that specifies whether the shape is decorative in the document.
Remarks:
Note that shape having not empty getAlternativeText() / setAlternativeText(java.lang.String) cannot be decorative.
Examples:
Shows how to set that the shape is decorative.
Document doc = new Document(getMyDir() + "Decorative shapes.docx");
Shape shape = (Shape) doc.getChildNodes(NodeType.SHAPE, true).get(0);
Assert.assertTrue(shape.isDecorative());
// If "AlternativeText" is not empty, the shape cannot be decorative.
// That's why our value has changed to 'false'.
shape.setAlternativeText("Alternative text.");
Assert.assertFalse(shape.isDecorative());
DocumentBuilder builder = new DocumentBuilder(doc);
builder.moveToDocumentEnd();
// Create a new shape as decorative.
shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 100.0);
shape.isDecorative(true);
doc.save(getArtifactsDir() + "Shape.IsDecorative.docx");
Returns: boolean - The flag that specifies whether the shape is decorative in the document.
isDecorative(boolean value)
public void isDecorative(boolean value)
Sets the flag that specifies whether the shape is decorative in the document.
Remarks:
Note that shape having not empty getAlternativeText() / setAlternativeText(java.lang.String) cannot be decorative.
Examples:
Shows how to set that the shape is decorative.
Document doc = new Document(getMyDir() + "Decorative shapes.docx");
Shape shape = (Shape) doc.getChildNodes(NodeType.SHAPE, true).get(0);
Assert.assertTrue(shape.isDecorative());
// If "AlternativeText" is not empty, the shape cannot be decorative.
// That's why our value has changed to 'false'.
shape.setAlternativeText("Alternative text.");
Assert.assertFalse(shape.isDecorative());
DocumentBuilder builder = new DocumentBuilder(doc);
builder.moveToDocumentEnd();
// Create a new shape as decorative.
shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 100.0);
shape.isDecorative(true);
doc.save(getArtifactsDir() + "Shape.IsDecorative.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The flag that specifies whether the shape is decorative in the document. |
isDeleteRevision()
public boolean isDeleteRevision()
Returns true if this object was deleted in Microsoft Word while change tracking was enabled.
Examples:
Shows how to work with revision shapes.
Document doc = new Document();
Assert.assertFalse(doc.getTrackRevisions());
// Insert an inline shape without tracking revisions, which will make this shape not a revision of any kind.
Shape shape = new Shape(doc, ShapeType.CUBE);
shape.setWrapType(WrapType.INLINE);
shape.setWidth(100.0);
shape.setHeight(100.0);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(shape);
// Start tracking revisions and then insert another shape, which will be a revision.
doc.startTrackRevisions("John Doe");
shape = new Shape(doc, ShapeType.SUN);
shape.setWrapType(WrapType.INLINE);
shape.setWidth(100.0);
shape.setHeight(100.0);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(shape);
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(shapeList.size(), 2);
Shape firstShape = shapeList.get(0);
firstShape.remove();
// Since we removed that shape while we were tracking changes,
// the shape persists in the document and counts as a delete revision.
// Accepting this revision will remove the shape permanently, and rejecting it will keep it in the document.
Assert.assertEquals(ShapeType.CUBE, shapeList.get(0).getShapeType());
Assert.assertTrue(shapeList.get(0).isDeleteRevision());
// And we inserted another shape while tracking changes, so that shape will count as an insert revision.
// Accepting this revision will assimilate this shape into the document as a non-revision,
// and rejecting the revision will remove this shape permanently.
Assert.assertEquals(ShapeType.SUN, shapeList.get(1).getShapeType());
Assert.assertTrue(shapeList.get(1).isInsertRevision());
Returns: boolean - True if this object was deleted in Microsoft Word while change tracking was enabled.
isGroup()
public boolean isGroup()
Returns true if this is a group shape.
Examples:
Shows how to create a group of shapes, and print its contents using a document visitor.
public void groupOfShapes() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// If you need to create "NonPrimitive" shapes, such as SingleCornerSnipped, TopCornersSnipped, DiagonalCornersSnipped,
// TopCornersOneRoundedOneSnipped, SingleCornerRounded, TopCornersRounded, DiagonalCornersRounded
// please use DocumentBuilder.InsertShape methods.
Shape balloon = new Shape(doc, ShapeType.BALLOON);
balloon.setWidth(200.0);
balloon.setHeight(200.0);
balloon.setStrokeColor(Color.RED);
Shape cube = new Shape(doc, ShapeType.CUBE);
cube.setWidth(100.0);
cube.setHeight(100.0);
cube.setStrokeColor(Color.BLUE);
GroupShape group = new GroupShape(doc);
group.appendChild(balloon);
group.appendChild(cube);
Assert.assertTrue(group.isGroup());
builder.insertNode(group);
ShapeInfoPrinter printer = new ShapeInfoPrinter();
group.accept(printer);
System.out.println(printer.getText());
}
///
/// Prints the contents of a visited shape group to the console.
///
public static class ShapeInfoPrinter extends DocumentVisitor {
public ShapeInfoPrinter() {
mBuilder = new StringBuilder();
}
public String getText() {
return mBuilder.toString();
}
public int visitGroupShapeStart(final GroupShape groupShape) {
mBuilder.append("Shape group started:\r\n");
return VisitorAction.CONTINUE;
}
public int visitGroupShapeEnd(final GroupShape groupShape) {
mBuilder.append("End of shape group\r\n");
return VisitorAction.CONTINUE;
}
public int visitShapeStart(final Shape shape) {
mBuilder.append("\tShape - " + shape.getShapeType() + ":\r\n");
mBuilder.append("\t\tWidth: " + shape.getWidth() + "\r\n");
mBuilder.append("\t\tHeight: " + shape.getHeight() + "\r\n");
mBuilder.append("\t\tStroke color: " + shape.getStroke().getColor() + "\r\n");
mBuilder.append("\t\tFill color: " + shape.getFill().getForeColor() + "\r\n");
return VisitorAction.CONTINUE;
}
public int visitShapeEnd(final Shape shape) {
mBuilder.append("\tEnd of shape\r\n");
return VisitorAction.CONTINUE;
}
private final StringBuilder mBuilder;
}
Returns: boolean - true if this is a group shape.
isHorizontalRule()
public boolean isHorizontalRule()
Returns true if this shape is a horizontal rule.
Examples:
Shows how to insert a horizontal rule shape, and customize its formatting.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertHorizontalRule();
HorizontalRuleFormat horizontalRuleFormat = shape.getHorizontalRuleFormat();
horizontalRuleFormat.setAlignment(HorizontalRuleAlignment.CENTER);
horizontalRuleFormat.setWidthPercent(70.0);
horizontalRuleFormat.setHeight(3.0);
horizontalRuleFormat.setColor(Color.BLUE);
horizontalRuleFormat.setNoShade(true);
Assert.assertTrue(shape.isHorizontalRule());
Assert.assertTrue(shape.getHorizontalRuleFormat().getNoShade());
Returns: boolean - true if this shape is a horizontal rule.
isImage()
public boolean isImage()
Returns true if this shape is an image shape.
Examples:
Shows how to open an HTML document with images from a stream using a base URI.
InputStream stream = new FileInputStream(getMyDir() + "Document.html");
try {
// Pass the URI of the base folder while loading it
// so that any images with relative URIs in the HTML document can be found.
LoadOptions loadOptions = new LoadOptions();
loadOptions.setBaseUri(getImageDir());
Document doc = new Document(stream, loadOptions);
// Verify that the first shape of the document contains a valid image.
Shape shape = (Shape) doc.getChild(NodeType.SHAPE, 0, true);
Assert.assertTrue(shape.isImage());
Assert.assertNotNull(shape.getImageData().getImageBytes());
Assert.assertEquals(32.0, ConvertUtil.pointToPixel(shape.getWidth()), 0.01);
Assert.assertEquals(32.0, ConvertUtil.pointToPixel(shape.getHeight()), 0.01);
} finally {
if (stream != null) stream.close();
}
Returns: boolean - true if this shape is an image shape.
isInline()
public boolean isInline()
A quick way to determine if this shape is positioned inline with text.
Remarks:
Has effect only for top level shapes.
Examples:
Shows how to determine whether a shape is inline or floating.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Below are two wrapping types that shapes may have.
// 1 - Inline:
builder.write("Hello world! ");
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 100.0);
shape.setFillColor(Color.BLUE);
builder.write(" Hello again.");
// An inline shape sits inside a paragraph among other paragraph elements, such as runs of text.
// In Microsoft Word, we may click and drag the shape to any paragraph as if it is a character.
// If the shape is large, it will affect vertical paragraph spacing.
// We cannot move this shape to a place with no paragraph.
Assert.assertEquals(WrapType.INLINE, shape.getWrapType());
Assert.assertTrue(shape.isInline());
// 2 - Floating:
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 200.0,
RelativeVerticalPosition.TOP_MARGIN, 200.0, 100.0, 100.0, WrapType.NONE);
shape.setFillColor(Color.ORANGE);
// A floating shape belongs to the paragraph that we insert it into,
// which we can determine by an anchor symbol that appears when we click the shape.
// If the shape does not have a visible anchor symbol to its left,
// we will need to enable visible anchors via "Options" -> "Display" -> "Object Anchors".
// In Microsoft Word, we may left click and drag this shape freely to any location.
Assert.assertEquals(WrapType.NONE, shape.getWrapType());
Assert.assertFalse(shape.isInline());
doc.save(getArtifactsDir() + "Shape.IsInline.docx");
Returns: boolean - The corresponding boolean value.
isInsertRevision()
public boolean isInsertRevision()
Returns true if this object was inserted in Microsoft Word while change tracking was enabled.
Examples:
Shows how to work with revision shapes.
Document doc = new Document();
Assert.assertFalse(doc.getTrackRevisions());
// Insert an inline shape without tracking revisions, which will make this shape not a revision of any kind.
Shape shape = new Shape(doc, ShapeType.CUBE);
shape.setWrapType(WrapType.INLINE);
shape.setWidth(100.0);
shape.setHeight(100.0);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(shape);
// Start tracking revisions and then insert another shape, which will be a revision.
doc.startTrackRevisions("John Doe");
shape = new Shape(doc, ShapeType.SUN);
shape.setWrapType(WrapType.INLINE);
shape.setWidth(100.0);
shape.setHeight(100.0);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(shape);
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(shapeList.size(), 2);
Shape firstShape = shapeList.get(0);
firstShape.remove();
// Since we removed that shape while we were tracking changes,
// the shape persists in the document and counts as a delete revision.
// Accepting this revision will remove the shape permanently, and rejecting it will keep it in the document.
Assert.assertEquals(ShapeType.CUBE, shapeList.get(0).getShapeType());
Assert.assertTrue(shapeList.get(0).isDeleteRevision());
// And we inserted another shape while tracking changes, so that shape will count as an insert revision.
// Accepting this revision will assimilate this shape into the document as a non-revision,
// and rejecting the revision will remove this shape permanently.
Assert.assertEquals(ShapeType.SUN, shapeList.get(1).getShapeType());
Assert.assertTrue(shapeList.get(1).isInsertRevision());
Returns: boolean - True if this object was inserted in Microsoft Word while change tracking was enabled.
isLayoutInCell()
public boolean isLayoutInCell()
Gets a flag indicating whether the shape is displayed inside a table or outside of it.
Remarks:
The default value is true .
Has effect only for top level shapes, the property getWrapType() / setWrapType(int) of which is set to value other than Inline.
Examples:
Shows how to determine how to display a shape in a table cell.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Table table = builder.startTable();
builder.insertCell();
builder.insertCell();
builder.endTable();
TableStyle tableStyle = (TableStyle) doc.getStyles().add(StyleType.TABLE, "MyTableStyle1");
tableStyle.setBottomPadding(20.0);
tableStyle.setLeftPadding(10.0);
tableStyle.setRightPadding(10.0);
tableStyle.setTopPadding(20.0);
tableStyle.getBorders().setColor(Color.BLACK);
tableStyle.getBorders().setLineStyle(LineStyle.SINGLE);
table.setStyle(tableStyle);
builder.moveTo(table.getFirstRow().getFirstCell().getFirstParagraph());
Shape shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 50.0,
RelativeVerticalPosition.TOP_MARGIN, 100.0, 100.0, 100.0, WrapType.NONE);
// Set the "IsLayoutInCell" property to "true" to display the shape as an inline element inside the cell's paragraph.
// The coordinate origin that will determine the shape's location will be the top left corner of the shape's cell.
// If we re-size the cell, the shape will move to maintain the same position starting from the cell's top left.
// Set the "IsLayoutInCell" property to "false" to display the shape as an independent floating shape.
// The coordinate origin that will determine the shape's location will be the top left corner of the page,
// and the shape will not respond to any re-sizing of its cell.
shape.isLayoutInCell(isLayoutInCell);
// We can only apply the "IsLayoutInCell" property to floating shapes.
shape.setWrapType(WrapType.NONE);
doc.save(getArtifactsDir() + "Shape.LayoutInTableCell.docx");
Returns: boolean - A flag indicating whether the shape is displayed inside a table or outside of it.
isLayoutInCell(boolean value)
public void isLayoutInCell(boolean value)
Sets a flag indicating whether the shape is displayed inside a table or outside of it.
Remarks:
The default value is true .
Has effect only for top level shapes, the property getWrapType() / setWrapType(int) of which is set to value other than Inline.
Examples:
Shows how to determine how to display a shape in a table cell.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Table table = builder.startTable();
builder.insertCell();
builder.insertCell();
builder.endTable();
TableStyle tableStyle = (TableStyle) doc.getStyles().add(StyleType.TABLE, "MyTableStyle1");
tableStyle.setBottomPadding(20.0);
tableStyle.setLeftPadding(10.0);
tableStyle.setRightPadding(10.0);
tableStyle.setTopPadding(20.0);
tableStyle.getBorders().setColor(Color.BLACK);
tableStyle.getBorders().setLineStyle(LineStyle.SINGLE);
table.setStyle(tableStyle);
builder.moveTo(table.getFirstRow().getFirstCell().getFirstParagraph());
Shape shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 50.0,
RelativeVerticalPosition.TOP_MARGIN, 100.0, 100.0, 100.0, WrapType.NONE);
// Set the "IsLayoutInCell" property to "true" to display the shape as an inline element inside the cell's paragraph.
// The coordinate origin that will determine the shape's location will be the top left corner of the shape's cell.
// If we re-size the cell, the shape will move to maintain the same position starting from the cell's top left.
// Set the "IsLayoutInCell" property to "false" to display the shape as an independent floating shape.
// The coordinate origin that will determine the shape's location will be the top left corner of the page,
// and the shape will not respond to any re-sizing of its cell.
shape.isLayoutInCell(isLayoutInCell);
// We can only apply the "IsLayoutInCell" property to floating shapes.
shape.setWrapType(WrapType.NONE);
doc.save(getArtifactsDir() + "Shape.LayoutInTableCell.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A flag indicating whether the shape is displayed inside a table or outside of it. |
isMoveFromRevision()
public boolean isMoveFromRevision()
Returns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled.
Examples:
Shows how to identify move revision shapes.
// A move revision is when we move an element in the document body by cut-and-pasting it in Microsoft Word while
// tracking changes. If we involve an inline shape in such a text movement, that shape will also be a revision.
// Copying-and-pasting or moving floating shapes do not create move revisions.
Document doc = new Document(getMyDir() + "Revision shape.docx");
// Move revisions consist of pairs of "Move from", and "Move to" revisions. We moved in this document in one shape,
// but until we accept or reject the move revision, there will be two instances of that shape.
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(shapeList.size(), 2);
Shape firstShape = shapeList.get(0);
// This is the "Move to" revision, which is the shape at its arrival destination.
// If we accept the revision, this "Move to" revision shape will disappear,
// and the "Move from" revision shape will remain.
Assert.assertFalse(shapeList.get(0).isMoveFromRevision());
Assert.assertTrue(shapeList.get(0).isMoveToRevision());
// This is the "Move from" revision, which is the shape at its original location.
// If we accept the revision, this "Move from" revision shape will disappear,
// and the "Move to" revision shape will remain.
Assert.assertTrue(shapeList.get(1).isMoveFromRevision());
Assert.assertFalse(shapeList.get(1).isMoveToRevision());
Returns: boolean - true if this object was moved (deleted) in Microsoft Word while change tracking was enabled.
isMoveToRevision()
public boolean isMoveToRevision()
Returns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled.
Examples:
Shows how to identify move revision shapes.
// A move revision is when we move an element in the document body by cut-and-pasting it in Microsoft Word while
// tracking changes. If we involve an inline shape in such a text movement, that shape will also be a revision.
// Copying-and-pasting or moving floating shapes do not create move revisions.
Document doc = new Document(getMyDir() + "Revision shape.docx");
// Move revisions consist of pairs of "Move from", and "Move to" revisions. We moved in this document in one shape,
// but until we accept or reject the move revision, there will be two instances of that shape.
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(shapeList.size(), 2);
Shape firstShape = shapeList.get(0);
// This is the "Move to" revision, which is the shape at its arrival destination.
// If we accept the revision, this "Move to" revision shape will disappear,
// and the "Move from" revision shape will remain.
Assert.assertFalse(shapeList.get(0).isMoveFromRevision());
Assert.assertTrue(shapeList.get(0).isMoveToRevision());
// This is the "Move from" revision, which is the shape at its original location.
// If we accept the revision, this "Move from" revision shape will disappear,
// and the "Move to" revision shape will remain.
Assert.assertTrue(shapeList.get(1).isMoveFromRevision());
Assert.assertFalse(shapeList.get(1).isMoveToRevision());
Returns: boolean - true if this object was moved (inserted) in Microsoft Word while change tracking was enabled.
isSignatureLine()
public boolean isSignatureLine()
Indicates that shape is a SignatureLine.
Examples:
Shows how to create a line for a signature and insert it into a document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
SignatureLineOptions options = new SignatureLineOptions();
{
options.setAllowComments(true);
options.setDefaultInstructions(true);
options.setEmail("john.doe@management.com");
options.setInstructions("Please sign here");
options.setShowDate(true);
options.setSigner("John Doe");
options.setSignerTitle("Senior Manager");
}
// Insert a shape that will contain a signature line, whose appearance we will
// customize using the "SignatureLineOptions" object we have created above.
// If we insert a shape whose coordinates originate at the bottom right hand corner of the page,
// we will need to supply negative x and y coordinates to bring the shape into view.
Shape shape = builder.insertSignatureLine(options, RelativeHorizontalPosition.RIGHT_MARGIN, -170.0,
RelativeVerticalPosition.BOTTOM_MARGIN, -60.0, WrapType.NONE);
Assert.assertTrue(shape.isSignatureLine());
// Verify the properties of our signature line via its Shape object.
SignatureLine signatureLine = shape.getSignatureLine();
Assert.assertEquals(signatureLine.getEmail(), "john.doe@management.com");
Assert.assertEquals(signatureLine.getSigner(), "John Doe");
Assert.assertEquals(signatureLine.getSignerTitle(), "Senior Manager");
Assert.assertEquals(signatureLine.getInstructions(), "Please sign here");
Assert.assertTrue(signatureLine.getShowDate());
Assert.assertTrue(signatureLine.getAllowComments());
Assert.assertTrue(signatureLine.getDefaultInstructions());
doc.save(getArtifactsDir() + "Shape.SignatureLine.docx");
Returns: boolean - The corresponding boolean value.
isTopLevel()
public boolean isTopLevel()
Returns true if this shape is not a child of a group shape.
Examples:
Shows how to tell whether a shape is a part of a group shape.
Document doc = new Document();
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
shape.setWidth(200.0);
shape.setHeight(200.0);
shape.setWrapType(WrapType.NONE);
// A shape by default is not part of any group shape, and therefore has the "IsTopLevel" property set to "true".
Assert.assertTrue(shape.isTopLevel());
GroupShape group = new GroupShape(doc);
group.appendChild(shape);
// Once we assimilate a shape into a group shape, the "IsTopLevel" property changes to "false".
Assert.assertFalse(shape.isTopLevel());
Returns: boolean - true if this shape is not a child of a group shape.
isWordArt()
public boolean isWordArt()
Returns true if this shape is a WordArt object.
Remarks:
Works till 2007 compatibility mode. In 2010 and higher compatibility mode WordArt is just a TextBox with fancy fonts.
Examples:
Shows how to work with WordArt.
public void insertTextPaths() throws Exception {
Document doc = new Document();
// Insert a WordArt object to display text in a shape that we can re-size and move by using the mouse in Microsoft Word.
// Provide a "ShapeType" as an argument to set a shape for the WordArt.
Shape shape = appendWordArt(doc, "Hello World! This text is bold, and italic.",
"Arial", 480.0, 24.0, Color.WHITE, Color.BLACK, ShapeType.TEXT_PLAIN_TEXT);
// Apply the "Bold" and "Italic" formatting settings to the text using the respective properties.
shape.getTextPath().setBold(true);
shape.getTextPath().setItalic(true);
// Below are various other text formatting-related properties.
Assert.assertFalse(shape.getTextPath().getUnderline());
Assert.assertFalse(shape.getTextPath().getShadow());
Assert.assertFalse(shape.getTextPath().getStrikeThrough());
Assert.assertFalse(shape.getTextPath().getReverseRows());
Assert.assertFalse(shape.getTextPath().getXScale());
Assert.assertFalse(shape.getTextPath().getTrim());
Assert.assertFalse(shape.getTextPath().getSmallCaps());
Assert.assertEquals(36.0, shape.getTextPath().getSize());
Assert.assertEquals("Hello World! This text is bold, and italic.", shape.getTextPath().getText());
Assert.assertEquals(ShapeType.TEXT_PLAIN_TEXT, shape.getShapeType());
// Use the "On" property to show/hide the text.
shape = appendWordArt(doc, "On set to \"true\"", "Calibri", 150.0, 24.0, Color.YELLOW, Color.RED, ShapeType.TEXT_PLAIN_TEXT);
shape.getTextPath().setOn(true);
shape = appendWordArt(doc, "On set to \"false\"", "Calibri", 150.0, 24.0, Color.YELLOW, Color.pink, ShapeType.TEXT_PLAIN_TEXT);
shape.getTextPath().setOn(false);
// Use the "Kerning" property to enable/disable kerning spacing between certain characters.
shape = appendWordArt(doc, "Kerning: VAV", "Times New Roman", 90.0, 24.0, Color.ORANGE, Color.RED, ShapeType.TEXT_PLAIN_TEXT);
shape.getTextPath().setKerning(true);
shape = appendWordArt(doc, "No kerning: VAV", "Times New Roman", 100.0, 24.0, Color.ORANGE, Color.RED, ShapeType.TEXT_PLAIN_TEXT);
shape.getTextPath().setKerning(false);
// Use the "Spacing" property to set the custom spacing between characters on a scale from 0.0 (none) to 1.0 (default).
shape = appendWordArt(doc, "Spacing set to 0.1", "Calibri", 120.0, 24.0, Color.BLUE, Color.BLUE, ShapeType.TEXT_CASCADE_DOWN);
shape.getTextPath().setSpacing(0.1);
// Set the "RotateLetters" property to "true" to rotate each character 90 degrees counterclockwise.
shape = appendWordArt(doc, "RotateLetters", "Calibri", 200.0, 36.0, Color.YELLOW, Color.GREEN, ShapeType.TEXT_WAVE);
shape.getTextPath().setRotateLetters(true);
// Set the "SameLetterHeights" property to "true" to get the x-height of each character to equal the cap height.
shape = appendWordArt(doc, "Same character height for lower and UPPER case", "Calibri", 300.0, 24.0, Color.BLUE, Color.BLUE, ShapeType.TEXT_SLANT_UP);
shape.getTextPath().setSameLetterHeights(true);
// By default, the text's size will always scale to fit the containing shape's size, overriding the text size setting.
shape = appendWordArt(doc, "FitShape on", "Calibri", 160.0, 24.0, Color.BLUE, Color.BLUE, ShapeType.TEXT_PLAIN_TEXT);
Assert.assertTrue(shape.getTextPath().getFitShape());
shape.getTextPath().setSize(24.0);
// If we set the "FitShape: property to "false", the text will keep the size
// which the "Size" property specifies regardless of the size of the shape.
// Use the "TextPathAlignment" property also to align the text to a side of the shape.
shape = appendWordArt(doc, "FitShape off", "Calibri", 160.0, 24.0, Color.BLUE, Color.BLUE, ShapeType.TEXT_PLAIN_TEXT);
shape.getTextPath().setFitShape(false);
shape.getTextPath().setSize(24.0);
shape.getTextPath().setTextPathAlignment(TextPathAlignment.RIGHT);
doc.save(getArtifactsDir() + "Shape.InsertTextPaths.docx");
}
///
/// Insert a new paragraph with a WordArt shape inside it.
///
private static Shape appendWordArt(Document doc, String text, String textFontFamily, double shapeWidth, double shapeHeight, Color wordArtFill, Color line, int wordArtShapeType) throws Exception {
// Create an inline Shape, which will serve as a container for our WordArt.
// The shape can only be a valid WordArt shape if we assign a WordArt-designated ShapeType to it.
// These types will have "WordArt object" in the description,
// and their enumerator constant names will all start with "Text".
Shape shape = new Shape(doc, wordArtShapeType);
{
shape.setWrapType(WrapType.INLINE);
shape.setWidth(shapeWidth);
shape.setHeight(shapeHeight);
shape.setFillColor(wordArtFill);
shape.setStrokeColor(line);
}
shape.getTextPath().setText(text);
shape.getTextPath().setFontFamily(textFontFamily);
Paragraph para = (Paragraph) doc.getFirstSection().getBody().appendChild(new Paragraph(doc));
para.appendChild(shape);
return shape;
}
Returns: boolean - true if this shape is a WordArt object.
iterator()
public Iterator iterator()
Provides support for the for each style iteration over the child nodes of this node.
Examples:
Shows how to print all of a document’s comments and their replies.
Document doc = new Document(getMyDir() + "Comments.docx");
NodeCollection comments = doc.getChildNodes(NodeType.COMMENT, true);
// If a comment has no ancestor, it is a "top-level" comment as opposed to a reply-type comment.
// Print all top-level comments along with any replies they may have.
for (Comment comment : (Iterable) comments) {
if (comment.getAncestor() == null) {
System.out.println("Top-level comment:");
System.out.println("\t\"{comment.GetText().Trim()}\", by {comment.Author}");
System.out.println("Has {comment.Replies.Count} replies");
for (Comment commentReply : comment.getReplies()) {
System.out.println("\t\"{commentReply.GetText().Trim()}\", by {commentReply.Author}");
}
System.out.println();
}
}
Returns: java.util.Iterator
localToParent(Point2D.Float value)
public Point2D.Float localToParent(Point2D.Float value)
Converts a value from the local coordinate space into the coordinate space of the parent shape.
Examples:
Shows how to translate the x and y coordinate location on a shape’s coordinate plane to a location on the parent shape’s coordinate plane.
Document doc = new Document();
// Insert a group shape, and place it 100 points below and to the right of
// the document's x and Y coordinate origin point.
GroupShape group = new GroupShape(doc);
group.setBounds(new Rectangle2D.Float(100f, 100f, 500f, 500f));
// Use the "LocalToParent" method to determine that (0, 0) on the group's internal x and y coordinates
// lies on (100, 100) of its parent shape's coordinate system. The group shape's parent is the document itself.
Assert.assertEquals(new Point2D.Float(100f, 100f), group.localToParent(new Point2D.Float(0f, 0f)));
// By default, a shape's internal coordinate plane has the top left corner at (0, 0),
// and the bottom right corner at (1000, 1000). Due to its size, our group shape covers an area of 500pt x 500pt
// in the document's plane. This means that a movement of 1pt on the document's coordinate plane will translate
// to a movement of 2pts on the group shape's coordinate plane.
Assert.assertEquals(new Point2D.Float(150f, 150f), group.localToParent(new Point2D.Float(100f, 100f)));
Assert.assertEquals(new Point2D.Float(200f, 200f), group.localToParent(new Point2D.Float(200f, 200f)));
Assert.assertEquals(new Point2D.Float(250f, 250f), group.localToParent(new Point2D.Float(300f, 300f)));
// Move the group shape's x and y axis origin from the top left corner to the center.
// This will offset the group's internal coordinates relative to the document's coordinates even further.
group.setCoordOrigin(new Point(-250, -250));
Assert.assertEquals(new Point2D.Float(375f, 375f), group.localToParent(new Point2D.Float(300f, 300f)));
// Changing the scale of the coordinate plane will also affect relative locations.
group.setCoordSize(new Dimension(500, 500));
Assert.assertEquals(new Point2D.Float(650f, 650f), group.localToParent(new Point2D.Float(300f, 300f)));
// If we wish to add a shape to this group while defining its location based on a location in the document,
// we will need to first confirm a location in the group shape that will match the document's location.
Assert.assertEquals(new Point2D.Float(700f, 700f), group.localToParent(new Point2D.Float(350f, 350f)));
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(700.0);
shape.setTop(700.0);
}
group.appendChild(shape);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(group);
doc.save(getArtifactsDir() + "Shape.LocalToParent.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.awt.geom.Point2D.Float |
Returns: java.awt.geom.Point2D.Float
nextPreOrder(Node rootNode)
public Node nextPreOrder(Node rootNode)
Gets next node according to the pre-order tree traversal algorithm.
Examples:
Shows how to traverse the document’s node tree using the pre-order traversal algorithm, and delete any encountered shape with an image.
Document doc = new Document(getMyDir() + "Images.docx");
ArrayList shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(9, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
Node curNode = doc;
while (curNode != null) {
Node nextNode = curNode.nextPreOrder(doc);
if (curNode.previousPreOrder(doc) != null && nextNode != null)
Assert.assertEquals(curNode, nextNode.previousPreOrder(doc));
if (curNode.getNodeType() == NodeType.SHAPE && ((Shape) curNode).hasImage())
curNode.remove();
curNode = nextNode;
}
shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(0, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
Parameters:
| Parameter | Type | Description |
|---|---|---|
| rootNode | Node | The top node (limit) of traversal. |
Returns: Node - Next node in pre-order order. Null if reached the rootNode .
nodeTypeToString(int nodeType)
public static String nodeTypeToString(int nodeType)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| nodeType | int |
Returns: java.lang.String
oneColorGradient(int style, int variant, double degree)
public void oneColorGradient(int style, int variant, double degree)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| style | int | |
| variant | int | |
| degree | double |
patterned(int patternType)
public void patterned(int patternType)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| patternType | int |
prependChild(Node newChild)
public Node prependChild(Node newChild)
Adds the specified node to the beginning of the list of child nodes for this node.
Remarks:
If the newChild is already in the tree, it is first removed.
If the node being inserted was created from another document, you should use M:Aspose.Words.DocumentBase.ImportNode(Aspose.Words.Node,System.Boolean,Aspose.Words.ImportFormatMode) to import the node to the current document. The imported node can then be inserted into the current document.
Examples:
Shows how to add, update and delete child nodes in a CompositeNode’s collection of children.
Document doc = new Document();
// An empty document, by default, has one paragraph.
Assert.assertEquals(1, doc.getFirstSection().getBody().getParagraphs().getCount());
// Composite nodes such as our paragraph can contain other composite and inline nodes as children.
Paragraph paragraph = doc.getFirstSection().getBody().getFirstParagraph();
Run paragraphText = new Run(doc, "Initial text. ");
paragraph.appendChild(paragraphText);
// Create three more run nodes.
Run run1 = new Run(doc, "Run 1. ");
Run run2 = new Run(doc, "Run 2. ");
Run run3 = new Run(doc, "Run 3. ");
// The document body will not display these runs until we insert them into a composite node
// that itself is a part of the document's node tree, as we did with the first run.
// We can determine where the text contents of nodes that we insert
// appears in the document by specifying an insertion location relative to another node in the paragraph.
Assert.assertEquals("Initial text.", paragraph.getText().trim());
// Insert the second run into the paragraph in front of the initial run.
paragraph.insertBefore(run2, paragraphText);
Assert.assertEquals("Run 2. Initial text.", paragraph.getText().trim());
// Insert the third run after the initial run.
paragraph.insertAfter(run3, paragraphText);
Assert.assertEquals("Run 2. Initial text. Run 3.", paragraph.getText().trim());
// Insert the first run to the start of the paragraph's child nodes collection.
paragraph.prependChild(run1);
Assert.assertEquals("Run 1. Run 2. Initial text. Run 3.", paragraph.getText().trim());
Assert.assertEquals(4, paragraph.getChildNodes(NodeType.ANY, true).getCount());
// We can modify the contents of the run by editing and deleting existing child nodes.
((Run) paragraph.getChildNodes(NodeType.RUN, true).get(1)).setText("Updated run 2. ");
paragraph.getChildNodes(NodeType.RUN, true).remove(paragraphText);
Assert.assertEquals("Run 1. Updated run 2. Run 3.", paragraph.getText().trim());
Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, true).getCount());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| newChild | Node | The node to add. |
Returns: Node - The node added.
presetTextured(int presetTexture)
public void presetTextured(int presetTexture)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| presetTexture | int |
previousPreOrder(Node rootNode)
public Node previousPreOrder(Node rootNode)
Gets the previous node according to the pre-order tree traversal algorithm.
Examples:
Shows how to traverse the document’s node tree using the pre-order traversal algorithm, and delete any encountered shape with an image.
Document doc = new Document(getMyDir() + "Images.docx");
ArrayList shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(9, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
Node curNode = doc;
while (curNode != null) {
Node nextNode = curNode.nextPreOrder(doc);
if (curNode.previousPreOrder(doc) != null && nextNode != null)
Assert.assertEquals(curNode, nextNode.previousPreOrder(doc));
if (curNode.getNodeType() == NodeType.SHAPE && ((Shape) curNode).hasImage())
curNode.remove();
curNode = nextNode;
}
shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(0, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
Parameters:
| Parameter | Type | Description |
|---|---|---|
| rootNode | Node | The top node (limit) of traversal. |
Returns: Node - Previous node in pre-order order. Null if reached the rootNode .
remove()
public void remove()
Removes itself from the parent.
Examples:
Shows how to remove all child nodes of a specific type from a composite node.
Document doc = new Document(getMyDir() + "Tables.docx");
Assert.assertEquals(2, doc.getChildNodes(NodeType.TABLE, true).getCount());
Node curNode = doc.getFirstSection().getBody().getFirstChild();
while (curNode != null) {
// Save the next sibling node as a variable in case we want to move to it after deleting this node.
Node nextNode = curNode.getNextSibling();
// A section body can contain Paragraph and Table nodes.
// If the node is a Table, remove it from the parent.
if (curNode.getNodeType() == NodeType.TABLE) {
curNode.remove();
}
curNode = nextNode;
}
Assert.assertEquals(0, doc.getChildNodes(NodeType.TABLE, true).getCount());
Shows how to delete all shapes with images from a document.
Document doc = new Document(getMyDir() + "Images.docx");
ArrayList shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(9, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
for (Shape shape : shapes)
if (shape.hasImage())
shape.remove();
shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(0, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
removeAllChildren()
public void removeAllChildren()
Removes all the child nodes of the current node.
Examples:
Shows how to construct an Aspose.Words document by hand.
Document doc = new Document();
// A blank document contains one section, one body and one paragraph.
// Call the "RemoveAllChildren" method to remove all those nodes,
// and end up with a document node with no children.
doc.removeAllChildren();
// This document now has no composite child nodes that we can add content to.
// If we wish to edit it, we will need to repopulate its node collection.
// First, create a new section, and then append it as a child to the root document node.
Section section = new Section(doc);
doc.appendChild(section);
// Set some page setup properties for the section.
section.getPageSetup().setSectionStart(SectionStart.NEW_PAGE);
section.getPageSetup().setPaperSize(PaperSize.LETTER);
// A section needs a body, which will contain and display all its contents
// on the page between the section's header and footer.
Body body = new Body(doc);
section.appendChild(body);
// Create a paragraph, set some formatting properties, and then append it as a child to the body.
Paragraph para = new Paragraph(doc);
para.getParagraphFormat().setStyleName("Heading 1");
para.getParagraphFormat().setAlignment(ParagraphAlignment.CENTER);
body.appendChild(para);
// Finally, add some content to do the document. Create a run,
// set its appearance and contents, and then append it as a child to the paragraph.
Run run = new Run(doc);
run.setText("Hello World!");
run.getFont().setColor(Color.RED);
para.appendChild(run);
Assert.assertEquals("Hello World!", doc.getText().trim());
doc.save(getArtifactsDir() + "Section.CreateManually.docx");
removeChild(Node oldChild)
public Node removeChild(Node oldChild)
Removes the specified child node.
Remarks:
The parent of oldChild is set to null after the node is removed.
Examples:
Shows how to use of methods of Node and CompositeNode to remove a section before the last section in the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Section 1 text.");
builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
builder.writeln("Section 2 text.");
// Both sections are siblings of each other.
Section lastSection = (Section) doc.getLastChild();
Section firstSection = (Section) lastSection.getPreviousSibling();
// Remove a section based on its sibling relationship with another section.
if (lastSection.getPreviousSibling() != null)
doc.removeChild(firstSection);
// The section we removed was the first one, leaving the document with only the second.
Assert.assertEquals("Section 2 text.", doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| oldChild | Node | The node to remove. |
Returns: Node - The removed node.
removeGlow()
public void removeGlow()
removeMoveRevisions()
public void removeMoveRevisions()
removeReflection()
public void removeReflection()
removeRunAttr(int key)
public void removeRunAttr(int key)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | int |
removeShadow()
public void removeShadow()
removeShapeAttr(int key)
public void removeShapeAttr(int key)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | int |
removeSmartTags()
public void removeSmartTags()
Removes all SmartTag descendant nodes of the current node.
Remarks:
This method does not remove the content of the smart tags.
Examples:
Removes all smart tags from descendant nodes of a composite node.
Document doc = new Document(getMyDir() + "Smart tags.doc");
Assert.assertEquals(8, doc.getChildNodes(NodeType.SMART_TAG, true).getCount());
doc.removeSmartTags();
Assert.assertEquals(0, doc.getChildNodes(NodeType.SMART_TAG, true).getCount());
Shows how to create smart tags.
public void create() throws Exception {
Document doc = new Document();
// A smart tag appears in a document with Microsoft Word recognizes a part of its text as some form of data,
// such as a name, date, or address, and converts it to a hyperlink that displays a purple dotted underline.
SmartTag smartTag = new SmartTag(doc);
// Smart tags are composite nodes that contain their recognized text in its entirety.
// Add contents to this smart tag manually.
smartTag.appendChild(new Run(doc, "May 29, 2019"));
// Microsoft Word may recognize the above contents as being a date.
// Smart tags use the "Element" property to reflect the type of data they contain.
smartTag.setElement("date");
// Some smart tag types process their contents further into custom XML properties.
smartTag.getProperties().add(new CustomXmlProperty("Day", "", "29"));
smartTag.getProperties().add(new CustomXmlProperty("Month", "", "5"));
smartTag.getProperties().add(new CustomXmlProperty("Year", "", "2019"));
// Set the smart tag's URI to the default value.
smartTag.setUri("urn:schemas-microsoft-com:office:smarttags");
doc.getFirstSection().getBody().getFirstParagraph().appendChild(smartTag);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(new Run(doc, " is a date. "));
// Create another smart tag for a stock ticker.
smartTag = new SmartTag(doc);
smartTag.setElement("stockticker");
smartTag.setUri("urn:schemas-microsoft-com:office:smarttags");
smartTag.appendChild(new Run(doc, "MSFT"));
doc.getFirstSection().getBody().getFirstParagraph().appendChild(smartTag);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(new Run(doc, " is a stock ticker."));
// Print all the smart tags in our document using a document visitor.
doc.accept(new SmartTagPrinter());
// Older versions of Microsoft Word support smart tags.
doc.save(getArtifactsDir() + "SmartTag.Create.doc");
// Use the "RemoveSmartTags" method to remove all smart tags from a document.
Assert.assertEquals(2, doc.getChildNodes(NodeType.SMART_TAG, true).getCount());
doc.removeSmartTags();
Assert.assertEquals(0, doc.getChildNodes(NodeType.SMART_TAG, true).getCount());
}
///
/// Prints visited smart tags and their contents.
///
private static class SmartTagPrinter extends DocumentVisitor {
///
/// Called when a SmartTag node is encountered in the document.
///
public int visitSmartTagStart(SmartTag smartTag) {
System.out.println("Smart tag type: {smartTag.Element}");
return VisitorAction.CONTINUE;
}
///
/// Called when the visiting of a SmartTag node is ended.
///
public int visitSmartTagEnd(SmartTag smartTag) {
System.out.println("\tContents: \"{smartTag.ToString(SaveFormat.Text)}\"");
if (smartTag.getProperties().getCount() == 0) {
System.out.println("\tContains no properties");
} else {
System.out.println("\tProperties: ");
String[] properties = new String[smartTag.getProperties().getCount()];
int index = 0;
for (CustomXmlProperty cxp : smartTag.getProperties())
properties[index++] = MessageFormat.format("\"{0}\" = \"{1}\"", cxp.getName(), cxp.getValue());
System.out.println(StringUtils.join(properties, ", "));
}
return VisitorAction.CONTINUE;
}
}
removeSoftEdge()
public void removeSoftEdge()
selectNodes(String xpath)
public NodeList selectNodes(String xpath)
Selects a list of nodes matching the XPath expression.
Remarks:
Only expressions with element names are supported at the moment. Expressions that use attribute names are not supported.
Examples:
Shows how to use an XPath expression to test whether a node is inside a field.
Document doc = new Document(getMyDir() + "Mail merge destination - Northwind employees.docx");
// The NodeList that results from this XPath expression will contain all nodes we find inside a field.
// However, FieldStart and FieldEnd nodes can be on the list if there are nested fields in the path.
// Currently does not find rare fields in which the FieldCode or FieldResult spans across multiple paragraphs.
NodeList resultList =
doc.selectNodes("//FieldStart/following-sibling::node()[following-sibling::FieldEnd]");
Run[] runs = Arrays.stream(resultList.toArray()).filter(n -> n.getNodeType() == NodeType.RUN).toArray(Run[]::new);
Run run = runs[0];
// Check if the specified run is one of the nodes that are inside the field.
System.out.println(MessageFormat.format("Contents of the first Run node that''s part of a field: {0}", run.getText().trim()));
Shows how to select certain nodes by using an XPath expression.
Document doc = new Document(getMyDir() + "Tables.docx");
// This expression will extract all paragraph nodes,
// which are descendants of any table node in the document.
NodeList nodeList = doc.selectNodes("//Table//Paragraph");
// Iterate through the list with an enumerator and print the contents of every paragraph in each cell of the table.
int index = 0;
Iterator e = nodeList.iterator();
while (e.hasNext()) {
Node currentNode = e.next();
System.out.println(MessageFormat.format("Table paragraph index {0}, contents: \"{1}\"", index++, currentNode.getText().trim()));
}
// This expression will select any paragraphs that are direct children of any Body node in the document.
nodeList = doc.selectNodes("//Body/Paragraph");
// We can treat the list as an array.
Assert.assertEquals(nodeList.toArray().length, 4);
// Use SelectSingleNode to select the first result of the same expression as above.
Node node = doc.selectSingleNode("//Body/Paragraph");
Assert.assertEquals(Paragraph.class, node.getClass());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| xpath | java.lang.String | The XPath expression. |
Returns: NodeList - A list of nodes matching the XPath query.
selectSingleNode(String xpath)
public Node selectSingleNode(String xpath)
Selects the first Node that matches the XPath expression.
Remarks:
Only expressions with element names are supported at the moment. Expressions that use attribute names are not supported.
Examples:
Shows how to select certain nodes by using an XPath expression.
Document doc = new Document(getMyDir() + "Tables.docx");
// This expression will extract all paragraph nodes,
// which are descendants of any table node in the document.
NodeList nodeList = doc.selectNodes("//Table//Paragraph");
// Iterate through the list with an enumerator and print the contents of every paragraph in each cell of the table.
int index = 0;
Iterator e = nodeList.iterator();
while (e.hasNext()) {
Node currentNode = e.next();
System.out.println(MessageFormat.format("Table paragraph index {0}, contents: \"{1}\"", index++, currentNode.getText().trim()));
}
// This expression will select any paragraphs that are direct children of any Body node in the document.
nodeList = doc.selectNodes("//Body/Paragraph");
// We can treat the list as an array.
Assert.assertEquals(nodeList.toArray().length, 4);
// Use SelectSingleNode to select the first result of the same expression as above.
Node node = doc.selectSingleNode("//Body/Paragraph");
Assert.assertEquals(Paragraph.class, node.getClass());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| xpath | java.lang.String | The XPath expression. |
Returns: Node - The first Node that matches the XPath query or null if no matching node is found.
setAllowOverlap(boolean value)
public void setAllowOverlap(boolean value)
Sets a value that specifies whether this shape can overlap other shapes.
Remarks:
This property affects behavior of the shape in Microsoft Word. Aspose.Words ignores the value of this property.
This property is applicable only to top level shapes.
The default value is true .
Examples:
Shows how to work with floating tables properties.
Document doc = new Document(getMyDir() + "Table wrapped by text.docx");
Table table = doc.getFirstSection().getBody().getTables().get(0);
if (table.getTextWrapping() == TextWrapping.AROUND) {
Assert.assertEquals(RelativeHorizontalPosition.MARGIN, table.getHorizontalAnchor());
Assert.assertEquals(RelativeVerticalPosition.PARAGRAPH, table.getVerticalAnchor());
Assert.assertEquals(false, table.getAllowOverlap());
// Only Margin, Page, Column available in RelativeHorizontalPosition for HorizontalAnchor setter.
// The ArgumentException will be thrown for any other values.
table.setHorizontalAnchor(RelativeHorizontalPosition.COLUMN);
// Only Margin, Page, Paragraph available in RelativeVerticalPosition for VerticalAnchor setter.
// The ArgumentException will be thrown for any other values.
table.setVerticalAnchor(RelativeVerticalPosition.PAGE);
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A value that specifies whether this shape can overlap other shapes. |
setAlternativeText(String value)
public void setAlternativeText(String value)
Defines alternative text to be displayed instead of a graphic.
Remarks:
The default value is an empty string.
Examples:
Shows how to use a shape’s alternative text.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertShape(ShapeType.CUBE, 150.0, 150.0);
shape.setName("MyCube");
shape.setAlternativeText("Alt text for MyCube.");
// We can access the alternative text of a shape by right-clicking it, and then via "Format AutoShape" -> "Alt Text".
doc.save(getArtifactsDir() + "Shape.AltText.docx");
// Save the document to HTML, and then delete the linked image that belongs to our shape.
// The browser that is reading our HTML will display the alt text in place of the missing image.
doc.save(getArtifactsDir() + "Shape.AltText.html");
new File(getArtifactsDir() + "Shape.AltText.001.png").delete();
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.lang.String | The corresponding java.lang.String value. |
setAnchorLocked(boolean value)
public void setAnchorLocked(boolean value)
Specifies whether the shape’s anchor is locked.
Remarks:
The default value is false .
Has effect only for top level shapes.
This property affects behavior of the shape’s anchor in Microsoft Word. When the anchor is not locked, moving the shape in Microsoft Word can move the shape’s anchor too.
Examples:
Shows how to lock or unlock a shape’s paragraph anchor.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
builder.write("Our shape will have an anchor attached to this paragraph.");
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 200.0, 160.0);
shape.setWrapType(WrapType.NONE);
builder.insertBreak(BreakType.PARAGRAPH_BREAK);
builder.writeln("Hello again!");
// Set the "AnchorLocked" property to "true" to prevent the shape's anchor
// from moving when moving the shape in Microsoft Word.
// Set the "AnchorLocked" property to "false" to allow any movement of the shape
// to also move its anchor to any other paragraph that the shape ends up close to.
shape.setAnchorLocked(anchorLocked);
// If the shape does not have a visible anchor symbol to its left,
// we will need to enable visible anchors via "Options" -> "Display" -> "Object Anchors".
doc.save(getArtifactsDir() + "Shape.AnchorLocked.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The corresponding boolean value. |
setAspectRatioLocked(boolean value)
public void setAspectRatioLocked(boolean value)
Specifies whether the shape’s aspect ratio is locked.
Remarks:
The default value depends on the ShapeType, for the ShapeType.IMAGE it is true but for the other shape types it is false .
Has effect for top level shapes only.
Examples:
Shows how to lock/unlock a shape’s aspect ratio.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a shape. If we open this document in Microsoft Word, we can left click the shape to reveal
// eight sizing handles around its perimeter, which we can click and drag to change its size.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
// Set the "AspectRatioLocked" property to "true" to preserve the shape's aspect ratio
// when using any of the four diagonal sizing handles, which change both the image's height and width.
// Using any orthogonal sizing handles that either change the height or width will still change the aspect ratio.
// Set the "AspectRatioLocked" property to "false" to allow us to
// freely change the image's aspect ratio with all sizing handles.
shape.setAspectRatioLocked(lockAspectRatio);
doc.save(getArtifactsDir() + "Shape.AspectRatio.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The corresponding boolean value. |
setBehindText(boolean value)
public void setBehindText(boolean value)
Specifies whether the shape is below or above text.
Remarks:
Has effect only for top level shapes.
The default value is false .
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The corresponding boolean value. |
setBlur(double value)
public void setBlur(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setBounds(Rectangle2D.Float value)
public void setBounds(Rectangle2D.Float value)
Sets the location and size of the containing block of the shape.
Remarks:
Ignores aspect ratio lock upon setting.
For a top-level shape, the value is in points and relative to the shape anchor.
For shapes in a group, the value is in the coordinate space and units of the parent group.
Examples:
Shows how to verify shape containing block boundaries.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertShape(ShapeType.LINE, RelativeHorizontalPosition.LEFT_MARGIN, 50.0,
RelativeVerticalPosition.TOP_MARGIN, 50.0, 100.0, 100.0, WrapType.NONE);
shape.setStrokeColor(Color.ORANGE);
// Even though the line itself takes up little space on the document page,
// it occupies a rectangular containing block, the size of which we can determine using the "Bounds" properties.
Assert.assertEquals(new Rectangle2D.Float(50f, 50f, 100f, 100f), shape.getBounds());
Assert.assertEquals(new Rectangle2D.Float(50f, 50f, 100f, 100f), shape.getBoundsInPoints());
// Create a group shape, and then set the size of its containing block using the "Bounds" property.
GroupShape group = new GroupShape(doc);
group.setBounds(new Rectangle2D.Float(0f, 100f, 250f, 250f));
Assert.assertEquals(new Rectangle2D.Float(0f, 100f, 250f, 250f), group.getBoundsInPoints());
// Create a rectangle, verify the size of its bounding block, and then add it to the group shape.
shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(700.0);
shape.setTop(700.0);
}
Assert.assertEquals(new Rectangle2D.Float(700f, 700f, 100f, 100f), shape.getBoundsInPoints());
group.appendChild(shape);
// The group shape's coordinate plane has its origin on the top left-hand side corner of its containing block,
// and the x and y coordinates of (1000, 1000) on the bottom right-hand side corner.
// Our group shape is 250x250pt in size, so every 4pt on the group shape's coordinate plane
// translates to 1pt in the document body's coordinate plane.
// Every shape that we insert will also shrink in size by a factor of 4.
// The change in the shape's "BoundsInPoints" property will reflect this.
Assert.assertEquals(new Rectangle2D.Float(175f, 275f, 25f, 25f), shape.getBoundsInPoints());
doc.getFirstSection().getBody().getFirstParagraph().appendChild(group);
// Insert a shape and place it outside of the bounds of the group shape's containing block.
shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(1000.0);
shape.setTop(1000.0);
}
group.appendChild(shape);
// The group shape's footprint in the document body has increased, but the containing block remains the same.
Assert.assertEquals(new Rectangle2D.Float(0f, 100f, 250f, 250f), group.getBoundsInPoints());
Assert.assertEquals(new Rectangle2D.Float(250f, 350f, 25f, 25f), shape.getBoundsInPoints());
doc.save(getArtifactsDir() + "Shape.Bounds.docx");
Shows how to create and populate a group shape.
Document doc = new Document();
// Create a group shape. A group shape can display a collection of child shape nodes.
// In Microsoft Word, clicking within the group shape's boundary or on one of the group shape's child shapes will
// select all the other child shapes within this group and allow us to scale and move all the shapes at once.
GroupShape group = new GroupShape(doc);
Assert.assertEquals(WrapType.NONE, group.getWrapType());
// Create a 400pt x 400pt group shape and place it at the document's floating shape coordinate origin.
group.setBounds(new Rectangle2D.Float(0f, 0f, 400f, 400f));
// Set the group's internal coordinate plane size to 500 x 500pt.
// The top left corner of the group will have an x and y coordinate of (0, 0),
// and the bottom right corner will have an x and y coordinate of (500, 500).
group.setCoordSize(new Dimension(500, 500));
// Set the coordinates of the top left corner of the group to (-250, -250).
// The group's center will now have an x and y coordinate value of (0, 0),
// and the bottom right corner will be at (250, 250).
group.setCoordOrigin(new Point(-250, -250));
Shape rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(group.getCoordSize().width);
rectangleShape.setHeight(group.getCoordSize().height);
rectangleShape.setLeft(group.getCoordOrigin().x);
rectangleShape.setTop(group.getCoordOrigin().y);
// Create a rectangle that will display the boundary of this group shape and add it to the group.
group.appendChild(rectangleShape);
// Once a shape is a part of a group shape, we can access it as a child node and then modify it.
((Shape) group.getChild(NodeType.SHAPE, 0, true)).getStroke().setDashStyle(DashStyle.DASH);
Shape starShape = new Shape(doc, ShapeType.STAR);
starShape.setWidth(20.0);
starShape.setHeight(20.0);
starShape.setLeft(-10);
starShape.setTop(-10);
starShape.setFillColor(Color.RED);
// Create a small red star and insert it into the group.
// Line up the shape with the group's coordinate origin, which we have moved to the center.
group.appendChild(starShape);
rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(250.0);
rectangleShape.setHeight(250.0);
rectangleShape.setLeft(-250);
rectangleShape.setTop(-250);
rectangleShape.setFillColor(Color.BLUE);
// Insert a rectangle, and then insert a slightly smaller rectangle in the same place with an image.
// Newer shapes that we add to the group overlap older shapes. The light blue rectangle will partially overlap the red star,
// and then the shape with the image will overlap the light blue rectangle, using it as a frame.
// We cannot use the "ZOrder" properties of shapes to manipulate their arrangement within a group shape.
group.appendChild(rectangleShape);
Shape imageShape = new Shape(doc, ShapeType.IMAGE);
imageShape.setWidth(200.0);
imageShape.setHeight(200.0);
imageShape.setLeft(-225);
imageShape.setTop(-225);
group.appendChild(imageShape);
((Shape) group.getChild(NodeType.SHAPE, 3, true)).getImageData().setImage(getImageDir() + "Logo.jpg");
Shape textboxShape = new Shape(doc, ShapeType.TEXT_BOX);
textboxShape.setWidth(200.0);
textboxShape.setHeight(50.0);
textboxShape.setLeft(group.getCoordSize().width + new Point(group.getCoordOrigin()).x - 200);
textboxShape.setTop(group.getCoordSize().height + new Point(group.getCoordOrigin()).y);
// Insert a text box into the group shape. Set the "Left" property so that the text box's right edge
// touches the right boundary of the group shape. Set the "Top" property so that the text box sits outside
// the boundary of the group shape, with its top size lined up along the group shape's bottom margin.
group.appendChild(textboxShape);
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertNode(group);
builder.moveTo(((Shape) group.getChild(NodeType.SHAPE, 4, true)).appendChild(new Paragraph(doc)));
builder.write("Hello world!");
doc.save(getArtifactsDir() + "Shape.GroupShape.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.awt.geom.Rectangle2D.Float | The location and size of the containing block of the shape. |
setColor(Color value)
public void setColor(Color value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.awt.Color |
setCoordOrigin(Point value)
public void setCoordOrigin(Point value)
The coordinates at the top-left corner of the containing block of this shape.
Remarks:
The default value is (0,0).
Examples:
Shows how to translate the x and y coordinate location on a shape’s coordinate plane to a location on the parent shape’s coordinate plane.
Document doc = new Document();
// Insert a group shape, and place it 100 points below and to the right of
// the document's x and Y coordinate origin point.
GroupShape group = new GroupShape(doc);
group.setBounds(new Rectangle2D.Float(100f, 100f, 500f, 500f));
// Use the "LocalToParent" method to determine that (0, 0) on the group's internal x and y coordinates
// lies on (100, 100) of its parent shape's coordinate system. The group shape's parent is the document itself.
Assert.assertEquals(new Point2D.Float(100f, 100f), group.localToParent(new Point2D.Float(0f, 0f)));
// By default, a shape's internal coordinate plane has the top left corner at (0, 0),
// and the bottom right corner at (1000, 1000). Due to its size, our group shape covers an area of 500pt x 500pt
// in the document's plane. This means that a movement of 1pt on the document's coordinate plane will translate
// to a movement of 2pts on the group shape's coordinate plane.
Assert.assertEquals(new Point2D.Float(150f, 150f), group.localToParent(new Point2D.Float(100f, 100f)));
Assert.assertEquals(new Point2D.Float(200f, 200f), group.localToParent(new Point2D.Float(200f, 200f)));
Assert.assertEquals(new Point2D.Float(250f, 250f), group.localToParent(new Point2D.Float(300f, 300f)));
// Move the group shape's x and y axis origin from the top left corner to the center.
// This will offset the group's internal coordinates relative to the document's coordinates even further.
group.setCoordOrigin(new Point(-250, -250));
Assert.assertEquals(new Point2D.Float(375f, 375f), group.localToParent(new Point2D.Float(300f, 300f)));
// Changing the scale of the coordinate plane will also affect relative locations.
group.setCoordSize(new Dimension(500, 500));
Assert.assertEquals(new Point2D.Float(650f, 650f), group.localToParent(new Point2D.Float(300f, 300f)));
// If we wish to add a shape to this group while defining its location based on a location in the document,
// we will need to first confirm a location in the group shape that will match the document's location.
Assert.assertEquals(new Point2D.Float(700f, 700f), group.localToParent(new Point2D.Float(350f, 350f)));
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(700.0);
shape.setTop(700.0);
}
group.appendChild(shape);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(group);
doc.save(getArtifactsDir() + "Shape.LocalToParent.docx");
Shows how to create and populate a group shape.
Document doc = new Document();
// Create a group shape. A group shape can display a collection of child shape nodes.
// In Microsoft Word, clicking within the group shape's boundary or on one of the group shape's child shapes will
// select all the other child shapes within this group and allow us to scale and move all the shapes at once.
GroupShape group = new GroupShape(doc);
Assert.assertEquals(WrapType.NONE, group.getWrapType());
// Create a 400pt x 400pt group shape and place it at the document's floating shape coordinate origin.
group.setBounds(new Rectangle2D.Float(0f, 0f, 400f, 400f));
// Set the group's internal coordinate plane size to 500 x 500pt.
// The top left corner of the group will have an x and y coordinate of (0, 0),
// and the bottom right corner will have an x and y coordinate of (500, 500).
group.setCoordSize(new Dimension(500, 500));
// Set the coordinates of the top left corner of the group to (-250, -250).
// The group's center will now have an x and y coordinate value of (0, 0),
// and the bottom right corner will be at (250, 250).
group.setCoordOrigin(new Point(-250, -250));
Shape rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(group.getCoordSize().width);
rectangleShape.setHeight(group.getCoordSize().height);
rectangleShape.setLeft(group.getCoordOrigin().x);
rectangleShape.setTop(group.getCoordOrigin().y);
// Create a rectangle that will display the boundary of this group shape and add it to the group.
group.appendChild(rectangleShape);
// Once a shape is a part of a group shape, we can access it as a child node and then modify it.
((Shape) group.getChild(NodeType.SHAPE, 0, true)).getStroke().setDashStyle(DashStyle.DASH);
Shape starShape = new Shape(doc, ShapeType.STAR);
starShape.setWidth(20.0);
starShape.setHeight(20.0);
starShape.setLeft(-10);
starShape.setTop(-10);
starShape.setFillColor(Color.RED);
// Create a small red star and insert it into the group.
// Line up the shape with the group's coordinate origin, which we have moved to the center.
group.appendChild(starShape);
rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(250.0);
rectangleShape.setHeight(250.0);
rectangleShape.setLeft(-250);
rectangleShape.setTop(-250);
rectangleShape.setFillColor(Color.BLUE);
// Insert a rectangle, and then insert a slightly smaller rectangle in the same place with an image.
// Newer shapes that we add to the group overlap older shapes. The light blue rectangle will partially overlap the red star,
// and then the shape with the image will overlap the light blue rectangle, using it as a frame.
// We cannot use the "ZOrder" properties of shapes to manipulate their arrangement within a group shape.
group.appendChild(rectangleShape);
Shape imageShape = new Shape(doc, ShapeType.IMAGE);
imageShape.setWidth(200.0);
imageShape.setHeight(200.0);
imageShape.setLeft(-225);
imageShape.setTop(-225);
group.appendChild(imageShape);
((Shape) group.getChild(NodeType.SHAPE, 3, true)).getImageData().setImage(getImageDir() + "Logo.jpg");
Shape textboxShape = new Shape(doc, ShapeType.TEXT_BOX);
textboxShape.setWidth(200.0);
textboxShape.setHeight(50.0);
textboxShape.setLeft(group.getCoordSize().width + new Point(group.getCoordOrigin()).x - 200);
textboxShape.setTop(group.getCoordSize().height + new Point(group.getCoordOrigin()).y);
// Insert a text box into the group shape. Set the "Left" property so that the text box's right edge
// touches the right boundary of the group shape. Set the "Top" property so that the text box sits outside
// the boundary of the group shape, with its top size lined up along the group shape's bottom margin.
group.appendChild(textboxShape);
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertNode(group);
builder.moveTo(((Shape) group.getChild(NodeType.SHAPE, 4, true)).appendChild(new Paragraph(doc)));
builder.write("Hello world!");
doc.save(getArtifactsDir() + "Shape.GroupShape.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.awt.Point | The corresponding java.awt.Point value. |
setCoordSize(Dimension value)
public void setCoordSize(Dimension value)
The width and height of the coordinate space inside the containing block of this shape.
Remarks:
The default value is (1000, 1000).
Examples:
Shows how to translate the x and y coordinate location on a shape’s coordinate plane to a location on the parent shape’s coordinate plane.
Document doc = new Document();
// Insert a group shape, and place it 100 points below and to the right of
// the document's x and Y coordinate origin point.
GroupShape group = new GroupShape(doc);
group.setBounds(new Rectangle2D.Float(100f, 100f, 500f, 500f));
// Use the "LocalToParent" method to determine that (0, 0) on the group's internal x and y coordinates
// lies on (100, 100) of its parent shape's coordinate system. The group shape's parent is the document itself.
Assert.assertEquals(new Point2D.Float(100f, 100f), group.localToParent(new Point2D.Float(0f, 0f)));
// By default, a shape's internal coordinate plane has the top left corner at (0, 0),
// and the bottom right corner at (1000, 1000). Due to its size, our group shape covers an area of 500pt x 500pt
// in the document's plane. This means that a movement of 1pt on the document's coordinate plane will translate
// to a movement of 2pts on the group shape's coordinate plane.
Assert.assertEquals(new Point2D.Float(150f, 150f), group.localToParent(new Point2D.Float(100f, 100f)));
Assert.assertEquals(new Point2D.Float(200f, 200f), group.localToParent(new Point2D.Float(200f, 200f)));
Assert.assertEquals(new Point2D.Float(250f, 250f), group.localToParent(new Point2D.Float(300f, 300f)));
// Move the group shape's x and y axis origin from the top left corner to the center.
// This will offset the group's internal coordinates relative to the document's coordinates even further.
group.setCoordOrigin(new Point(-250, -250));
Assert.assertEquals(new Point2D.Float(375f, 375f), group.localToParent(new Point2D.Float(300f, 300f)));
// Changing the scale of the coordinate plane will also affect relative locations.
group.setCoordSize(new Dimension(500, 500));
Assert.assertEquals(new Point2D.Float(650f, 650f), group.localToParent(new Point2D.Float(300f, 300f)));
// If we wish to add a shape to this group while defining its location based on a location in the document,
// we will need to first confirm a location in the group shape that will match the document's location.
Assert.assertEquals(new Point2D.Float(700f, 700f), group.localToParent(new Point2D.Float(350f, 350f)));
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
{
shape.setWidth(100.0);
shape.setHeight(100.0);
shape.setLeft(700.0);
shape.setTop(700.0);
}
group.appendChild(shape);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(group);
doc.save(getArtifactsDir() + "Shape.LocalToParent.docx");
Shows how to create and populate a group shape.
Document doc = new Document();
// Create a group shape. A group shape can display a collection of child shape nodes.
// In Microsoft Word, clicking within the group shape's boundary or on one of the group shape's child shapes will
// select all the other child shapes within this group and allow us to scale and move all the shapes at once.
GroupShape group = new GroupShape(doc);
Assert.assertEquals(WrapType.NONE, group.getWrapType());
// Create a 400pt x 400pt group shape and place it at the document's floating shape coordinate origin.
group.setBounds(new Rectangle2D.Float(0f, 0f, 400f, 400f));
// Set the group's internal coordinate plane size to 500 x 500pt.
// The top left corner of the group will have an x and y coordinate of (0, 0),
// and the bottom right corner will have an x and y coordinate of (500, 500).
group.setCoordSize(new Dimension(500, 500));
// Set the coordinates of the top left corner of the group to (-250, -250).
// The group's center will now have an x and y coordinate value of (0, 0),
// and the bottom right corner will be at (250, 250).
group.setCoordOrigin(new Point(-250, -250));
Shape rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(group.getCoordSize().width);
rectangleShape.setHeight(group.getCoordSize().height);
rectangleShape.setLeft(group.getCoordOrigin().x);
rectangleShape.setTop(group.getCoordOrigin().y);
// Create a rectangle that will display the boundary of this group shape and add it to the group.
group.appendChild(rectangleShape);
// Once a shape is a part of a group shape, we can access it as a child node and then modify it.
((Shape) group.getChild(NodeType.SHAPE, 0, true)).getStroke().setDashStyle(DashStyle.DASH);
Shape starShape = new Shape(doc, ShapeType.STAR);
starShape.setWidth(20.0);
starShape.setHeight(20.0);
starShape.setLeft(-10);
starShape.setTop(-10);
starShape.setFillColor(Color.RED);
// Create a small red star and insert it into the group.
// Line up the shape with the group's coordinate origin, which we have moved to the center.
group.appendChild(starShape);
rectangleShape = new Shape(doc, ShapeType.RECTANGLE);
rectangleShape.setWidth(250.0);
rectangleShape.setHeight(250.0);
rectangleShape.setLeft(-250);
rectangleShape.setTop(-250);
rectangleShape.setFillColor(Color.BLUE);
// Insert a rectangle, and then insert a slightly smaller rectangle in the same place with an image.
// Newer shapes that we add to the group overlap older shapes. The light blue rectangle will partially overlap the red star,
// and then the shape with the image will overlap the light blue rectangle, using it as a frame.
// We cannot use the "ZOrder" properties of shapes to manipulate their arrangement within a group shape.
group.appendChild(rectangleShape);
Shape imageShape = new Shape(doc, ShapeType.IMAGE);
imageShape.setWidth(200.0);
imageShape.setHeight(200.0);
imageShape.setLeft(-225);
imageShape.setTop(-225);
group.appendChild(imageShape);
((Shape) group.getChild(NodeType.SHAPE, 3, true)).getImageData().setImage(getImageDir() + "Logo.jpg");
Shape textboxShape = new Shape(doc, ShapeType.TEXT_BOX);
textboxShape.setWidth(200.0);
textboxShape.setHeight(50.0);
textboxShape.setLeft(group.getCoordSize().width + new Point(group.getCoordOrigin()).x - 200);
textboxShape.setTop(group.getCoordSize().height + new Point(group.getCoordOrigin()).y);
// Insert a text box into the group shape. Set the "Left" property so that the text box's right edge
// touches the right boundary of the group shape. Set the "Top" property so that the text box sits outside
// the boundary of the group shape, with its top size lined up along the group shape's bottom margin.
group.appendChild(textboxShape);
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertNode(group);
builder.moveTo(((Shape) group.getChild(NodeType.SHAPE, 4, true)).appendChild(new Paragraph(doc)));
builder.write("Hello world!");
doc.save(getArtifactsDir() + "Shape.GroupShape.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.awt.Dimension | The corresponding java.awt.Dimension value. |
setCustomNodeId(int value)
public void setCustomNodeId(int value)
Specifies custom node identifier.
Remarks:
Default is zero.
This identifier can be set and used arbitrarily. For example, as a key to get external data.
Important note, specified value is not saved to an output file and exists only during the node lifetime.
Examples:
Shows how to traverse through a composite node’s collection of child nodes.
Document doc = new Document();
// Add two runs and one shape as child nodes to the first paragraph of this document.
Paragraph paragraph = (Paragraph) doc.getChild(NodeType.PARAGRAPH, 0, true);
paragraph.appendChild(new Run(doc, "Hello world! "));
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
shape.setWidth(200.0);
shape.setHeight(200.0);
// Note that the 'CustomNodeId' is not saved to an output file and exists only during the node lifetime.
shape.setCustomNodeId(100);
shape.setWrapType(WrapType.INLINE);
paragraph.appendChild(shape);
paragraph.appendChild(new Run(doc, "Hello again!"));
// Iterate through the paragraph's collection of immediate children,
// and print any runs or shapes that we find within.
NodeCollection children = paragraph.getChildNodes(NodeType.ANY, false);
Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, false).getCount());
for (Node child : (Iterable) children)
switch (child.getNodeType()) {
case NodeType.RUN:
System.out.println("Run contents:");
System.out.println(MessageFormat.format("\t\"{0}\"", child.getText().trim()));
break;
case NodeType.SHAPE:
Shape childShape = (Shape)child;
System.out.println("Shape:");
System.out.println(MessageFormat.format("\t{0}, {1}x{2}", childShape.getShapeType(), childShape.getWidth(), childShape.getHeight()));
break;
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. |
setDistance(double value)
public void setDistance(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setDistanceBottom(double value)
public void setDistanceBottom(double value)
Sets the distance (in points) between the document text and the bottom edge of the shape.
Remarks:
The default value is 0.
Has effect only for top level shapes.
Examples:
Shows how to set the wrapping distance for a text that surrounds a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a rectangle and, get the text to wrap tightly around its bounds.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 150.0, 150.0);
shape.setWrapType(WrapType.TIGHT);
// Set the minimum distance between the shape and surrounding text to 40pt from all sides.
shape.setDistanceTop(40.0);
shape.setDistanceBottom(40.0);
shape.setDistanceLeft(40.0);
shape.setDistanceRight(40.0);
// Move the shape closer to the center of the page, and then rotate the shape 60 degrees clockwise.
shape.setTop(75.0);
shape.setLeft(150.0);
shape.setRotation(60.0);
// Add text that will wrap around the shape.
builder.getFont().setSize(24.0d);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
doc.save(getArtifactsDir() + "Shape.Coordinates.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double | The distance (in points) between the document text and the bottom edge of the shape. |
setDistanceLeft(double value)
public void setDistanceLeft(double value)
Sets the distance (in points) between the document text and the left edge of the shape.
Remarks:
The default value is 1/8 inch.
Has effect only for top level shapes.
Examples:
Shows how to set the wrapping distance for a text that surrounds a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a rectangle and, get the text to wrap tightly around its bounds.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 150.0, 150.0);
shape.setWrapType(WrapType.TIGHT);
// Set the minimum distance between the shape and surrounding text to 40pt from all sides.
shape.setDistanceTop(40.0);
shape.setDistanceBottom(40.0);
shape.setDistanceLeft(40.0);
shape.setDistanceRight(40.0);
// Move the shape closer to the center of the page, and then rotate the shape 60 degrees clockwise.
shape.setTop(75.0);
shape.setLeft(150.0);
shape.setRotation(60.0);
// Add text that will wrap around the shape.
builder.getFont().setSize(24.0d);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
doc.save(getArtifactsDir() + "Shape.Coordinates.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double | The distance (in points) between the document text and the left edge of the shape. |
setDistanceRight(double value)
public void setDistanceRight(double value)
Sets the distance (in points) between the document text and the right edge of the shape.
Remarks:
The default value is 1/8 inch.
Has effect only for top level shapes.
Examples:
Shows how to set the wrapping distance for a text that surrounds a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a rectangle and, get the text to wrap tightly around its bounds.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 150.0, 150.0);
shape.setWrapType(WrapType.TIGHT);
// Set the minimum distance between the shape and surrounding text to 40pt from all sides.
shape.setDistanceTop(40.0);
shape.setDistanceBottom(40.0);
shape.setDistanceLeft(40.0);
shape.setDistanceRight(40.0);
// Move the shape closer to the center of the page, and then rotate the shape 60 degrees clockwise.
shape.setTop(75.0);
shape.setLeft(150.0);
shape.setRotation(60.0);
// Add text that will wrap around the shape.
builder.getFont().setSize(24.0d);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
doc.save(getArtifactsDir() + "Shape.Coordinates.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double | The distance (in points) between the document text and the right edge of the shape. |
setDistanceTop(double value)
public void setDistanceTop(double value)
Sets the distance (in points) between the document text and the top edge of the shape.
Remarks:
The default value is 0.
Has effect only for top level shapes.
Examples:
Shows how to set the wrapping distance for a text that surrounds a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a rectangle and, get the text to wrap tightly around its bounds.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 150.0, 150.0);
shape.setWrapType(WrapType.TIGHT);
// Set the minimum distance between the shape and surrounding text to 40pt from all sides.
shape.setDistanceTop(40.0);
shape.setDistanceBottom(40.0);
shape.setDistanceLeft(40.0);
shape.setDistanceRight(40.0);
// Move the shape closer to the center of the page, and then rotate the shape 60 degrees clockwise.
shape.setTop(75.0);
shape.setLeft(150.0);
shape.setRotation(60.0);
// Add text that will wrap around the shape.
builder.getFont().setSize(24.0d);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
doc.save(getArtifactsDir() + "Shape.Coordinates.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double | The distance (in points) between the document text and the top edge of the shape. |
setEdgeRadius(double value)
public void setEdgeRadius(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setFillableBackColor(Color value)
public void setFillableBackColor(Color value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.awt.Color |
setFillableBackThemeColor(int value)
public void setFillableBackThemeColor(int value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int |
setFillableBackTintAndShade(double value)
public void setFillableBackTintAndShade(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setFillableForeColor(Color value)
public void setFillableForeColor(Color value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.awt.Color |
setFillableForeThemeColor(int value)
public void setFillableForeThemeColor(int value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int |
setFillableForeTintAndShade(double value)
public void setFillableForeTintAndShade(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setFillableTransparency(double value)
public void setFillableTransparency(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setFillableVisible(boolean value)
public void setFillableVisible(boolean value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean |
setFilledColor(Color value)
public void setFilledColor(Color value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.awt.Color |
setFlipOrientation(int value)
public void setFlipOrientation(int value)
Switches the orientation of a shape.
Remarks:
The default value is FlipOrientation.NONE.
Examples:
Shows how to flip a shape on an axis.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert an image shape and leave its orientation in its default state.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 100.0,
RelativeVerticalPosition.TOP_MARGIN, 100.0, 100.0, 100.0, WrapType.NONE);
shape.getImageData().setImage(getImageDir() + "Logo.jpg");
Assert.assertEquals(FlipOrientation.NONE, shape.getFlipOrientation());
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 250.0,
RelativeVerticalPosition.TOP_MARGIN, 100.0, 100.0, 100.0, WrapType.NONE);
shape.getImageData().setImage(getImageDir() + "Logo.jpg");
// Set the "FlipOrientation" property to "FlipOrientation.Horizontal" to flip the second shape on the y-axis,
// making it into a horizontal mirror image of the first shape.
shape.setFlipOrientation(FlipOrientation.HORIZONTAL);
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 100.0,
RelativeVerticalPosition.TOP_MARGIN, 250.0, 100.0, 100.0, WrapType.NONE);
shape.getImageData().setImage(getImageDir() + "Logo.jpg");
// Set the "FlipOrientation" property to "FlipOrientation.Horizontal" to flip the third shape on the x-axis,
// making it into a vertical mirror image of the first shape.
shape.setFlipOrientation(FlipOrientation.VERTICAL);
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 250.0,
RelativeVerticalPosition.TOP_MARGIN, 250.0, 100.0, 100.0, WrapType.NONE);
shape.getImageData().setImage(getImageDir() + "Logo.jpg");
// Set the "FlipOrientation" property to "FlipOrientation.Horizontal" to flip the fourth shape on both the x and y axes,
// making it into a horizontal and vertical mirror image of the first shape.
shape.setFlipOrientation(FlipOrientation.BOTH);
doc.save(getArtifactsDir() + "Shape.FlipShapeOrientation.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. The value must be a bitwise combination of FlipOrientation constants. |
setGradientAngle(double value)
public void setGradientAngle(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setHRef(String value)
public void setHRef(String value)
Sets the full hyperlink address for a shape.
Remarks:
The default value is an empty string.
Below are examples of valid values for this property:
Full URI: https://www.aspose.com/ .
Full file name: C:\\My Documents\\SalesReport.doc .
Relative URI: ../../../resource.txt
Relative file name: ..\\My Documents\\SalesReport.doc .
Bookmark within another document: https://www.aspose.com/Products/Default.aspx#Suites
Bookmark within this document: #BookmakName .
Examples:
Shows how to insert a shape which contains an image, and is also a hyperlink.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setHRef("https://forum.aspose.com/");
shape.setTarget("New Window");
shape.setScreenTip("Aspose.Words Support Forums");
// Ctrl + left-clicking the shape in Microsoft Word will open a new web browser window
// and take us to the hyperlink in the "HRef" property.
doc.save(getArtifactsDir() + "Image.InsertImageWithHyperlink.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.lang.String | The full hyperlink address for a shape. |
setHeight(double value)
public void setHeight(double value)
Sets the height of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points.
For shapes in a group, the value is in the coordinate space and units of the parent group.
The default value is 0.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Shows how to resize a shape with an image.
// When we insert an image using the "InsertImage" method, the builder scales the shape that displays the image so that,
// when we view the document using 100% zoom in Microsoft Word, the shape displays the image in its actual size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
// A 400x400 image will create an ImageData object with an image size of 300x300pt.
ImageSize imageSize = shape.getImageData().getImageSize();
Assert.assertEquals(300.0d, imageSize.getWidthPoints());
Assert.assertEquals(300.0d, imageSize.getHeightPoints());
// If a shape's dimensions match the image data's dimensions,
// then the shape is displaying the image in its original size.
Assert.assertEquals(300.0d, shape.getWidth());
Assert.assertEquals(300.0d, shape.getHeight());
// Reduce the overall size of the shape by 50%.
shape.setWidth(shape.getWidth() * 0.5);
// Scaling factors apply to both the width and the height at the same time to preserve the shape's proportions.
Assert.assertEquals(150.0d, shape.getWidth());
Assert.assertEquals(150.0d, shape.getHeight());
// When we resize the shape, the size of the image data remains the same.
Assert.assertEquals(300.0d, imageSize.getWidthPoints());
Assert.assertEquals(300.0d, imageSize.getHeightPoints());
// We can reference the image data dimensions to apply a scaling based on the size of the image.
shape.setWidth(imageSize.getWidthPoints() * 1.1);
Assert.assertEquals(330.0d, shape.getWidth());
Assert.assertEquals(330.0d, shape.getHeight());
doc.save(getArtifactsDir() + "Image.ScaleImage.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double | The height of the containing block of the shape. |
setHeightRelative(float value)
public void setHeightRelative(float value)
Sets the value that represents the percentage of shape’s relative height.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | float | The value that represents the percentage of shape’s relative height. |
setHidden(boolean value)
public void setHidden(boolean value)
Sets a boolean value indicating whether the shape is visible.
Remarks:
The default value is false .
Examples:
Shows how to hide the shape.
Document doc = new Document(getMyDir() + "Shadow color.docx");
Shape shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
if (!shape.getHidden())
shape.setHidden(true);
doc.save(getArtifactsDir() + "Shape.Hidden.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A boolean value indicating whether the shape is visible. |
setHorizontalAlignment(int value)
public void setHorizontalAlignment(int value)
Specifies how the shape is positioned horizontally.
Remarks:
The default value is HorizontalAlignment.NONE.
Has effect only for top level floating shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. The value must be one of HorizontalAlignment constants. |
setImage(byte[] imageBytes)
public void setImage(byte[] imageBytes)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| imageBytes | byte[] |
setLeft(double value)
public void setLeft(double value)
Sets the position of the left edge of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points and relative to the shape anchor.
For shapes in a group, the value is in the coordinate space and units of the parent group.
The default value is 0.
Has effect only for floating shapes.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double | The position of the left edge of the containing block of the shape. |
setLeftRelative(float value)
public void setLeftRelative(float value)
Sets the value that represents shape’s relative left position in percent.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | float | The value that represents shape’s relative left position in percent. |
setName(String value)
public void setName(String value)
Sets the optional shape name.
Remarks:
Default is empty string.
Cannot be null , but can be an empty string.
Examples:
Shows how to use a shape’s alternative text.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertShape(ShapeType.CUBE, 150.0, 150.0);
shape.setName("MyCube");
shape.setAlternativeText("Alt text for MyCube.");
// We can access the alternative text of a shape by right-clicking it, and then via "Format AutoShape" -> "Alt Text".
doc.save(getArtifactsDir() + "Shape.AltText.docx");
// Save the document to HTML, and then delete the linked image that belongs to our shape.
// The browser that is reading our HTML will display the alt text in place of the missing image.
doc.save(getArtifactsDir() + "Shape.AltText.html");
new File(getArtifactsDir() + "Shape.AltText.001.png").delete();
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.lang.String | The optional shape name. |
setOldOn(boolean value)
public void setOldOn(boolean value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean |
setOldOpacity(double value)
public void setOldOpacity(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setRadius(double value)
public void setRadius(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setReflectionSize(double value)
public void setReflectionSize(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setReflectionTransparency(double value)
public void setReflectionTransparency(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setRelativeHorizontalPosition(int value)
public void setRelativeHorizontalPosition(int value)
Specifies relative to what the shape is positioned horizontally.
Remarks:
The default value is RelativeHorizontalPosition.COLUMN.
Has effect only for top level floating shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. The value must be one of RelativeHorizontalPosition constants. |
setRelativeHorizontalSize(int value)
public void setRelativeHorizontalSize(int value)
Sets the value of shape’s relative size in horizontal direction.
Remarks:
The default value is RelativeHorizontalSize.
Has effect only if getWidthRelative() / setWidthRelative(float) is set.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The value of shape’s relative size in horizontal direction. The value must be one of RelativeHorizontalSize constants. |
setRelativeVerticalPosition(int value)
public void setRelativeVerticalPosition(int value)
Specifies relative to what the shape is positioned vertically.
Remarks:
The default value is RelativeVerticalPosition.PARAGRAPH.
Has effect only for top level floating shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. The value must be one of RelativeVerticalPosition constants. |
setRelativeVerticalSize(int value)
public void setRelativeVerticalSize(int value)
Sets the value of shape’s relative size in vertical direction.
Remarks:
The default value is RelativeVerticalSize.MARGIN.
Has effect only if getHeightRelative() / setHeightRelative(float) is set.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The value of shape’s relative size in vertical direction. The value must be one of RelativeVerticalSize constants. |
setRotateWithObject(boolean value)
public void setRotateWithObject(boolean value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean |
setRotation(double value)
public void setRotation(double value)
Defines the angle (in degrees) that a shape is rotated. Positive value corresponds to clockwise rotation angle.
Remarks:
The default value is 0.
Examples:
Shows how to insert and rotate an image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a shape with an image.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
Assert.assertTrue(shape.canHaveImage());
Assert.assertTrue(shape.hasImage());
// Rotate the image 45 degrees clockwise.
shape.setRotation(45.0);
doc.save(getArtifactsDir() + "Shape.Rotate.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double | The corresponding double value. |
setRunAttr(int fontAttr, Object value)
public void setRunAttr(int fontAttr, Object value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| fontAttr | int | |
| value | java.lang.Object |
setScreenTip(String value)
public void setScreenTip(String value)
Defines the text displayed when the mouse pointer moves over the shape.
Remarks:
The default value is an empty string.
Examples:
Shows how to insert a shape which contains an image, and is also a hyperlink.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setHRef("https://forum.aspose.com/");
shape.setTarget("New Window");
shape.setScreenTip("Aspose.Words Support Forums");
// Ctrl + left-clicking the shape in Microsoft Word will open a new web browser window
// and take us to the hyperlink in the "HRef" property.
doc.save(getArtifactsDir() + "Image.InsertImageWithHyperlink.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.lang.String | The corresponding java.lang.String value. |
setShadowType(int value)
public void setShadowType(int value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int |
setShapeAttr(int key, Object value)
public void setShapeAttr(int key, Object value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | int | |
| value | java.lang.Object |
setTarget(String value)
public void setTarget(String value)
Sets the target frame for the shape hyperlink.
Remarks:
The default value is an empty string.
Examples:
Shows how to insert a shape which contains an image, and is also a hyperlink.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setHRef("https://forum.aspose.com/");
shape.setTarget("New Window");
shape.setScreenTip("Aspose.Words Support Forums");
// Ctrl + left-clicking the shape in Microsoft Word will open a new web browser window
// and take us to the hyperlink in the "HRef" property.
doc.save(getArtifactsDir() + "Image.InsertImageWithHyperlink.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.lang.String | The target frame for the shape hyperlink. |
setTextureAlignment(int value)
public void setTextureAlignment(int value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int |
setTitle(String value)
public void setTitle(String value)
Sets the title (caption) of the current shape object.
Remarks:
Default is empty string.
Cannot be null , but can be an empty string.
Examples:
Shows how to set the title of a shape.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create a shape, give it a title, and then add it to the document.
Shape shape = new Shape(doc, ShapeType.CUBE);
shape.setWidth(200.0);
shape.setHeight(200.0);
shape.setTitle("My cube");
builder.insertNode(shape);
// When we save a document with a shape that has a title,
// Aspose.Words will store that title in the shape's Alt Text.
doc.save(getArtifactsDir() + "Shape.Title.docx");
doc = new Document(getArtifactsDir() + "Shape.Title.docx");
shape = (Shape) doc.getChild(NodeType.SHAPE, 0, true);
Assert.assertEquals("", shape.getTitle());
Assert.assertEquals("Title: My cube", shape.getAlternativeText());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | java.lang.String | The title (caption) of the current shape object. |
setTop(double value)
public void setTop(double value)
Sets the position of the top edge of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points and relative to the shape anchor.
For shapes in a group, the value is in the coordinate space and units of the parent group.
The default value is 0.
Has effect only for floating shapes.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double | The position of the top edge of the containing block of the shape. |
setTopRelative(float value)
public void setTopRelative(float value)
Sets the value that represents shape’s relative top position in percent.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | float | The value that represents shape’s relative top position in percent. |
setTransparency(double value)
public void setTransparency(double value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double |
setVerticalAlignment(int value)
public void setVerticalAlignment(int value)
Specifies how the shape is positioned vertically.
Remarks:
The default value is VerticalAlignment.NONE.
Has effect only for top level floating shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. The value must be one of VerticalAlignment constants. |
setWidth(double value)
public void setWidth(double value)
Sets the width of the containing block of the shape.
Remarks:
For a top-level shape, the value is in points.
For shapes in a group, the value is in the coordinate space and units of the parent group.
The default value is 0.
Examples:
Shows how to insert a floating image, and specify its position and size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
// Configure the shape's "RelativeHorizontalPosition" property to treat the value of the "Left" property
// as the shape's horizontal distance, in points, from the left side of the page.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
// Set the shape's horizontal distance from the left side of the page to 100.
shape.setLeft(100.0);
// Use the "RelativeVerticalPosition" property in a similar way to position the shape 80pt below the top of the page.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setTop(80.0);
// Set the shape's height, which will automatically scale the width to preserve dimensions.
shape.setHeight(125.0);
Assert.assertEquals(125.0d, shape.getWidth());
// The "Bottom" and "Right" properties contain the bottom and right edges of the image.
Assert.assertEquals(shape.getTop() + shape.getHeight(), shape.getBottom());
Assert.assertEquals(shape.getLeft() + shape.getWidth(), shape.getRight());
doc.save(getArtifactsDir() + "Image.CreateFloatingPositionSize.docx");
Shows how to resize a shape with an image.
// When we insert an image using the "InsertImage" method, the builder scales the shape that displays the image so that,
// when we view the document using 100% zoom in Microsoft Word, the shape displays the image in its actual size.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
// A 400x400 image will create an ImageData object with an image size of 300x300pt.
ImageSize imageSize = shape.getImageData().getImageSize();
Assert.assertEquals(300.0d, imageSize.getWidthPoints());
Assert.assertEquals(300.0d, imageSize.getHeightPoints());
// If a shape's dimensions match the image data's dimensions,
// then the shape is displaying the image in its original size.
Assert.assertEquals(300.0d, shape.getWidth());
Assert.assertEquals(300.0d, shape.getHeight());
// Reduce the overall size of the shape by 50%.
shape.setWidth(shape.getWidth() * 0.5);
// Scaling factors apply to both the width and the height at the same time to preserve the shape's proportions.
Assert.assertEquals(150.0d, shape.getWidth());
Assert.assertEquals(150.0d, shape.getHeight());
// When we resize the shape, the size of the image data remains the same.
Assert.assertEquals(300.0d, imageSize.getWidthPoints());
Assert.assertEquals(300.0d, imageSize.getHeightPoints());
// We can reference the image data dimensions to apply a scaling based on the size of the image.
shape.setWidth(imageSize.getWidthPoints() * 1.1);
Assert.assertEquals(330.0d, shape.getWidth());
Assert.assertEquals(330.0d, shape.getHeight());
doc.save(getArtifactsDir() + "Image.ScaleImage.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | double | The width of the containing block of the shape. |
setWidthRelative(float value)
public void setWidthRelative(float value)
Sets the value that represents the percentage of shape’s relative width.
Examples:
Shows how to set relative size and position.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Adding a simple shape with absolute size and position.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, 100.0, 40.0);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.setWrapType(WrapType.NONE);
// Checking and setting the relative horizontal size.
if (shape.getRelativeHorizontalSize() == RelativeHorizontalSize.DEFAULT)
{
// Setting the horizontal size binding to Margin.
shape.setRelativeHorizontalSize(RelativeHorizontalSize.MARGIN);
// Setting the width to 50% of Margin width.
shape.setWidthRelative(50f);
}
// Checking and setting the relative vertical size.
if (shape.getRelativeVerticalSize() == RelativeVerticalSize.DEFAULT)
{
// Setting the vertical size binding to Margin.
shape.setRelativeVerticalSize(RelativeVerticalSize.MARGIN);
// Setting the heigh to 30% of Margin height.
shape.setHeightRelative(30f);
}
// Checking and setting the relative vertical position.
if (shape.getRelativeVerticalPosition() == RelativeVerticalPosition.PARAGRAPH)
{
// etting the position binding to TopMargin.
shape.setRelativeVerticalPosition(RelativeVerticalPosition.TOP_MARGIN);
// Setting relative Top to 30% of TopMargin position.
shape.setTopRelative(30f);
}
// Checking and setting the relative horizontal position.
if (shape.getRelativeHorizontalPosition() == RelativeHorizontalPosition.DEFAULT)
{
// Setting the position binding to RightMargin.
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.RIGHT_MARGIN);
// The position relative value can be negative.
shape.setLeftRelative(-260);
}
doc.save(getArtifactsDir() + "Shape.RelativeSizeAndPosition.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | float | The value that represents the percentage of shape’s relative width. |
setWrapSide(int value)
public void setWrapSide(int value)
Specifies how the text is wrapped around the shape.
Remarks:
The default value is WrapSide.BOTH.
Has effect only for top level shapes.
Examples:
Shows how to replace all textbox shapes with image shapes.
Document doc = new Document(getMyDir() + "Textboxes in drawing canvas.docx");
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(3, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.TEXT_BOX));
Assert.assertEquals(1, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.IMAGE));
for (Shape shape : shapeList) {
if (((shape.getShapeType()) == (ShapeType.TEXT_BOX))) {
Shape replacementShape = new Shape(doc, ShapeType.IMAGE);
replacementShape.getImageData().setImage(getImageDir() + "Logo.jpg");
replacementShape.setLeft(shape.getLeft());
replacementShape.setTop(shape.getTop());
replacementShape.setWidth(shape.getWidth());
replacementShape.setHeight(shape.getHeight());
replacementShape.setRelativeHorizontalPosition(shape.getRelativeHorizontalPosition());
replacementShape.setRelativeVerticalPosition(shape.getRelativeVerticalPosition());
replacementShape.setHorizontalAlignment(shape.getHorizontalAlignment());
replacementShape.setVerticalAlignment(shape.getVerticalAlignment());
replacementShape.setWrapType(shape.getWrapType());
replacementShape.setWrapSide(shape.getWrapSide());
shape.getParentNode().insertAfter(replacementShape, shape);
shape.remove();
}
}
shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
Assert.assertEquals(0, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.TEXT_BOX));
Assert.assertEquals(4, IterableUtils.countMatches(shapeList, s -> s.getShapeType() == ShapeType.IMAGE));
doc.save(getArtifactsDir() + "Shape.ReplaceTextboxesWithImages.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. The value must be one of WrapSide constants. |
setWrapType(int value)
public void setWrapType(int value)
Defines whether the shape is inline or floating. For floating shapes defines the wrapping mode for text around the shape.
Remarks:
The default value is WrapType.NONE.
Has effect only for top level shapes.
Examples:
Shows how to insert a floating image to the center of a page.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.insertImage(getImageDir() + "Logo.jpg");
shape.setWrapType(WrapType.NONE);
shape.setBehindText(true);
shape.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE);
shape.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE);
shape.setHorizontalAlignment(HorizontalAlignment.CENTER);
shape.setVerticalAlignment(VerticalAlignment.CENTER);
doc.save(getArtifactsDir() + "Image.CreateFloatingPageCenter.docx");
Shows how to create and format a text box.
Document doc = new Document();
// Create a floating text box.
Shape textBox = new Shape(doc, ShapeType.TEXT_BOX);
textBox.setWrapType(WrapType.NONE);
textBox.setHeight(50.0);
textBox.setWidth(200.0);
// Set the horizontal, and vertical alignment of the text inside the shape.
textBox.setHorizontalAlignment(HorizontalAlignment.CENTER);
textBox.setVerticalAlignment(VerticalAlignment.TOP);
// Add a paragraph to the text box and add a run of text that the text box will display.
textBox.appendChild(new Paragraph(doc));
Paragraph para = textBox.getFirstParagraph();
para.getParagraphFormat().setAlignment(ParagraphAlignment.CENTER);
Run run = new Run(doc);
run.setText("Hello world!");
para.appendChild(run);
doc.getFirstSection().getBody().getFirstParagraph().appendChild(textBox);
doc.save(getArtifactsDir() + "Shape.CreateTextBox.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. The value must be one of WrapType constants. |
setZOrder(int value)
public void setZOrder(int value)
Determines the display order of overlapping shapes.
Remarks:
Has effect only for top level shapes.
The default value is 0.
The number represents the stacking precedence. A shape with a higher number will be displayed as if it were overlapping (in “front” of) a shape with a lower number.
The order of overlapping shapes is independent for shapes in the header and in the main text of the document.
The display order of child shapes in a group shape is determined by their order inside the group shape.
Examples:
Shows how to manipulate the order of shapes.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert three different colored rectangles that partially overlap each other.
// When we insert a shape that overlaps another shape, Aspose.Words places the newer shape on top of the old one.
// The light green rectangle will overlap the light blue rectangle and partially obscure it,
// and the light blue rectangle will obscure the orange rectangle.
Shape shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 100.0,
RelativeVerticalPosition.TOP_MARGIN, 100.0, 200.0, 200.0, WrapType.NONE);
shape.setFillColor(Color.ORANGE);
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 150.0,
RelativeVerticalPosition.TOP_MARGIN, 150.0, 200.0, 200.0, WrapType.NONE);
shape.setFillColor(Color.BLUE);
shape = builder.insertShape(ShapeType.RECTANGLE, RelativeHorizontalPosition.LEFT_MARGIN, 200.0,
RelativeVerticalPosition.TOP_MARGIN, 200.0, 200.0, 200.0, WrapType.NONE);
shape.setFillColor(Color.GREEN);
List shapeList = Arrays.stream(doc.getChildNodes(NodeType.SHAPE, true).toArray())
.filter(Shape.class::isInstance)
.map(Shape.class::cast)
.collect(Collectors.toList());
// The "ZOrder" property of a shape determines its stacking priority among other overlapping shapes.
// If two overlapping shapes have different "ZOrder" values,
// Microsoft Word will place the shape with a higher value over the shape with the lower value.
// Set the "ZOrder" values of our shapes to place the first orange rectangle over the second light blue one
// and the second light blue rectangle over the third light green rectangle.
// This will reverse their original stacking order.
shapeList.get(0).setZOrder(3);
shapeList.get(1).setZOrder(2);
shapeList.get(2).setZOrder(1);
doc.save(getArtifactsDir() + "Shape.ZOrder.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. |
setZOrder_IShape(int value)
public void setZOrder_IShape(int value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int |
solid()
public void solid()
toString()
public String toString()
Returns: java.lang.String
toString(SaveOptions saveOptions)
public String toString(SaveOptions saveOptions)
Exports the content of the node into a string using the specified save options.
Examples:
Exports the content of a node to String in HTML format.
Document doc = new Document(getMyDir() + "Document.docx");
Node node = doc.getLastSection().getBody().getLastParagraph();
// When we call the ToString method using the html SaveFormat overload,
// it converts the node's contents to their raw html representation.
Assert.assertEquals(" " +
"Hello World!" +
"", node.toString(SaveFormat.HTML));
// We can also modify the result of this conversion using a SaveOptions object.
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.setExportRelativeFontSize(true);
Assert.assertEquals(" " +
"Hello World!" +
"", node.toString(saveOptions));
Parameters:
| Parameter | Type | Description |
|---|---|---|
| saveOptions | SaveOptions | Specifies the options that control how the node is saved. |
Returns: java.lang.String - The content of the node in the specified format.
toString(int saveFormat)
public String toString(int saveFormat)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| saveFormat | int |
Returns: java.lang.String
twoColorGradient(int style, int variant)
public void twoColorGradient(int style, int variant)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| style | int | |
| variant | int |
