com.aspose.words

Class StructuredDocumentTag

java.lang.Object

com.aspose.words.Node

com.aspose.words.CompositeNode

com.aspose.words.StructuredDocumentTag

All Implemented Interfaces:

IStructuredDocumentTag, java.lang.Cloneable, java.lang.Iterable

public class StructuredDocumentTag
extends CompositeNode
implements IStructuredDocumentTag

Represents a structured document tag (SDT or content control) in a document.

To learn more, visit the Structured Document Tags or Content Control documentation article.

Remarks:

Structured document tags (SDTs) allow to embed customer-defined semantics as well as its behavior and appearance into a document.

In this version Aspose.Words provides a number of public methods and properties to manipulate the behavior and content of StructuredDocumentTag. Mapping of SDT nodes to custom XML packages within a document can be performed with using the getXmlMapping() property.

StructuredDocumentTag can occur in a document in the following places:

• Block-level - Among paragraphs and tables, as a child of a Body, HeaderFooter, Comment, Footnote or a Shape node.
• Row-level - Among rows in a table, as a child of a Table node.
• Cell-level - Among cells in a table row, as a child of a Row node.
• Inline-level - Among inline content inside, as a child of a Paragraph.
• Nested inside another StructuredDocumentTag.

Examples:

Shows how to work with styles for content control elements.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Below are two ways to apply a style from the document to a structured document tag.
 // 1 -  Apply a style object from the document's style collection:
 Style quoteStyle = doc.getStyles().getByStyleIdentifier(StyleIdentifier.QUOTE);
 StructuredDocumentTag sdtPlainText = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);
 sdtPlainText.setStyle(quoteStyle);

 // 2 -  Reference a style in the document by name:
 StructuredDocumentTag sdtRichText = new StructuredDocumentTag(doc, SdtType.RICH_TEXT, MarkupLevel.INLINE);
 sdtRichText.setStyleName("Quote");

 builder.insertNode(sdtPlainText);
 builder.insertNode(sdtRichText);

 Assert.assertEquals(NodeType.STRUCTURED_DOCUMENT_TAG, sdtPlainText.getNodeType());

 NodeCollection tags = doc.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true);

 for (StructuredDocumentTag sdt : (Iterable<StructuredDocumentTag>) tags) {
     Assert.assertEquals(StyleIdentifier.QUOTE, sdt.getStyle().getStyleIdentifier());
     Assert.assertEquals("Quote", sdt.getStyleName());
 }
 
 

Constructor Summary

Constructors

Constructor and Description
StructuredDocumentTag(DocumentBase doc, int type, int level) Initializes a new instance of this class.

Method Summary

Modifier and Type	Method and Description
boolean	accept(DocumentVisitor visitor) Accepts a visitor.
int	acceptEnd(DocumentVisitor visitor) Accepts a visitor for visiting the end of the StructuredDocumentTag.
int	acceptStart(DocumentVisitor visitor) Accepts a visitor for visiting the start of the StructuredDocumentTag.
void	clear() Clears contents of this structured document tag and displays a placeholder if it is defined.
void	clearRunAttrs()
java.lang.Object	fetchInheritedRunAttr(int key)
int	getAppearance() Gets/sets the appearance of a structured document tag.
java.lang.String	getBuildingBlockCategory() Specifies category of building block for this SDT node.
java.lang.String	getBuildingBlockGallery() Specifies type of building block for this SDT.
int	getCalendarType() Specifies the type of calendar for this SDT.
boolean	getChecked() Gets/Sets current state of the Checkbox SDT.
java.awt.Color	getColor() Gets the color of the structured document tag.
Font	getContentsFont() Font formatting that will be applied to text entered into SDT.
java.lang.String	getDateDisplayFormat() String that represents the format in which dates are displayed.
int	getDateDisplayLocale() Allows to set/get the language format for the date displayed in this SDT.
int	getDateStorageFormat() Gets/sets format in which the date for a date SDT is stored when the SDT is bound to an XML node in the document's data store.
java.lang.Object	getDirectRunAttr(int key)
java.lang.Object	getDirectRunAttr(int key, int revisionsView)
Font	getEndCharacterFont() Font formatting that will be applied to the last character of text entered into SDT.
java.util.Date	getFullDate() Specifies the full date and time last entered into this SDT.
int	getId() Specifies a unique read-only persistent numerical Id for this SDT.
int	getLevel_IMarkupNode()
int	getLevel() Gets the level at which this SDT occurs in the document tree.
SdtListItemCollection	getListItems() Gets SdtListItemCollection associated with this SDT.
boolean	getLockContentControl() When set to true, this property will prohibit a user from deleting this SDT.
boolean	getLockContents() When set to true, this property will prohibit a user from editing the contents of this SDT.
boolean	getMultiline() Specifies whether this SDT allows multiple lines of text.
Node	getNode() Returns Node object that implements this interface.
int	getNodeType() Returns NodeType.STRUCTURED_DOCUMENT_TAG.
BuildingBlock	getPlaceholder() Gets the BuildingBlock containing placeholder text which should be displayed when this SDT run contents are empty, the associated mapped XML element is empty as specified via the getXmlMapping() element or the isShowingPlaceholderText() / isShowingPlaceholderText(boolean) element is true.
java.lang.String	getPlaceholderName() Gets or sets Name of the BuildingBlock containing placeholder text.
int	getSdtType() Gets type of this Structured document tag.
Style	getStyle() Gets the Style of the structured document tag.
java.lang.String	getStyleName() Gets the name of the style applied to the structured document tag.
java.lang.String	getTag() Specifies a tag associated with the current SDT node.
java.lang.String	getTitle() Specifies the friendly name associated with this SDT.
java.lang.String	getWordOpenXML() Gets a string that represents the XML contained within the node in the SaveFormat.FLAT_OPC format.
java.lang.String	getWordOpenXMLMinimal() Gets a string that represents the XML contained within the node in the SaveFormat.FLAT_OPC format.
XmlMapping	getXmlMapping() Gets an object that represents the mapping of this structured document tag to XML data in a custom XML part of the current document.
boolean	isMultiSection() Returns true if this instance is a ranged (multi-section) structured document tag.
boolean	isShowingPlaceholderText() Specifies whether the content of this SDT shall be interpreted to contain placeholder text (as opposed to regular text contents within the SDT).
void	isShowingPlaceholderText(boolean value) Specifies whether the content of this SDT shall be interpreted to contain placeholder text (as opposed to regular text contents within the SDT).
boolean	isTemporary() Specifies whether this SDT shall be removed from the WordProcessingML document when its contents are modified.
void	isTemporary(boolean value) Specifies whether this SDT shall be removed from the WordProcessingML document when its contents are modified.
void	removeMoveRevisions()
void	removeRunAttr(int key)
void	removeSelfOnly() Removes just this SDT node itself, but keeps the content of it inside the document tree.
void	setAppearance(int value) Gets/sets the appearance of a structured document tag.
void	setBuildingBlockCategory(java.lang.String value) Specifies category of building block for this SDT node.
void	setBuildingBlockGallery(java.lang.String value) Specifies type of building block for this SDT.
void	setCalendarType(int value) Specifies the type of calendar for this SDT.
void	setChecked(boolean value) Gets/Sets current state of the Checkbox SDT.
void	setCheckedSymbol(int characterCode, java.lang.String fontName) Sets the symbol used to represent the checked state of a check box content control.
void	setColor(java.awt.Color value) Sets the color of the structured document tag.
void	setDateDisplayFormat(java.lang.String value) String that represents the format in which dates are displayed.
void	setDateDisplayLocale(int value) Allows to set/get the language format for the date displayed in this SDT.
void	setDateStorageFormat(int value) Gets/sets format in which the date for a date SDT is stored when the SDT is bound to an XML node in the document's data store.
void	setFullDate(java.util.Date value) Specifies the full date and time last entered into this SDT.
void	setLockContentControl(boolean value) When set to true, this property will prohibit a user from deleting this SDT.
void	setLockContents(boolean value) When set to true, this property will prohibit a user from editing the contents of this SDT.
void	setMultiline(boolean value) Specifies whether this SDT allows multiple lines of text.
void	setPlaceholderName(java.lang.String value) Gets or sets Name of the BuildingBlock containing placeholder text.
void	setRunAttr(int key, java.lang.Object value)
void	setStyle(Style value) Sets the Style of the structured document tag.
void	setStyleName(java.lang.String value) Sets the name of the style applied to the structured document tag.
void	setTag(java.lang.String value) Specifies a tag associated with the current SDT node.
void	setTitle(java.lang.String value) Specifies the friendly name associated with this SDT.
void	setUncheckedSymbol(int characterCode, java.lang.String fontName) Sets the symbol used to represent the unchecked state of a check box content control.

Methods inherited from class com.aspose.words.CompositeNode

acceptChildren, acceptCore, appendChild, coreRemoveSelfOnly, getChild, getChildNodes, getContainer, getCount, getCurrentNode, getFirstChild, getLastChild, getNextMatchingNode, getText, hasChildNodes, indexOf, insertAfter, insertBefore, isComposite, iterator, prependChild, removeAllChildren, removeChild, removeSmartTags, selectNodes, selectSingleNode

Methods inherited from class com.aspose.words.Node

deepClone, getAncestor, getAncestor, getCustomNodeId, getDocument, getNextSibling, getParentNode, getPreviousSibling, getRange, memberwiseClone, nextPreOrder, nodeTypeToString, previousPreOrder, remove, setCustomNodeId, toString, toString, toString, visitorActionToBool

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.aspose.words.IStructuredDocumentTag

getChildNodes

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

StructuredDocumentTag

public StructuredDocumentTag(DocumentBase doc,
                             int type,
                             int level)

Initializes a new instance of this class.

Method Detail

setCheckedSymbol

public void setCheckedSymbol(int characterCode,
                             java.lang.String fontName)
                      throws java.lang.Exception

Sets the symbol used to represent the checked state of a check box content control.

Remarks:

Accessing this method will only work for SdtType.CHECKBOX SDT types.

For all other SDT types exception will occur.

Examples:

Show how to create a structured document tag in the form of a check box.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 StructuredDocumentTag sdtCheckBox = new StructuredDocumentTag(doc, SdtType.CHECKBOX, MarkupLevel.INLINE);
 sdtCheckBox.setChecked(true);
 sdtCheckBox.setCheckedSymbol(0x00A9, "Times New Roman");
 sdtCheckBox.setUncheckedSymbol(0x00AE, "Times New Roman");

 builder.insertNode(sdtCheckBox);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.CheckBox.docx");
 
 

Parameters:

characterCode - The character code for the specified symbol.

fontName - The name of the font that contains the symbol.

Throws:

java.lang.Exception

setUncheckedSymbol

public void setUncheckedSymbol(int characterCode,
                               java.lang.String fontName)
                        throws java.lang.Exception

Sets the symbol used to represent the unchecked state of a check box content control.

Remarks:

Accessing this method will only work for SdtType.CHECKBOX SDT types.

For all other SDT types exception will occur.

Examples:

Show how to create a structured document tag in the form of a check box.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 StructuredDocumentTag sdtCheckBox = new StructuredDocumentTag(doc, SdtType.CHECKBOX, MarkupLevel.INLINE);
 sdtCheckBox.setChecked(true);
 sdtCheckBox.setCheckedSymbol(0x00A9, "Times New Roman");
 sdtCheckBox.setUncheckedSymbol(0x00AE, "Times New Roman");

 builder.insertNode(sdtCheckBox);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.CheckBox.docx");
 
 

Parameters:

characterCode - The character code for the specified symbol.

fontName - The name of the font that contains the symbol.

Throws:

java.lang.Exception

removeSelfOnly

public void removeSelfOnly()
                    throws java.lang.Exception

Removes just this SDT node itself, but keeps the content of it inside the document tree.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

removeSelfOnly in interface IStructuredDocumentTag

Throws:

java.lang.Exception

accept

public boolean accept(DocumentVisitor visitor)
               throws java.lang.Exception

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.

Calls DocumentVisitor.visitStructuredDocumentTagStart(com.aspose.words.StructuredDocumentTag), then calls Node.accept(com.aspose.words.DocumentVisitor) for all child nodes of the smart tag and calls DocumentVisitor.visitStructuredDocumentTagEnd(com.aspose.words.StructuredDocumentTag) at the end.

Examples:

Shows how to print the node structure of every structured document tag in a document.

 
 public void structuredDocumentTagToText() throws Exception {
     Document doc = new Document(getMyDir() + "DocumentVisitor-compatible features.docx");
     StructuredDocumentTagNodePrinter visitor = new StructuredDocumentTagNodePrinter();

     // 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());
 }

 /// <summary>
 /// Traverses a node's non-binary tree of child nodes.
 /// Creates a map in the form of a string of all encountered StructuredDocumentTag nodes and their children.
 /// </summary>
 public static class StructuredDocumentTagNodePrinter extends DocumentVisitor {
     public StructuredDocumentTagNodePrinter() {
         mBuilder = new StringBuilder();
         mVisitorIsInsideStructuredDocumentTag = false;
     }

     /// <summary>
     /// Gets the plain text of the document that was accumulated by the visitor.
     /// </summary>
     public String getText() {
         return mBuilder.toString();
     }

     /// <summary>
     /// Called when a Run node is encountered in the document.
     /// </summary>
     public int visitRun(final Run run) {
         if (mVisitorIsInsideStructuredDocumentTag) {
             indentAndAppendLine("[Run] \"" + run.getText() + "\"");
         }

         return VisitorAction.CONTINUE;
     }

     /// <summary>
     /// Called when a StructuredDocumentTag node is encountered in the document.
     /// </summary>
     public int visitStructuredDocumentTagStart(final StructuredDocumentTag sdt) {
         indentAndAppendLine("[StructuredDocumentTag start] Title: " + sdt.getTitle());
         mDocTraversalDepth++;

         return VisitorAction.CONTINUE;
     }

     /// <summary>
     /// Called after all the child nodes of a StructuredDocumentTag node have been visited.
     /// </summary>
     public int visitStructuredDocumentTagEnd(final StructuredDocumentTag sdt) {
         mDocTraversalDepth--;
         indentAndAppendLine("[StructuredDocumentTag end]");

         return VisitorAction.CONTINUE;
     }

     /// <summary>
     /// Append a line to the StringBuilder and indent it depending on how deep the visitor is into the document tree.
     /// </summary>
     /// <param name="text"></param>
     private void indentAndAppendLine(final String text) {
         for (int i = 0; i < mDocTraversalDepth; i++) {
             mBuilder.append("|  ");
         }

         mBuilder.append(text + "\r\n");
     }

     private final boolean mVisitorIsInsideStructuredDocumentTag;
     private int mDocTraversalDepth;
     private final StringBuilder mBuilder;
 }
 
 

Specified by:

accept in class Node

Parameters:

visitor - The visitor that will visit the nodes.

Returns:

True if all nodes were visited; false if DocumentVisitor stopped the operation before visiting all nodes.

Throws:

java.lang.Exception

clear

public void clear()
           throws java.lang.Exception

Clears contents of this structured document tag and displays a placeholder if it is defined.

Remarks:

It is not possible to clear contents of a structured document tag if it has revisions.

If this structured document tag is mapped to custom XML (with using the getXmlMapping() property), the referenced XML node is cleared.

Examples:

Shows how to delete contents of structured document tag elements.

 
 Document doc = new Document();

 // Create a plain text structured document tag, and then append it to the document.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);
 doc.getFirstSection().getBody().appendChild(tag);

 // This structured document tag, which is in the form of a text box, already displays placeholder text.
 Assert.assertEquals("Click here to enter text.", tag.getText().trim());
 Assert.assertTrue(tag.isShowingPlaceholderText());

 // Create a building block with text contents.
 GlossaryDocument glossaryDoc = doc.getGlossaryDocument();
 BuildingBlock substituteBlock = new BuildingBlock(glossaryDoc);
 substituteBlock.setName("My placeholder");
 substituteBlock.appendChild(new Section(glossaryDoc));
 substituteBlock.getFirstSection().ensureMinimum();
 substituteBlock.getFirstSection().getBody().getFirstParagraph().appendChild(new Run(glossaryDoc, "Custom placeholder text."));
 glossaryDoc.appendChild(substituteBlock);

 // Set the structured document tag's "PlaceholderName" property to our building block's name to get
 // the structured document tag to display the contents of the building block in place of the original default text.
 tag.setPlaceholderName("My placeholder");

 Assert.assertEquals("Custom placeholder text.", tag.getText().trim());
 Assert.assertTrue(tag.isShowingPlaceholderText());

 // Edit the text of the structured document tag and hide the placeholder text.
 Run run = (Run) tag.getChild(NodeType.RUN, 0, true);
 run.setText("New text.");
 tag.isShowingPlaceholderText(false);

 Assert.assertEquals("New text.", tag.getText().trim());

 // Use the "Clear" method to clear this structured document tag's contents and display the placeholder again.
 tag.clear();

 Assert.assertTrue(tag.isShowingPlaceholderText());
 Assert.assertEquals("Custom placeholder text.", tag.getText().trim());
 
 

Throws:

java.lang.Exception

acceptStart

public int acceptStart(DocumentVisitor visitor)
                throws java.lang.Exception

Accepts a visitor for visiting the start of the StructuredDocumentTag.

Examples:

Shows how to print the node structure of every structured document tag in a document.

 
 public void structuredDocumentTagToText() throws Exception {
     Document doc = new Document(getMyDir() + "DocumentVisitor-compatible features.docx");
     StructuredDocumentTagNodePrinter visitor = new StructuredDocumentTagNodePrinter();

     // 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());
 }

 /// <summary>
 /// Traverses a node's non-binary tree of child nodes.
 /// Creates a map in the form of a string of all encountered StructuredDocumentTag nodes and their children.
 /// </summary>
 public static class StructuredDocumentTagNodePrinter extends DocumentVisitor {
     public StructuredDocumentTagNodePrinter() {
         mBuilder = new StringBuilder();
         mVisitorIsInsideStructuredDocumentTag = false;
     }

     /// <summary>
     /// Gets the plain text of the document that was accumulated by the visitor.
     /// </summary>
     public String getText() {
         return mBuilder.toString();
     }

     /// <summary>
     /// Called when a Run node is encountered in the document.
     /// </summary>
     public int visitRun(final Run run) {
         if (mVisitorIsInsideStructuredDocumentTag) {
             indentAndAppendLine("[Run] \"" + run.getText() + "\"");
         }

         return VisitorAction.CONTINUE;
     }

     /// <summary>
     /// Called when a StructuredDocumentTag node is encountered in the document.
     /// </summary>
     public int visitStructuredDocumentTagStart(final StructuredDocumentTag sdt) {
         indentAndAppendLine("[StructuredDocumentTag start] Title: " + sdt.getTitle());
         mDocTraversalDepth++;

         return VisitorAction.CONTINUE;
     }

     /// <summary>
     /// Called after all the child nodes of a StructuredDocumentTag node have been visited.
     /// </summary>
     public int visitStructuredDocumentTagEnd(final StructuredDocumentTag sdt) {
         mDocTraversalDepth--;
         indentAndAppendLine("[StructuredDocumentTag end]");

         return VisitorAction.CONTINUE;
     }

     /// <summary>
     /// Append a line to the StringBuilder and indent it depending on how deep the visitor is into the document tree.
     /// </summary>
     /// <param name="text"></param>
     private void indentAndAppendLine(final String text) {
         for (int i = 0; i < mDocTraversalDepth; i++) {
             mBuilder.append("|  ");
         }

         mBuilder.append(text + "\r\n");
     }

     private final boolean mVisitorIsInsideStructuredDocumentTag;
     private int mDocTraversalDepth;
     private final StringBuilder mBuilder;
 }
 
 

Specified by:

acceptStart in class CompositeNode

Parameters:

visitor - The document visitor.

Returns:

The action to be taken by the visitor. The returned value is one of VisitorAction constants.

Throws:

java.lang.Exception

acceptEnd

public int acceptEnd(DocumentVisitor visitor)
              throws java.lang.Exception

Accepts a visitor for visiting the end of the StructuredDocumentTag.

Examples:

Shows how to print the node structure of every structured document tag in a document.

 
 public void structuredDocumentTagToText() throws Exception {
     Document doc = new Document(getMyDir() + "DocumentVisitor-compatible features.docx");
     StructuredDocumentTagNodePrinter visitor = new StructuredDocumentTagNodePrinter();

     // 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());
 }

 /// <summary>
 /// Traverses a node's non-binary tree of child nodes.
 /// Creates a map in the form of a string of all encountered StructuredDocumentTag nodes and their children.
 /// </summary>
 public static class StructuredDocumentTagNodePrinter extends DocumentVisitor {
     public StructuredDocumentTagNodePrinter() {
         mBuilder = new StringBuilder();
         mVisitorIsInsideStructuredDocumentTag = false;
     }

     /// <summary>
     /// Gets the plain text of the document that was accumulated by the visitor.
     /// </summary>
     public String getText() {
         return mBuilder.toString();
     }

     /// <summary>
     /// Called when a Run node is encountered in the document.
     /// </summary>
     public int visitRun(final Run run) {
         if (mVisitorIsInsideStructuredDocumentTag) {
             indentAndAppendLine("[Run] \"" + run.getText() + "\"");
         }

         return VisitorAction.CONTINUE;
     }

     /// <summary>
     /// Called when a StructuredDocumentTag node is encountered in the document.
     /// </summary>
     public int visitStructuredDocumentTagStart(final StructuredDocumentTag sdt) {
         indentAndAppendLine("[StructuredDocumentTag start] Title: " + sdt.getTitle());
         mDocTraversalDepth++;

         return VisitorAction.CONTINUE;
     }

     /// <summary>
     /// Called after all the child nodes of a StructuredDocumentTag node have been visited.
     /// </summary>
     public int visitStructuredDocumentTagEnd(final StructuredDocumentTag sdt) {
         mDocTraversalDepth--;
         indentAndAppendLine("[StructuredDocumentTag end]");

         return VisitorAction.CONTINUE;
     }

     /// <summary>
     /// Append a line to the StringBuilder and indent it depending on how deep the visitor is into the document tree.
     /// </summary>
     /// <param name="text"></param>
     private void indentAndAppendLine(final String text) {
         for (int i = 0; i < mDocTraversalDepth; i++) {
             mBuilder.append("|  ");
         }

         mBuilder.append(text + "\r\n");
     }

     private final boolean mVisitorIsInsideStructuredDocumentTag;
     private int mDocTraversalDepth;
     private final StringBuilder mBuilder;
 }
 
 

Specified by:

acceptEnd in class CompositeNode

Parameters:

visitor - The document visitor.

Returns:

The action to be taken by the visitor. The returned value is one of VisitorAction constants.

Throws:

java.lang.Exception

isMultiSection

public boolean isMultiSection()

Description copied from interface: IStructuredDocumentTag

Returns true if this instance is a ranged (multi-section) structured document tag.

Examples:

Shows how to get structured document tag.

 
 Document doc = new Document(getMyDir() + "Structured document tags by id.docx");

 // Get the structured document tag by Id.
 IStructuredDocumentTag sdt = doc.getRange().getStructuredDocumentTags().getById(1160505028);
 System.out.println(sdt.isMultiSection());
 System.out.println(sdt.getTitle());

 // Get the structured document tag or ranged tag by Title.
 sdt = doc.getRange().getStructuredDocumentTags().getByTitle("Alias4");
 System.out.println(sdt.getId());
 
 

Specified by:

isMultiSection in interface IStructuredDocumentTag

Returns:

True if this instance is a ranged (multi-section) structured document tag.

getNode

public Node getNode()

Description copied from interface: IStructuredDocumentTag

Returns Node object that implements this interface.

Specified by:

getNode in interface IStructuredDocumentTag

Returns:

Node object that implements this interface.

getNodeType

public int getNodeType()

Returns NodeType.STRUCTURED_DOCUMENT_TAG.

Examples:

Shows how to work with styles for content control elements.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Below are two ways to apply a style from the document to a structured document tag.
 // 1 -  Apply a style object from the document's style collection:
 Style quoteStyle = doc.getStyles().getByStyleIdentifier(StyleIdentifier.QUOTE);
 StructuredDocumentTag sdtPlainText = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);
 sdtPlainText.setStyle(quoteStyle);

 // 2 -  Reference a style in the document by name:
 StructuredDocumentTag sdtRichText = new StructuredDocumentTag(doc, SdtType.RICH_TEXT, MarkupLevel.INLINE);
 sdtRichText.setStyleName("Quote");

 builder.insertNode(sdtPlainText);
 builder.insertNode(sdtRichText);

 Assert.assertEquals(NodeType.STRUCTURED_DOCUMENT_TAG, sdtPlainText.getNodeType());

 NodeCollection tags = doc.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true);

 for (StructuredDocumentTag sdt : (Iterable<StructuredDocumentTag>) tags) {
     Assert.assertEquals(StyleIdentifier.QUOTE, sdt.getStyle().getStyleIdentifier());
     Assert.assertEquals("Quote", sdt.getStyleName());
 }
 
 

Specified by:

getNodeType in class Node

Returns:

NodeType.STRUCTURED_DOCUMENT_TAG. The returned value is one of NodeType constants.

getPlaceholder

public BuildingBlock getPlaceholder()

Gets the BuildingBlock containing placeholder text which should be displayed when this SDT run contents are empty, the associated mapped XML element is empty as specified via the getXmlMapping() element or the isShowingPlaceholderText() / isShowingPlaceholderText(boolean) element is true.

Remarks:

Can be null, meaning that the placeholder is not applicable for this Sdt.

Examples:

Shows how to use a building block's contents as a custom placeholder text for a structured document tag.

 
 Document doc = new Document();

 // Insert a plain text structured document tag of the "PlainText" type, which will function as a text box.
 // The contents that it will display by default are a "Click here to enter text." prompt.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // We can get the tag to display the contents of a building block instead of the default text.
 // First, add a building block with contents to the glossary document.
 GlossaryDocument glossaryDoc = doc.getGlossaryDocument();

 BuildingBlock substituteBlock = new BuildingBlock(glossaryDoc);
 substituteBlock.setName("Custom Placeholder");
 substituteBlock.appendChild(new Section(glossaryDoc));
 substituteBlock.getFirstSection().appendChild(new Body(glossaryDoc));
 substituteBlock.getFirstSection().getBody().appendParagraph("Custom placeholder text.");

 glossaryDoc.appendChild(substituteBlock);

 // Then, use the structured document tag's "PlaceholderName" property to reference that building block by name.
 tag.setPlaceholderName("Custom Placeholder");

 // If "PlaceholderName" refers to an existing block in the parent document's glossary document,
 // we will be able to verify the building block via the "Placeholder" property.
 Assert.assertEquals(substituteBlock, tag.getPlaceholder());

 // Set the "IsShowingPlaceholderText" property to "true" to treat the
 // structured document tag's current contents as placeholder text.
 // This means that clicking on the text box in Microsoft Word will immediately highlight all the tag's contents.
 // Set the "IsShowingPlaceholderText" property to "false" to get the
 // structured document tag to treat its contents as text that a user has already entered.
 // Clicking on this text in Microsoft Word will place the blinking cursor at the clicked location.
 tag.isShowingPlaceholderText(isShowingPlaceholderText);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlaceholderBuildingBlock.docx");
 
 

Specified by:

getPlaceholder in interface IStructuredDocumentTag

Returns:

The BuildingBlock containing placeholder text which should be displayed when this SDT run contents are empty, the associated mapped XML element is empty as specified via the getXmlMapping() element or the isShowingPlaceholderText() / isShowingPlaceholderText(boolean) element is true.

getPlaceholderName

public java.lang.String getPlaceholderName()

Gets or sets Name of the BuildingBlock containing placeholder text.

Specified by:

getPlaceholderName in interface IStructuredDocumentTag

Returns:

The corresponding String value.

Throws:

java.lang.IllegalStateException - Throw if BuildingBlock with this name BuildingBlock.getName() / BuildingBlock.setName(java.lang.String) is not present in Document.getGlossaryDocument() / Document.setGlossaryDocument(com.aspose.words.GlossaryDocument).

Examples:

Shows how to use a building block's contents as a custom placeholder text for a structured document tag.

 
 Document doc = new Document();

 // Insert a plain text structured document tag of the "PlainText" type, which will function as a text box.
 // The contents that it will display by default are a "Click here to enter text." prompt.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // We can get the tag to display the contents of a building block instead of the default text.
 // First, add a building block with contents to the glossary document.
 GlossaryDocument glossaryDoc = doc.getGlossaryDocument();

 BuildingBlock substituteBlock = new BuildingBlock(glossaryDoc);
 substituteBlock.setName("Custom Placeholder");
 substituteBlock.appendChild(new Section(glossaryDoc));
 substituteBlock.getFirstSection().appendChild(new Body(glossaryDoc));
 substituteBlock.getFirstSection().getBody().appendParagraph("Custom placeholder text.");

 glossaryDoc.appendChild(substituteBlock);

 // Then, use the structured document tag's "PlaceholderName" property to reference that building block by name.
 tag.setPlaceholderName("Custom Placeholder");

 // If "PlaceholderName" refers to an existing block in the parent document's glossary document,
 // we will be able to verify the building block via the "Placeholder" property.
 Assert.assertEquals(substituteBlock, tag.getPlaceholder());

 // Set the "IsShowingPlaceholderText" property to "true" to treat the
 // structured document tag's current contents as placeholder text.
 // This means that clicking on the text box in Microsoft Word will immediately highlight all the tag's contents.
 // Set the "IsShowingPlaceholderText" property to "false" to get the
 // structured document tag to treat its contents as text that a user has already entered.
 // Clicking on this text in Microsoft Word will place the blinking cursor at the clicked location.
 tag.isShowingPlaceholderText(isShowingPlaceholderText);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlaceholderBuildingBlock.docx");
 
 

setPlaceholderName

public void setPlaceholderName(java.lang.String value)

Gets or sets Name of the BuildingBlock containing placeholder text.

Specified by:

setPlaceholderName in interface IStructuredDocumentTag

Parameters:

value - The corresponding String value.

Throws:

java.lang.IllegalStateException - Throw if BuildingBlock with this name BuildingBlock.getName() / BuildingBlock.setName(java.lang.String) is not present in Document.getGlossaryDocument() / Document.setGlossaryDocument(com.aspose.words.GlossaryDocument).

Examples:

Shows how to use a building block's contents as a custom placeholder text for a structured document tag.

 
 Document doc = new Document();

 // Insert a plain text structured document tag of the "PlainText" type, which will function as a text box.
 // The contents that it will display by default are a "Click here to enter text." prompt.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // We can get the tag to display the contents of a building block instead of the default text.
 // First, add a building block with contents to the glossary document.
 GlossaryDocument glossaryDoc = doc.getGlossaryDocument();

 BuildingBlock substituteBlock = new BuildingBlock(glossaryDoc);
 substituteBlock.setName("Custom Placeholder");
 substituteBlock.appendChild(new Section(glossaryDoc));
 substituteBlock.getFirstSection().appendChild(new Body(glossaryDoc));
 substituteBlock.getFirstSection().getBody().appendParagraph("Custom placeholder text.");

 glossaryDoc.appendChild(substituteBlock);

 // Then, use the structured document tag's "PlaceholderName" property to reference that building block by name.
 tag.setPlaceholderName("Custom Placeholder");

 // If "PlaceholderName" refers to an existing block in the parent document's glossary document,
 // we will be able to verify the building block via the "Placeholder" property.
 Assert.assertEquals(substituteBlock, tag.getPlaceholder());

 // Set the "IsShowingPlaceholderText" property to "true" to treat the
 // structured document tag's current contents as placeholder text.
 // This means that clicking on the text box in Microsoft Word will immediately highlight all the tag's contents.
 // Set the "IsShowingPlaceholderText" property to "false" to get the
 // structured document tag to treat its contents as text that a user has already entered.
 // Clicking on this text in Microsoft Word will place the blinking cursor at the clicked location.
 tag.isShowingPlaceholderText(isShowingPlaceholderText);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlaceholderBuildingBlock.docx");
 
 

getLevel

public int getLevel()

Gets the level at which this SDT occurs in the document tree.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

getLevel in interface IStructuredDocumentTag

Returns:

The level at which this SDT occurs in the document tree. The returned value is one of MarkupLevel constants.

getSdtType

public int getSdtType()

Gets type of this Structured document tag.

Examples:

Shows how to get the type of a structured document tag.

 
 Document doc = new Document(getMyDir() + "Structured document tags.docx");

 List<StructuredDocumentTag> tags = Arrays.stream(doc.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true).toArray())
         .filter(StructuredDocumentTag.class::isInstance)
         .map(StructuredDocumentTag.class::cast)
         .collect(Collectors.toList());

 Assert.assertEquals(SdtType.REPEATING_SECTION, tags.get(0).getSdtType());
 Assert.assertEquals(SdtType.REPEATING_SECTION_ITEM, tags.get(1).getSdtType());
 Assert.assertEquals(SdtType.RICH_TEXT, tags.get(2).getSdtType());
 
 

Specified by:

getSdtType in interface IStructuredDocumentTag

Returns:

Type of this Structured document tag. The returned value is one of SdtType constants.

getId

public int getId()

Specifies a unique read-only persistent numerical Id for this SDT.

Remarks:

Id attribute shall follow these rules:

• The document shall retain SDT ids only if the whole document is cloned Document.deepClone().
• During DocumentBase.importNode(com.aspose.words.Node, boolean) Id shall be retained if import does not cause conflicts with other SDT Ids in the target document.
• If multiple SDT nodes specify the same decimal number value for the Id attribute, then the first SDT in the document shall maintain this original Id, and all subsequent SDT nodes shall have new identifiers assigned to them when the document is loaded.
• During standalone SDT M:Aspose.Words.Markup.StructuredDocumentTag.Clone(System.Boolean,Aspose.Words.INodeCloningListener) operation new unique ID will be generated for the cloned SDT node.
• If Id is not specified in the source document, then the SDT node shall have a new unique identifier assigned to it when the document is loaded.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

getId in interface IStructuredDocumentTag

Returns:

The corresponding int value.

getLockContentControl

public boolean getLockContentControl()

When set to true, this property will prohibit a user from deleting this SDT.

Examples:

Shows how to apply editing restrictions to structured document tags.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Insert a plain text structured document tag, which acts as a text box that prompts the user to fill it in.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "LockContents" property to "true" to prohibit the user from editing this text box's contents.
 tag.setLockContents(true);
 builder.write("The contents of this structured document tag cannot be edited: ");
 builder.insertNode(tag);

 tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "LockContentControl" property to "true" to prohibit the user from
 // deleting this structured document tag manually in Microsoft Word.
 tag.setLockContentControl(true);

 builder.insertParagraph();
 builder.write("This structured document tag cannot be deleted but its contents can be edited: ");
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Lock.docx");
 
 

Specified by:

getLockContentControl in interface IStructuredDocumentTag

Returns:

The corresponding boolean value.

setLockContentControl

public void setLockContentControl(boolean value)

When set to true, this property will prohibit a user from deleting this SDT.

Examples:

Shows how to apply editing restrictions to structured document tags.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Insert a plain text structured document tag, which acts as a text box that prompts the user to fill it in.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "LockContents" property to "true" to prohibit the user from editing this text box's contents.
 tag.setLockContents(true);
 builder.write("The contents of this structured document tag cannot be edited: ");
 builder.insertNode(tag);

 tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "LockContentControl" property to "true" to prohibit the user from
 // deleting this structured document tag manually in Microsoft Word.
 tag.setLockContentControl(true);

 builder.insertParagraph();
 builder.write("This structured document tag cannot be deleted but its contents can be edited: ");
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Lock.docx");
 
 

Specified by:

setLockContentControl in interface IStructuredDocumentTag

Parameters:

value - The corresponding boolean value.

getLockContents

public boolean getLockContents()

When set to true, this property will prohibit a user from editing the contents of this SDT.

Examples:

Shows how to apply editing restrictions to structured document tags.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Insert a plain text structured document tag, which acts as a text box that prompts the user to fill it in.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "LockContents" property to "true" to prohibit the user from editing this text box's contents.
 tag.setLockContents(true);
 builder.write("The contents of this structured document tag cannot be edited: ");
 builder.insertNode(tag);

 tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "LockContentControl" property to "true" to prohibit the user from
 // deleting this structured document tag manually in Microsoft Word.
 tag.setLockContentControl(true);

 builder.insertParagraph();
 builder.write("This structured document tag cannot be deleted but its contents can be edited: ");
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Lock.docx");
 
 

Specified by:

getLockContents in interface IStructuredDocumentTag

Returns:

The corresponding boolean value.

setLockContents

public void setLockContents(boolean value)

When set to true, this property will prohibit a user from editing the contents of this SDT.

Examples:

Shows how to apply editing restrictions to structured document tags.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Insert a plain text structured document tag, which acts as a text box that prompts the user to fill it in.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "LockContents" property to "true" to prohibit the user from editing this text box's contents.
 tag.setLockContents(true);
 builder.write("The contents of this structured document tag cannot be edited: ");
 builder.insertNode(tag);

 tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "LockContentControl" property to "true" to prohibit the user from
 // deleting this structured document tag manually in Microsoft Word.
 tag.setLockContentControl(true);

 builder.insertParagraph();
 builder.write("This structured document tag cannot be deleted but its contents can be edited: ");
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Lock.docx");
 
 

Specified by:

setLockContents in interface IStructuredDocumentTag

Parameters:

value - The corresponding boolean value.

isShowingPlaceholderText

public boolean isShowingPlaceholderText()

Specifies whether the content of this SDT shall be interpreted to contain placeholder text (as opposed to regular text contents within the SDT).

if set to true, this state shall be resumed (showing placeholder text) upon opening this document.

Examples:

Shows how to use a building block's contents as a custom placeholder text for a structured document tag.

 
 Document doc = new Document();

 // Insert a plain text structured document tag of the "PlainText" type, which will function as a text box.
 // The contents that it will display by default are a "Click here to enter text." prompt.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // We can get the tag to display the contents of a building block instead of the default text.
 // First, add a building block with contents to the glossary document.
 GlossaryDocument glossaryDoc = doc.getGlossaryDocument();

 BuildingBlock substituteBlock = new BuildingBlock(glossaryDoc);
 substituteBlock.setName("Custom Placeholder");
 substituteBlock.appendChild(new Section(glossaryDoc));
 substituteBlock.getFirstSection().appendChild(new Body(glossaryDoc));
 substituteBlock.getFirstSection().getBody().appendParagraph("Custom placeholder text.");

 glossaryDoc.appendChild(substituteBlock);

 // Then, use the structured document tag's "PlaceholderName" property to reference that building block by name.
 tag.setPlaceholderName("Custom Placeholder");

 // If "PlaceholderName" refers to an existing block in the parent document's glossary document,
 // we will be able to verify the building block via the "Placeholder" property.
 Assert.assertEquals(substituteBlock, tag.getPlaceholder());

 // Set the "IsShowingPlaceholderText" property to "true" to treat the
 // structured document tag's current contents as placeholder text.
 // This means that clicking on the text box in Microsoft Word will immediately highlight all the tag's contents.
 // Set the "IsShowingPlaceholderText" property to "false" to get the
 // structured document tag to treat its contents as text that a user has already entered.
 // Clicking on this text in Microsoft Word will place the blinking cursor at the clicked location.
 tag.isShowingPlaceholderText(isShowingPlaceholderText);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlaceholderBuildingBlock.docx");
 
 

Specified by:

isShowingPlaceholderText in interface IStructuredDocumentTag

Returns:

The corresponding boolean value.

isShowingPlaceholderText

public void isShowingPlaceholderText(boolean value)

Specifies whether the content of this SDT shall be interpreted to contain placeholder text (as opposed to regular text contents within the SDT).

if set to true, this state shall be resumed (showing placeholder text) upon opening this document.

Examples:

Shows how to use a building block's contents as a custom placeholder text for a structured document tag.

 
 Document doc = new Document();

 // Insert a plain text structured document tag of the "PlainText" type, which will function as a text box.
 // The contents that it will display by default are a "Click here to enter text." prompt.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // We can get the tag to display the contents of a building block instead of the default text.
 // First, add a building block with contents to the glossary document.
 GlossaryDocument glossaryDoc = doc.getGlossaryDocument();

 BuildingBlock substituteBlock = new BuildingBlock(glossaryDoc);
 substituteBlock.setName("Custom Placeholder");
 substituteBlock.appendChild(new Section(glossaryDoc));
 substituteBlock.getFirstSection().appendChild(new Body(glossaryDoc));
 substituteBlock.getFirstSection().getBody().appendParagraph("Custom placeholder text.");

 glossaryDoc.appendChild(substituteBlock);

 // Then, use the structured document tag's "PlaceholderName" property to reference that building block by name.
 tag.setPlaceholderName("Custom Placeholder");

 // If "PlaceholderName" refers to an existing block in the parent document's glossary document,
 // we will be able to verify the building block via the "Placeholder" property.
 Assert.assertEquals(substituteBlock, tag.getPlaceholder());

 // Set the "IsShowingPlaceholderText" property to "true" to treat the
 // structured document tag's current contents as placeholder text.
 // This means that clicking on the text box in Microsoft Word will immediately highlight all the tag's contents.
 // Set the "IsShowingPlaceholderText" property to "false" to get the
 // structured document tag to treat its contents as text that a user has already entered.
 // Clicking on this text in Microsoft Word will place the blinking cursor at the clicked location.
 tag.isShowingPlaceholderText(isShowingPlaceholderText);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlaceholderBuildingBlock.docx");
 
 

Specified by:

isShowingPlaceholderText in interface IStructuredDocumentTag

Parameters:

value - The corresponding boolean value.

getTag

public java.lang.String getTag()

Specifies a tag associated with the current SDT node. Can not be null.

Remarks:

A tag is an arbitrary string which applications can associate with SDT in order to identify it without providing a visible friendly name.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

getTag in interface IStructuredDocumentTag

Returns:

The corresponding String value.

setTag

public void setTag(java.lang.String value)

Specifies a tag associated with the current SDT node. Can not be null.

Remarks:

A tag is an arbitrary string which applications can associate with SDT in order to identify it without providing a visible friendly name.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

setTag in interface IStructuredDocumentTag

Parameters:

value - The corresponding String value.

getContentsFont

public Font getContentsFont()

Font formatting that will be applied to text entered into SDT.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Returns:

The corresponding Font value.

getEndCharacterFont

public Font getEndCharacterFont()

Font formatting that will be applied to the last character of text entered into SDT.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Returns:

The corresponding Font value.

isTemporary

public boolean isTemporary()

Specifies whether this SDT shall be removed from the WordProcessingML document when its contents are modified.

Examples:

Shows how to make single-use controls.

 
 Document doc = new Document();

 // Insert a plain text structured document tag,
 // which will act as a plain text form that the user may enter text into.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "IsTemporary" property to "true" to make the structured document tag disappear and
 // assimilate its contents into the document after the user edits it once in Microsoft Word.
 // Set the "IsTemporary" property to "false" to allow the user to edit the contents
 // of the structured document tag any number of times.
 tag.isTemporary(isTemporary);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.write("Please enter text: ");
 builder.insertNode(tag);

 // Insert another structured document tag in the form of a check box and set its default state to "checked".
 tag = new StructuredDocumentTag(doc, SdtType.CHECKBOX, MarkupLevel.INLINE);
 tag.setChecked(true);

 // Set the "IsTemporary" property to "true" to make the check box become a symbol
 // once the user clicks on it in Microsoft Word.
 // Set the "IsTemporary" property to "false" to allow the user to click on the check box any number of times.
 tag.isTemporary(isTemporary);

 builder.write("\nPlease click the check box: ");
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.IsTemporary.docx");
 
 

Returns:

The corresponding boolean value.

isTemporary

public void isTemporary(boolean value)

Specifies whether this SDT shall be removed from the WordProcessingML document when its contents are modified.

Examples:

Shows how to make single-use controls.

 
 Document doc = new Document();

 // Insert a plain text structured document tag,
 // which will act as a plain text form that the user may enter text into.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the "IsTemporary" property to "true" to make the structured document tag disappear and
 // assimilate its contents into the document after the user edits it once in Microsoft Word.
 // Set the "IsTemporary" property to "false" to allow the user to edit the contents
 // of the structured document tag any number of times.
 tag.isTemporary(isTemporary);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.write("Please enter text: ");
 builder.insertNode(tag);

 // Insert another structured document tag in the form of a check box and set its default state to "checked".
 tag = new StructuredDocumentTag(doc, SdtType.CHECKBOX, MarkupLevel.INLINE);
 tag.setChecked(true);

 // Set the "IsTemporary" property to "true" to make the check box become a symbol
 // once the user clicks on it in Microsoft Word.
 // Set the "IsTemporary" property to "false" to allow the user to click on the check box any number of times.
 tag.isTemporary(isTemporary);

 builder.write("\nPlease click the check box: ");
 builder.insertNode(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.IsTemporary.docx");
 
 

Parameters:

value - The corresponding boolean value.

getTitle

public java.lang.String getTitle()

Specifies the friendly name associated with this SDT. Can not be null.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

getTitle in interface IStructuredDocumentTag

Returns:

The corresponding String value.

setTitle

public void setTitle(java.lang.String value)

Specifies the friendly name associated with this SDT. Can not be null.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

setTitle in interface IStructuredDocumentTag

Parameters:

value - The corresponding String value.

getListItems

public SdtListItemCollection getListItems()

Gets SdtListItemCollection associated with this SDT.

Remarks:

Accessing this property will only work for SdtType.COMBO_BOX or SdtType.DROP_DOWN_LIST SDT types.

For all other SDT types exception will occur.

Examples:

Shows how to work with drop down-list structured document tags.

 
 Document doc = new Document();
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.DROP_DOWN_LIST, MarkupLevel.BLOCK);
 doc.getFirstSection().getBody().appendChild(tag);

 // A drop-down list structured document tag is a form that allows the user to
 // select an option from a list by left-clicking and opening the form in Microsoft Word.
 // The "ListItems" property contains all list items, and each list item is an "SdtListItem".
 SdtListItemCollection listItems = tag.getListItems();
 listItems.add(new SdtListItem("Value 1"));

 Assert.assertEquals(listItems.get(0).getDisplayText(), listItems.get(0).getValue());

 // Add 3 more list items. Initialize these items using a different constructor to the first item
 // to display strings that are different from their values.
 listItems.add(new SdtListItem("Item 2", "Value 2"));
 listItems.add(new SdtListItem("Item 3", "Value 3"));
 listItems.add(new SdtListItem("Item 4", "Value 4"));

 Assert.assertEquals(4, listItems.getCount());

 // The drop-down list is displaying the first item. Assign a different list item to the "SelectedValue" to display it.
 listItems.setSelectedValue(listItems.get(3));

 Assert.assertEquals(listItems.getSelectedValue().getValue(), "Value 4");

 // Enumerate over the collection and print each element.
 Iterator<SdtListItem> enumerator = listItems.iterator();
 while (enumerator.hasNext()) {
     SdtListItem sdtListItem = enumerator.next();
     System.out.println(MessageFormat.format("List item: {0}, value: {1}", sdtListItem.getDisplayText(), sdtListItem.getValue()));
 }

 // Remove the last list item.
 listItems.removeAt(3);

 Assert.assertEquals(3, listItems.getCount());

 // Since our drop-down control is set to display the removed item by default, give it an item to display which exists.
 listItems.setSelectedValue(listItems.get(1));

 doc.save(getArtifactsDir() + "StructuredDocumentTag.ListItemCollection.docx");

 // Use the "Clear" method to empty the entire drop-down item collection at once.
 listItems.clear();

 Assert.assertEquals(0, listItems.getCount());
 
 

Returns:

SdtListItemCollection associated with this SDT.

getChecked

public boolean getChecked()

Gets/Sets current state of the Checkbox SDT. Default value for this property is false.

Remarks:

Accessing this property will only work for SdtType.CHECKBOX SDT types.

For all other SDT types exception will occur.

Examples:

Show how to create a structured document tag in the form of a check box.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 StructuredDocumentTag sdtCheckBox = new StructuredDocumentTag(doc, SdtType.CHECKBOX, MarkupLevel.INLINE);
 sdtCheckBox.setChecked(true);
 sdtCheckBox.setCheckedSymbol(0x00A9, "Times New Roman");
 sdtCheckBox.setUncheckedSymbol(0x00AE, "Times New Roman");

 builder.insertNode(sdtCheckBox);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.CheckBox.docx");
 
 

Returns:

The corresponding boolean value.

setChecked

public void setChecked(boolean value)
                throws java.lang.Exception

Gets/Sets current state of the Checkbox SDT. Default value for this property is false.

Remarks:

Accessing this property will only work for SdtType.CHECKBOX SDT types.

For all other SDT types exception will occur.

Examples:

Show how to create a structured document tag in the form of a check box.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 StructuredDocumentTag sdtCheckBox = new StructuredDocumentTag(doc, SdtType.CHECKBOX, MarkupLevel.INLINE);
 sdtCheckBox.setChecked(true);
 sdtCheckBox.setCheckedSymbol(0x00A9, "Times New Roman");
 sdtCheckBox.setUncheckedSymbol(0x00AE, "Times New Roman");

 builder.insertNode(sdtCheckBox);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.CheckBox.docx");
 
 

Parameters:

value - The corresponding boolean value.

Throws:

java.lang.Exception

getAppearance

public int getAppearance()

Gets/sets the appearance of a structured document tag.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

getAppearance in interface IStructuredDocumentTag

Returns:

The corresponding int value. The returned value is one of SdtAppearance constants.

setAppearance

public void setAppearance(int value)

Gets/sets the appearance of a structured document tag.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

setAppearance in interface IStructuredDocumentTag

Parameters:

value - The corresponding int value. The value must be one of SdtAppearance constants.

getDateDisplayLocale

public int getDateDisplayLocale()

Allows to set/get the language format for the date displayed in this SDT.

Remarks:

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Returns:

The corresponding int value.

setDateDisplayLocale

public void setDateDisplayLocale(int value)

Allows to set/get the language format for the date displayed in this SDT.

Remarks:

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Parameters:

value - The corresponding int value.

getDateDisplayFormat

public java.lang.String getDateDisplayFormat()

String that represents the format in which dates are displayed.

Remarks:

Can not be null.

The dates for English (U.S.) is "mm/dd/yyyy"

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Returns:

The corresponding String value.

setDateDisplayFormat

public void setDateDisplayFormat(java.lang.String value)

String that represents the format in which dates are displayed.

Remarks:

Can not be null.

The dates for English (U.S.) is "mm/dd/yyyy"

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Parameters:

value - The corresponding String value.

getFullDate

public java.util.Date getFullDate()

Specifies the full date and time last entered into this SDT.

Remarks:

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Returns:

The corresponding Date value.

setFullDate

public void setFullDate(java.util.Date value)

Specifies the full date and time last entered into this SDT.

Remarks:

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Parameters:

value - The corresponding Date value.

getDateStorageFormat

public int getDateStorageFormat()

Gets/sets format in which the date for a date SDT is stored when the SDT is bound to an XML node in the document's data store. Default value is SdtDateStorageFormat.DATE_TIME

Remarks:

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Returns:

The corresponding int value. The returned value is one of SdtDateStorageFormat constants.

setDateStorageFormat

public void setDateStorageFormat(int value)

Gets/sets format in which the date for a date SDT is stored when the SDT is bound to an XML node in the document's data store. Default value is SdtDateStorageFormat.DATE_TIME

Remarks:

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Parameters:

value - The corresponding int value. The value must be one of SdtDateStorageFormat constants.

getCalendarType

public int getCalendarType()

Specifies the type of calendar for this SDT. Default is SdtCalendarType.DEFAULT

Remarks:

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Returns:

The corresponding int value. The returned value is one of SdtCalendarType constants.

setCalendarType

public void setCalendarType(int value)

Specifies the type of calendar for this SDT. Default is SdtCalendarType.DEFAULT

Remarks:

Accessing this property will only work for SdtType.DATE SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to prompt the user to enter a date with a structured document tag.

 
 Document doc = new Document();

 // Insert a structured document tag that prompts the user to enter a date.
 // In Microsoft Word, this element is known as a "Date picker content control".
 // When we click on the arrow on the right end of this tag in Microsoft Word,
 // we will see a pop up in the form of a clickable calendar.
 // We can use that popup to select a date that the tag will display.
 StructuredDocumentTag sdtDate = new StructuredDocumentTag(doc, SdtType.DATE, MarkupLevel.INLINE);

 // Display the date, according to the Saudi Arabian Arabic locale.
 sdtDate.setDateDisplayLocale(1025);

 // Set the format with which to display the date.
 sdtDate.setDateDisplayFormat("dd MMMM, yyyy");
 sdtDate.setDateStorageFormat(SdtDateStorageFormat.DATE_TIME);

 // Display the date according to the Hijri calendar.
 sdtDate.setCalendarType(SdtCalendarType.HIJRI);

 // Before the user chooses a date in Microsoft Word, the tag will display the text "Click here to enter a date.".
 // According to the tag's calendar, set the "FullDate" property to get the tag to display a default date.
 Calendar cal = Calendar.getInstance();
 cal.set(1440, 10, 20);
 sdtDate.setFullDate(cal.getTime());

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(sdtDate);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.Date.docx");
 
 

Parameters:

value - The corresponding int value. The value must be one of SdtCalendarType constants.

getBuildingBlockGallery

public java.lang.String getBuildingBlockGallery()

Specifies type of building block for this SDT. Can not be null.

Remarks:

Accessing this property will only work for SdtType.BUILDING_BLOCK_GALLERY and SdtType.DOC_PART_OBJ SDT types. It is read-only for SDT of the document part type.

For all other SDT types exception will occur.

Examples:

Shows how to insert a structured document tag as a building block, and set its category and gallery.

 
 Document doc = new Document();

 StructuredDocumentTag buildingBlockSdt =
         new StructuredDocumentTag(doc, SdtType.BUILDING_BLOCK_GALLERY, MarkupLevel.BLOCK);
 buildingBlockSdt.setBuildingBlockCategory("Built-in");
 buildingBlockSdt.setBuildingBlockGallery("Table of Contents");

 doc.getFirstSection().getBody().appendChild(buildingBlockSdt);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.BuildingBlockCategories.docx");
 
 

Returns:

The corresponding String value.

setBuildingBlockGallery

public void setBuildingBlockGallery(java.lang.String value)

Specifies type of building block for this SDT. Can not be null.

Remarks:

Accessing this property will only work for SdtType.BUILDING_BLOCK_GALLERY and SdtType.DOC_PART_OBJ SDT types. It is read-only for SDT of the document part type.

For all other SDT types exception will occur.

Examples:

Shows how to insert a structured document tag as a building block, and set its category and gallery.

 
 Document doc = new Document();

 StructuredDocumentTag buildingBlockSdt =
         new StructuredDocumentTag(doc, SdtType.BUILDING_BLOCK_GALLERY, MarkupLevel.BLOCK);
 buildingBlockSdt.setBuildingBlockCategory("Built-in");
 buildingBlockSdt.setBuildingBlockGallery("Table of Contents");

 doc.getFirstSection().getBody().appendChild(buildingBlockSdt);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.BuildingBlockCategories.docx");
 
 

Parameters:

value - The corresponding String value.

getBuildingBlockCategory

public java.lang.String getBuildingBlockCategory()

Specifies category of building block for this SDT node. Can not be null.

Remarks:

Accessing this property will only work for SdtType.BUILDING_BLOCK_GALLERY and SdtType.DOC_PART_OBJ SDT types. It is read-only for SDT of the document part type.

For all other SDT types exception will occur.

Examples:

Shows how to insert a structured document tag as a building block, and set its category and gallery.

 
 Document doc = new Document();

 StructuredDocumentTag buildingBlockSdt =
         new StructuredDocumentTag(doc, SdtType.BUILDING_BLOCK_GALLERY, MarkupLevel.BLOCK);
 buildingBlockSdt.setBuildingBlockCategory("Built-in");
 buildingBlockSdt.setBuildingBlockGallery("Table of Contents");

 doc.getFirstSection().getBody().appendChild(buildingBlockSdt);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.BuildingBlockCategories.docx");
 
 

Returns:

The corresponding String value.

setBuildingBlockCategory

public void setBuildingBlockCategory(java.lang.String value)

Specifies category of building block for this SDT node. Can not be null.

Remarks:

Accessing this property will only work for SdtType.BUILDING_BLOCK_GALLERY and SdtType.DOC_PART_OBJ SDT types. It is read-only for SDT of the document part type.

For all other SDT types exception will occur.

Examples:

Shows how to insert a structured document tag as a building block, and set its category and gallery.

 
 Document doc = new Document();

 StructuredDocumentTag buildingBlockSdt =
         new StructuredDocumentTag(doc, SdtType.BUILDING_BLOCK_GALLERY, MarkupLevel.BLOCK);
 buildingBlockSdt.setBuildingBlockCategory("Built-in");
 buildingBlockSdt.setBuildingBlockGallery("Table of Contents");

 doc.getFirstSection().getBody().appendChild(buildingBlockSdt);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.BuildingBlockCategories.docx");
 
 

Parameters:

value - The corresponding String value.

getMultiline

public boolean getMultiline()

Specifies whether this SDT allows multiple lines of text.

Remarks:

Accessing this property will only work for SdtType.RICH_TEXT and SdtType.PLAIN_TEXT SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Returns:

The corresponding boolean value.

setMultiline

public void setMultiline(boolean value)

Specifies whether this SDT allows multiple lines of text.

Remarks:

Accessing this property will only work for SdtType.RICH_TEXT and SdtType.PLAIN_TEXT SDT type.

For all other SDT types exception will occur.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Parameters:

value - The corresponding boolean value.

getColor

public java.awt.Color getColor()

Gets the color of the structured document tag.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

getColor in interface IStructuredDocumentTag

Returns:

The color of the structured document tag.

setColor

public void setColor(java.awt.Color value)

Sets the color of the structured document tag.

Examples:

Shows how to create a structured document tag in a plain text box and modify its appearance.

 
 Document doc = new Document();

 // Create a structured document tag that will contain plain text.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);

 // Set the title and color of the frame that appears when you mouse over the structured document tag in Microsoft Word.
 tag.setTitle("My plain text");
 tag.setColor(Color.MAGENTA);

 // Set a tag for this structured document tag, which is obtainable
 // as an XML element named "tag", with the string below in its "@val" attribute.
 tag.setTag("MyPlainTextSDT");

 // Every structured document tag has a random unique ID.
 Assert.assertTrue(tag.getId() > 0);

 // Set the font for the text inside the structured document tag.
 tag.getContentsFont().setName("Arial");

 // Set the font for the text at the end of the structured document tag.
 // Any text that we type in the document body after moving out of the tag with arrow keys will use this font.
 tag.getEndCharacterFont().setName("Arial Black");

 // By default, this is false and pressing enter while inside a structured document tag does nothing.
 // When set to true, our structured document tag can have multiple lines.

 // Set the "Multiline" property to "false" to only allow the contents
 // of this structured document tag to span a single line.
 // Set the "Multiline" property to "true" to allow the tag to contain multiple lines of content.
 tag.setMultiline(true);

 // Set the "Appearance" property to "SdtAppearance.Tags" to show tags around content.
 // By default structured document tag shows as BoundingBox.
 tag.setAppearance(SdtAppearance.TAGS);

 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertNode(tag);

 // Insert a clone of our structured document tag in a new paragraph.
 StructuredDocumentTag tagClone = (StructuredDocumentTag) tag.deepClone(true);
 builder.insertParagraph();
 builder.insertNode(tagClone);

 // Use the "RemoveSelfOnly" method to remove a structured document tag, while keeping its contents in the document.
 tagClone.removeSelfOnly();

 doc.save(getArtifactsDir() + "StructuredDocumentTag.PlainText.docx");
 
 

Specified by:

setColor in interface IStructuredDocumentTag

Parameters:

value - The color of the structured document tag.

getStyle

public Style getStyle()

Gets the Style of the structured document tag.

Remarks:

Only StyleType.CHARACTER style or StyleType.PARAGRAPH style with linked character style can be set.

Examples:

Shows how to work with styles for content control elements.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Below are two ways to apply a style from the document to a structured document tag.
 // 1 -  Apply a style object from the document's style collection:
 Style quoteStyle = doc.getStyles().getByStyleIdentifier(StyleIdentifier.QUOTE);
 StructuredDocumentTag sdtPlainText = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);
 sdtPlainText.setStyle(quoteStyle);

 // 2 -  Reference a style in the document by name:
 StructuredDocumentTag sdtRichText = new StructuredDocumentTag(doc, SdtType.RICH_TEXT, MarkupLevel.INLINE);
 sdtRichText.setStyleName("Quote");

 builder.insertNode(sdtPlainText);
 builder.insertNode(sdtRichText);

 Assert.assertEquals(NodeType.STRUCTURED_DOCUMENT_TAG, sdtPlainText.getNodeType());

 NodeCollection tags = doc.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true);

 for (StructuredDocumentTag sdt : (Iterable<StructuredDocumentTag>) tags) {
     Assert.assertEquals(StyleIdentifier.QUOTE, sdt.getStyle().getStyleIdentifier());
     Assert.assertEquals("Quote", sdt.getStyleName());
 }
 
 

Returns:

The Style of the structured document tag.

setStyle

public void setStyle(Style value)

Sets the Style of the structured document tag.

Remarks:

Only StyleType.CHARACTER style or StyleType.PARAGRAPH style with linked character style can be set.

Examples:

Shows how to work with styles for content control elements.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Below are two ways to apply a style from the document to a structured document tag.
 // 1 -  Apply a style object from the document's style collection:
 Style quoteStyle = doc.getStyles().getByStyleIdentifier(StyleIdentifier.QUOTE);
 StructuredDocumentTag sdtPlainText = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);
 sdtPlainText.setStyle(quoteStyle);

 // 2 -  Reference a style in the document by name:
 StructuredDocumentTag sdtRichText = new StructuredDocumentTag(doc, SdtType.RICH_TEXT, MarkupLevel.INLINE);
 sdtRichText.setStyleName("Quote");

 builder.insertNode(sdtPlainText);
 builder.insertNode(sdtRichText);

 Assert.assertEquals(NodeType.STRUCTURED_DOCUMENT_TAG, sdtPlainText.getNodeType());

 NodeCollection tags = doc.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true);

 for (StructuredDocumentTag sdt : (Iterable<StructuredDocumentTag>) tags) {
     Assert.assertEquals(StyleIdentifier.QUOTE, sdt.getStyle().getStyleIdentifier());
     Assert.assertEquals("Quote", sdt.getStyleName());
 }
 
 

Parameters:

value - The Style of the structured document tag.

getStyleName

public java.lang.String getStyleName()

Gets the name of the style applied to the structured document tag.

Examples:

Shows how to work with styles for content control elements.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Below are two ways to apply a style from the document to a structured document tag.
 // 1 -  Apply a style object from the document's style collection:
 Style quoteStyle = doc.getStyles().getByStyleIdentifier(StyleIdentifier.QUOTE);
 StructuredDocumentTag sdtPlainText = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);
 sdtPlainText.setStyle(quoteStyle);

 // 2 -  Reference a style in the document by name:
 StructuredDocumentTag sdtRichText = new StructuredDocumentTag(doc, SdtType.RICH_TEXT, MarkupLevel.INLINE);
 sdtRichText.setStyleName("Quote");

 builder.insertNode(sdtPlainText);
 builder.insertNode(sdtRichText);

 Assert.assertEquals(NodeType.STRUCTURED_DOCUMENT_TAG, sdtPlainText.getNodeType());

 NodeCollection tags = doc.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true);

 for (StructuredDocumentTag sdt : (Iterable<StructuredDocumentTag>) tags) {
     Assert.assertEquals(StyleIdentifier.QUOTE, sdt.getStyle().getStyleIdentifier());
     Assert.assertEquals("Quote", sdt.getStyleName());
 }
 
 

Returns:

The name of the style applied to the structured document tag.

setStyleName

public void setStyleName(java.lang.String value)

Sets the name of the style applied to the structured document tag.

Examples:

Shows how to work with styles for content control elements.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Below are two ways to apply a style from the document to a structured document tag.
 // 1 -  Apply a style object from the document's style collection:
 Style quoteStyle = doc.getStyles().getByStyleIdentifier(StyleIdentifier.QUOTE);
 StructuredDocumentTag sdtPlainText = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);
 sdtPlainText.setStyle(quoteStyle);

 // 2 -  Reference a style in the document by name:
 StructuredDocumentTag sdtRichText = new StructuredDocumentTag(doc, SdtType.RICH_TEXT, MarkupLevel.INLINE);
 sdtRichText.setStyleName("Quote");

 builder.insertNode(sdtPlainText);
 builder.insertNode(sdtRichText);

 Assert.assertEquals(NodeType.STRUCTURED_DOCUMENT_TAG, sdtPlainText.getNodeType());

 NodeCollection tags = doc.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true);

 for (StructuredDocumentTag sdt : (Iterable<StructuredDocumentTag>) tags) {
     Assert.assertEquals(StyleIdentifier.QUOTE, sdt.getStyle().getStyleIdentifier());
     Assert.assertEquals("Quote", sdt.getStyleName());
 }
 
 

Parameters:

value - The name of the style applied to the structured document tag.

getXmlMapping

public XmlMapping getXmlMapping()

Gets an object that represents the mapping of this structured document tag to XML data in a custom XML part of the current document.

Remarks:

You can use the XmlMapping.setMapping(com.aspose.words.CustomXmlPart, java.lang.String, java.lang.String) method of this object to map a structured document tag to XML data.

Examples:

Shows how to create a structured document tag with custom XML data.

 
 Document doc = new Document();

 // Construct an XML part that contains data and add it to the document's collection.
 // If we enable the "Developer" tab in Microsoft Word,
 // we can find elements from this collection in the "XML Mapping Pane", along with a few default elements.
 String xmlPartId = UUID.randomUUID().toString();
 String xmlPartContent = "<root><text>Hello, World!</text></root>";
 CustomXmlPart xmlPart = doc.getCustomXmlParts().add(xmlPartId, xmlPartContent);

 Assert.assertEquals(xmlPart.getData(), xmlPartContent.getBytes());
 Assert.assertEquals(xmlPart.getId(), xmlPartId);

 // Below are two ways to refer to XML parts.
 // 1 -  By an index in the custom XML part collection:
 Assert.assertEquals(xmlPart, doc.getCustomXmlParts().get(0));

 // 2 -  By GUID:
 Assert.assertEquals(xmlPart, doc.getCustomXmlParts().getById(xmlPartId));

 // Add an XML schema association.
 xmlPart.getSchemas().add("http://www.w3.org/2001/XMLSchema");

 // Clone a part, and then insert it into the collection.
 CustomXmlPart xmlPartClone = xmlPart.deepClone();
 xmlPartClone.setId(UUID.randomUUID().toString());
 doc.getCustomXmlParts().add(xmlPartClone);

 Assert.assertEquals(doc.getCustomXmlParts().getCount(), 2);

 // Iterate through the collection and print the contents of each part.
 Iterator<CustomXmlPart> enumerator = doc.getCustomXmlParts().iterator();
 int index = 0;
 while (enumerator.hasNext()) {
     CustomXmlPart customXmlPart = enumerator.next();
     System.out.println(MessageFormat.format("XML part index {0}, ID: {1}", index, customXmlPart.getId()));
     System.out.println(MessageFormat.format("\tContent: {0}", customXmlPart.getData()));
     index++;
 }

 // Use the "RemoveAt" method to remove the cloned part by index.
 doc.getCustomXmlParts().removeAt(1);

 Assert.assertEquals(doc.getCustomXmlParts().getCount(), 1);

 // Clone the XML parts collection, and then use the "Clear" method to remove all its elements at once.
 CustomXmlPartCollection customXmlParts = doc.getCustomXmlParts().deepClone();
 customXmlParts.clear();

 // Create a structured document tag that will display our part's contents and insert it into the document body.
 StructuredDocumentTag tag = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);
 tag.getXmlMapping().setMapping(xmlPart, "/root[1]/text[1]", "");

 doc.getFirstSection().getBody().appendChild(tag);

 doc.save(getArtifactsDir() + "StructuredDocumentTag.CustomXml.docx");
 
 

Specified by:

getXmlMapping in interface IStructuredDocumentTag

Returns:

An object that represents the mapping of this structured document tag to XML data in a custom XML part of the current document.

getWordOpenXML

public java.lang.String getWordOpenXML()
                                throws java.lang.Exception

Gets a string that represents the XML contained within the node in the SaveFormat.FLAT_OPC format.

Examples:

Shows how to get XML contained within the node in the FlatOpc format.

 
 Document doc = new Document(getMyDir() + "Structured document tags.docx");

 List<StructuredDocumentTag> tags = Arrays.stream(doc.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true).toArray())
         .filter(StructuredDocumentTag.class::isInstance)
         .map(StructuredDocumentTag.class::cast)
         .collect(Collectors.toList());

 Assert.assertTrue(tags.get(0).getWordOpenXML()
         .contains(
                 "<pkg:part pkg:name=\"/docProps/app.xml\" pkg:contentType=\"application/vnd.openxmlformats-officedocument.extended-properties+xml\">"));
 
 

Specified by:

getWordOpenXML in interface IStructuredDocumentTag

Returns:

A string that represents the XML contained within the node in the SaveFormat.FLAT_OPC format.

Throws:

java.lang.Exception

getWordOpenXMLMinimal

public java.lang.String getWordOpenXMLMinimal()
                                       throws java.lang.Exception

Gets a string that represents the XML contained within the node in the SaveFormat.FLAT_OPC format. Unlike the getWordOpenXML() property, this method generates a stripped-down document that excludes any non-content-related parts.

Examples:

Shows how to work with styles for content control elements.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Below are two ways to apply a style from the document to a structured document tag.
 // 1 -  Apply a style object from the document's style collection:
 Style quoteStyle = doc.getStyles().getByStyleIdentifier(StyleIdentifier.QUOTE);
 StructuredDocumentTag sdtPlainText = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.INLINE);
 sdtPlainText.setStyle(quoteStyle);

 // 2 -  Reference a style in the document by name:
 StructuredDocumentTag sdtRichText = new StructuredDocumentTag(doc, SdtType.RICH_TEXT, MarkupLevel.INLINE);
 sdtRichText.setStyleName("Quote");

 builder.insertNode(sdtPlainText);
 builder.insertNode(sdtRichText);

 Assert.assertEquals(NodeType.STRUCTURED_DOCUMENT_TAG, sdtPlainText.getNodeType());

 NodeCollection tags = doc.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true);

 for (StructuredDocumentTag sdt : (Iterable<StructuredDocumentTag>) tags) {
     Assert.assertEquals(StyleIdentifier.QUOTE, sdt.getStyle().getStyleIdentifier());
     Assert.assertEquals("Quote", sdt.getStyleName());
 }
 
 

Returns:

A string that represents the XML contained within the node in the SaveFormat.FLAT_OPC format.

Throws:

java.lang.Exception

getLevel_IMarkupNode

public int getLevel_IMarkupNode()

removeMoveRevisions

public void removeMoveRevisions()

getDirectRunAttr

public java.lang.Object getDirectRunAttr(int key)

getDirectRunAttr

public java.lang.Object getDirectRunAttr(int key,
                                         int revisionsView)

fetchInheritedRunAttr

public java.lang.Object fetchInheritedRunAttr(int key)

setRunAttr

public void setRunAttr(int key,
                       java.lang.Object value)

removeRunAttr

public void removeRunAttr(int key)

clearRunAttrs

public void clearRunAttrs()