java.lang.Object
Node
Inline
SpecialChar
com.aspose.words.FieldChar
- All Implemented Interfaces:
- java.lang.Cloneable
- Direct Known Subclasses:
- FieldEnd, FieldSeparator, FieldStart
public abstract class FieldChar
- extends SpecialChar
Base class for nodes that represent field characters in a document.
A complete field in a Microsoft Word document is a complex structure consisting of
a field start character, field code, field separator character, field result
and field end character. Some fields only have field start, field code and field end.
To easily insert a new field into a document, use the DocumentBuilder.insertField(java.lang.String)
method.
Example:
Shows how to find the type of field that is represented by a node which is derived from FieldChar.
FieldChar fieldStart = (FieldChar) doc.getChild(NodeType.FIELD_START, 0, true);
int type = fieldStart.getFieldType();
- See Also:
- FieldStart, FieldSeparator, FieldEnd
Property Getters/Setters Summary |
DocumentBase | getDocument() | → inherited from Node |
|
Gets the document to which this node belongs.
|
int | getFieldType() | |
|
Returns the type of the field.
The value of the property is FieldType integer constant. |
Font | getFont() | → inherited from Inline |
|
Provides access to the font formatting of this object.
|
boolean | isComposite() | → inherited from Node |
|
Returns true if this node can contain other nodes.
|
boolean | isDeleteRevision() | → inherited from Inline |
|
Returns true if this object was deleted in Microsoft Word while change tracking was enabled.
|
boolean | isDirty() | |
void | isDirty(boolean value) | |
|
Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications
made to the document.
|
boolean | isFormatRevision() | → inherited from Inline |
|
Returns true if formatting of the object was changed in Microsoft Word while change tracking was enabled.
|
boolean | isInsertRevision() | → inherited from Inline |
|
Returns true if this object was inserted in Microsoft Word while change tracking was enabled.
|
boolean | isLocked() | |
void | isLocked(boolean value) | |
|
Gets or sets whether the parent field is locked (should not recalculate its result).
|
boolean | isMoveFromRevision() | → inherited from Inline |
|
Returns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled.
|
boolean | isMoveToRevision() | → inherited from Inline |
|
Returns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled.
|
Node | getNextSibling() | → inherited from Node |
|
Gets the node immediately following this node.
|
int | getNodeType() | → inherited from SpecialChar |
|
Returns NodeType.SpecialChar.
The value of the property is NodeType integer constant. |
CompositeNode | getParentNode() | → inherited from Node |
|
Gets the immediate parent of this node.
|
Paragraph | getParentParagraph() | → inherited from Inline |
|
Retrieves the parent Paragraph of this node.
|
Node | getPreviousSibling() | → inherited from Node |
|
Gets the node immediately preceding this node.
|
Range | getRange() | → inherited from Node |
|
Returns a Range object that represents the portion of a document that is contained in this node.
|
Property Getters/Setters Detail |
-
Gets the document to which this node belongs.
The node always belongs to a document even if it has just been created
and not yet added to the tree, or if it has been removed from the tree.
Example:
Shows that when you create any node, it requires a document that will own the node.
// Open a file from disk.
Document doc = new Document();
// Creating a new node of any type requires a document passed into the constructor.
Paragraph para = new Paragraph(doc);
// The new paragraph node does not yet have a parent.
System.out.println("Paragraph has no parent node: " + (para.getParentNode() == null));
// But the paragraph node knows its document.
System.out.println("Both nodes' documents are the same: " + (para.getDocument() == doc));
// The fact that a node always belongs to a document allows us to access and modify
// properties that reference the document-wide data such as styles or lists.
para.getParagraphFormat().setStyleName("Heading 1");
// Now add the paragraph to the main text of the first section.
doc.getFirstSection().getBody().appendChild(para);
// The paragraph node is now a child of the Body node.
System.out.println("Paragraph has a parent node: " + (para.getParentNode() != null));
getFieldType | |
public int getFieldType()
|
-
Returns the type of the field.
The value of the property is FieldType integer constant.
Example:
Shows how to find the type of field that is represented by a node which is derived from FieldChar.
FieldChar fieldStart = (FieldChar) doc.getChild(NodeType.FIELD_START, 0, true);
int type = fieldStart.getFieldType();
getFont | → inherited from Inline |
public Font getFont()
|
-
Provides access to the font formatting of this object.
Example:
Creates a simple document from scratch using the Aspose.Words object model.
// Create an "empty" document. Note that like in Microsoft Word,
// the empty document has one section, body and one paragraph in it.
Document doc = new Document();
// This truly makes the document empty. No sections (not possible in Microsoft Word).
doc.removeAllChildren();
// Create a new section node.
// Note that the section has not yet been added to the document,
// but we have to specify the parent document.
Section section = new Section(doc);
// Append the section to the document.
doc.appendChild(section);
// Lets set some properties for the section.
section.getPageSetup().setSectionStart(SectionStart.NEW_PAGE);
section.getPageSetup().setPaperSize(PaperSize.LETTER);
// The section that we created is empty, lets populate it. The section needs at least the Body node.
Body body = new Body(doc);
section.appendChild(body);
// The body needs to have at least one paragraph.
// Note that the paragraph has not yet been added to the document,
// but we have to specify the parent document.
// The parent document is needed so the paragraph can correctly work
// with styles and other document-wide information.
Paragraph para = new Paragraph(doc);
body.appendChild(para);
// We can set some formatting for the paragraph
para.getParagraphFormat().setStyleName("Heading 1");
para.getParagraphFormat().setAlignment(ParagraphAlignment.CENTER);
// So far we have one empty paragraph in the document.
// The document is valid and can be saved, but lets add some text before saving.
// Create a new run of text and add it to our paragraph.
Run run = new Run(doc);
run.setText("Hello World!");
run.getFont().setColor(Color.RED);
para.appendChild(run);
// As a matter of interest, you can retrieve text of the whole document and
// see that \x000c is automatically appended. \x000c is the end of section character.
System.out.println(doc.getText());
// Save the document.
doc.save(getArtifactsDir() + "Section.CreateFromScratch.doc");
isComposite | → inherited from Node |
public boolean isComposite()
|
-
Returns true if this node can contain other nodes.
This method returns false as Node cannot have child nodes.
Example:
Shows how to efficiently visit all direct and indirect children of a composite node.
public void recurseAllNodes() throws Exception
{
// Open a document.
Document doc = new Document(getMyDir() + "Node.RecurseAllNodes.doc");
// Invoke the recursive function that will walk the tree.
traverseAllNodes(doc);
}
/**
* A simple function that will walk through all children of a specified node recursively
* and print the type of each node to the screen.
*/
public void traverseAllNodes(CompositeNode parentNode)
{
// This is the most efficient way to loop through immediate children of a node.
for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling())
{
// Do some useful work.
System.out.println(Node.nodeTypeToString(childNode.getNodeType()));
// Recurse into the node if it is a composite node.
if (childNode.isComposite()) traverseAllNodes((CompositeNode) childNode);
}
}
isDeleteRevision | → inherited from Inline |
public boolean isDeleteRevision()
|
-
Returns true if this object was deleted in Microsoft Word while change tracking was enabled.
isDirty/isDirty | |
public boolean isDirty() / public void isDirty(boolean value)
|
-
Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications
made to the document.
isFormatRevision | → inherited from Inline |
public boolean isFormatRevision()
|
-
Returns true if formatting of the object was changed in Microsoft Word while change tracking was enabled.
isInsertRevision | → inherited from Inline |
public boolean isInsertRevision()
|
-
Returns true if this object was inserted in Microsoft Word while change tracking was enabled.
isLocked/isLocked | |
public boolean isLocked() / public void isLocked(boolean value)
|
-
Gets or sets whether the parent field is locked (should not recalculate its result).
isMoveFromRevision | → inherited from Inline |
public boolean isMoveFromRevision()
|
-
Returns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled.
isMoveToRevision | → inherited from Inline |
public boolean isMoveToRevision()
|
-
Returns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled.
getNextSibling | → inherited from Node |
public Node getNextSibling()
|
-
Gets the node immediately following this node.
If there is no next node, a null is returned.
Example:
Shows how to enumerate immediate child nodes of a composite node using NextSibling. In this example we enumerate all paragraphs of a section body.
// Get the section that we want to work on.
Section section = doc.getSections().get(0);
Body body = section.getBody();
// Loop starting from the first child until we reach null.
for (Node node = body.getFirstChild(); node != null; node = node.getNextSibling())
{
// Output the types of the nodes that we come across.
System.out.println(Node.nodeTypeToString(node.getNodeType()));
}
Example:
Shows how to efficiently visit all direct and indirect children of a composite node.
public void recurseAllNodes() throws Exception
{
// Open a document.
Document doc = new Document(getMyDir() + "Node.RecurseAllNodes.doc");
// Invoke the recursive function that will walk the tree.
traverseAllNodes(doc);
}
/**
* A simple function that will walk through all children of a specified node recursively
* and print the type of each node to the screen.
*/
public void traverseAllNodes(CompositeNode parentNode)
{
// This is the most efficient way to loop through immediate children of a node.
for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling())
{
// Do some useful work.
System.out.println(Node.nodeTypeToString(childNode.getNodeType()));
// Recurse into the node if it is a composite node.
if (childNode.isComposite()) traverseAllNodes((CompositeNode) childNode);
}
}
getNodeType | → inherited from SpecialChar |
public int getNodeType()
|
-
Returns NodeType.SpecialChar.
The value of the property is NodeType integer constant.
Example:
Shows how to retrieve the NodeType enumeration of nodes.
Document doc = new Document(getMyDir() + "Document.doc");
// Let's pick a node that we can't be quite sure of what type it is.
// In this case lets pick the first node of the first paragraph in the body of the document
Node node = doc.getFirstSection().getBody().getFirstParagraph().getFirstChild();
System.out.println("NodeType of first child: " + Node.nodeTypeToString(node.getNodeType()));
// This time let's pick a node that we know the type of. Create a new paragraph and a table node.
Paragraph para = new Paragraph(doc);
Table table = new Table(doc);
// Access to NodeType for typed nodes will always return their specific NodeType.
// i.e A paragraph node will always return NodeType.Paragraph, a table node will always return NodeType.Table.
System.out.println("NodeType of Paragraph: " + Node.nodeTypeToString(para.getNodeType()));
System.out.println("NodeType of Table: " + Node.nodeTypeToString(table.getNodeType()));
-
Gets the immediate parent of this node.
If a node has just been created and not yet added to the tree,
or if it has been removed from the tree, the parent is null.
Example:
Shows how to access the parent node.
// Create a new empty document. It has one section.
Document doc = new Document();
// The section is the first child node of the document.
Node section = doc.getFirstChild();
// The section's parent node is the document.
System.out.println("Section parent is the document: " + (doc == section.getParentNode()));
Example:
Shows that when you create any node, it requires a document that will own the node.
// Open a file from disk.
Document doc = new Document();
// Creating a new node of any type requires a document passed into the constructor.
Paragraph para = new Paragraph(doc);
// The new paragraph node does not yet have a parent.
System.out.println("Paragraph has no parent node: " + (para.getParentNode() == null));
// But the paragraph node knows its document.
System.out.println("Both nodes' documents are the same: " + (para.getDocument() == doc));
// The fact that a node always belongs to a document allows us to access and modify
// properties that reference the document-wide data such as styles or lists.
para.getParagraphFormat().setStyleName("Heading 1");
// Now add the paragraph to the main text of the first section.
doc.getFirstSection().getBody().appendChild(para);
// The paragraph node is now a child of the Body node.
System.out.println("Paragraph has a parent node: " + (para.getParentNode() != null));
getParentParagraph | → inherited from Inline |
public Paragraph getParentParagraph()
|
-
Retrieves the parent Paragraph of this node.
getPreviousSibling | → inherited from Node |
public Node getPreviousSibling()
|
-
Gets the node immediately preceding this node.
If there is no preceding node, a null is returned.
Example:
Demonstrates use of methods of Node and CompositeNode to remove a section before the last section in the document.
// Document is a CompositeNode and LastChild returns the last child node in the Document node.
// Since the Document can contain only Section nodes, the last child is the last section.
Node lastSection = doc.getLastChild();
// Each node knows its next and previous sibling nodes.
// Previous sibling of a section is a section before the specified section.
// If the node is the first child, PreviousSibling will return null.
Node sectionBeforeLast = lastSection.getPreviousSibling();
if (sectionBeforeLast != null) doc.removeChild(sectionBeforeLast);
getRange | → inherited from Node |
public Range getRange()
|
-
Returns a Range object that represents the portion of a document that is contained in this node.
Example:
Shows how to delete all characters of a range.
// Open Word document.
Document doc = new Document(getMyDir() + "Range.DeleteSection.doc");
// The document contains two sections. Each section has a paragraph of text.
System.out.println(doc.getText());
// Delete the first section from the document.
doc.getSections().get(0).getRange().delete();
// Check the first section was deleted by looking at the text of the whole document again.
System.out.println(doc.getText());
-
Accepts a visitor.
Calls DocumentVisitor.VisitSpecialChar.
For more info see the Visitor design pattern.
- Parameters:
visitor
- The visitor that will visit the node.
- Returns:
- False if the visitor requested the enumeration to stop.
deepClone | → inherited from Node |
public Node deepClone(boolean isCloneChildren) |
Example:
Shows how to clone composite nodes with and without their child nodes.
// Create a new empty document.
Document doc = new Document();
// Add some text to the first paragraph
Paragraph para = doc.getFirstSection().getBody().getFirstParagraph();
para.appendChild(new Run(doc, "Some text"));
// Clone the paragraph and the child nodes.
Node cloneWithChildren = para.deepClone(true);
// Only clone the paragraph and no child nodes.
Node cloneWithoutChildren = para.deepClone(false);
-
Gets the first ancestor of the specified NodeType.
- Parameters:
ancestorType
- A NodeType value. The node type of the ancestor to retrieve.
- Returns:
- The ancestor of the specified type or null if no ancestor of this type was found.
Example:
Shows how to find out if a table contains another table or if the table itself is nested inside another table.
public void calculateDepthOfNestedTables() throws Exception
{
Document doc = new Document(getMyDir() + "Table.NestedTables.doc");
int tableIndex = 0;
for (Table table : (Iterable<Table>) doc.getChildNodes(NodeType.TABLE, true))
{
// First lets find if any cells in the table have tables themselves as children.
int count = getChildTableCount(table);
System.out.println(MessageFormat.format("Table #{0} has {1} tables directly within its cells", tableIndex, count));
// Now let's try the other way around, lets try find if the table is nested inside another table and at what depth.
int tableDepth = getNestedDepthOfTable(table);
if (tableDepth > 0)
System.out.println(MessageFormat.format("Table #{0} is nested inside another table at depth of {1}", tableIndex, tableDepth));
else
System.out.println(MessageFormat.format("Table #{0} is a non nested table (is not a child of another table)", tableIndex));
tableIndex++;
}
}
/**
* Calculates what level a table is nested inside other tables.
*
* @returns An integer containing the level the table is nested at.
* 0 = Table is not nested inside any other table
* 1 = Table is nested within one parent table
* 2 = Table is nested within two parent tables etc..
*/
private static int getNestedDepthOfTable(Table table)
{
int depth = 0;
int type = table.getNodeType();
// The parent of the table will be a Cell, instead attempt to find a grandparent that is of type Table
Node parent = table.getAncestor(type);
while (parent != null)
{
// Every time we find a table a level up we increase the depth counter and then try to find an
// ancestor of type table from the parent.
depth++;
parent = parent.getAncestor(type);
}
return depth;
}
/**
* Determines if a table contains any immediate child table within its cells.
* Does not recursively traverse through those tables to check for further tables.
*
* @returns Returns true if at least one child cell contains a table.
* Returns false if no cells in the table contains a table.
*/
private static int getChildTableCount(Table table)
{
int tableCount = 0;
// Iterate through all child rows in the table
for (Row row : table.getRows())
{
// Iterate through all child cells in the row
for (Cell Cell : row.getCells())
{
// Retrieve the collection of child tables of this cell
TableCollection childTables = Cell.getTables();
// If this cell has a table as a child then return true
if (childTables.getCount() > 0) tableCount++;
}
}
// No cell contains a table
return tableCount;
}
getAncestor | → inherited from Node |
public CompositeNode getAncestor(java.lang.Class ancestorType) |
-
Gets the first ancestor of the specified object type.
The ancestor type matches if it is equal to ancestorType or derived from ancestorType.
- Parameters:
ancestorType
- The object type of the ancestor to retrieve.
- Returns:
- The ancestor of the specified type or null if no ancestor of this type was found.
getField | |
public Field getField() |
-
Returns a field for the field char.
A new Field object is created each time the method is called.
- Returns:
- A field for the field char.
Example:
Demonstrates how to retrieve the field class from an existing FieldStart node in the document.
Document doc = new Document(getMyDir() + "Document.TableOfContents.doc");
FieldStart fieldStart = (FieldStart) doc.getChild(NodeType.FIELD_START, 0, true);
// Retrieve the facade object which represents the field in the document.
Field field = fieldStart.getField();
System.out.println("Field code:" + field.getFieldCode());
System.out.println("Field result: " + field.getResult());
System.out.println("Is locked: " + field.isLocked());
// This updates only this field in the document.
field.update();
getText | → inherited from SpecialChar |
public java.lang.String getText() |
-
Gets the special character that this node represents.
- Returns:
- The string that contains the character that this node represents.
nextPreOrder | → inherited from Node |
public Node nextPreOrder(Node rootNode) |
-
Gets next node according to the pre-order tree traversal algorithm.
- Parameters:
rootNode
- The top node (limit) of traversal.
- Returns:
- Next node in pre-order order. Null if reached the rootNode.
Example:
Shows how to delete all images from a document using pre-order tree traversal.
Node curNode = doc;
while (curNode != null)
{
Node nextNode = curNode.nextPreOrder(doc);
if (curNode.getNodeType() == NodeType.SHAPE)
{
Shape shape = (Shape) curNode;
// Several shape types can have an image including image shapes and OLE objects.
if (shape.hasImage()) shape.remove();
}
curNode = nextNode;
}
previousPreOrder | → inherited from Node |
public Node previousPreOrder(Node rootNode) |
-
Gets the previous node according to the pre-order tree traversal algorithm.
- Parameters:
rootNode
- The top node (limit) of traversal.
- Returns:
- Previous node in pre-order order. Null if reached the rootNode.
remove | → inherited from Node |
public void remove() |
-
Removes itself from the parent.
Example:
Shows how to remove all nodes of a specific type from a composite node. In this example we remove tables from a section body.
// Get the section that we want to work on.
Section section = doc.getSections().get(0);
Body body = section.getBody();
// Select the first child node in the body.
Node curNode = body.getFirstChild();
while (curNode != null)
{
// Save the pointer to the next sibling node because if the current
// node is removed from the parent in the next step, we will have
// no way of finding the next node to continue the loop.
Node nextNode = curNode.getNextSibling();
// A section body can contain Paragraph and Table nodes.
// If the node is a Table, remove it from the parent.
if (curNode.getNodeType() == NodeType.TABLE) curNode.remove();
// Continue going through child nodes until null (no more siblings) is reached.
curNode = nextNode;
}
Example:
Shows how to delete all images from a document.
// Here we get all shapes from the document node, but you can do this for any smaller
// node too, for example delete shapes from a single section or a paragraph.
NodeCollection shapes = doc.getChildNodes(NodeType.SHAPE, true);
// We cannot delete shape nodes while we enumerate through the collection.
// One solution is to add nodes that we want to delete to a temporary array and delete afterwards.
ArrayList shapesToDelete = new ArrayList();
for (Shape shape : (Iterable<Shape>) shapes)
{
// Several shape types can have an image including image shapes and OLE objects.
if (shape.hasImage()) shapesToDelete.add(shape);
}
// Now we can delete shapes.
for (Shape shape : (Iterable<Shape>) shapesToDelete)
shape.remove();
toString | → inherited from Node |
public java.lang.String toString(SaveOptions saveOptions)
throws java.lang.Exception |
-
Exports the content of the node into a string using the specified save options.
- Parameters:
saveOptions
- Specifies the options that control how the node is saved.
- Returns:
- The content of the node in the specified format.
Example:
Exports the content of a node to string in HTML format using custom specified options.
Document doc = new Document(getMyDir() + "Document.doc");
// Extract the last paragraph in the document to convert to HTML.
Node node = doc.getLastSection().getBody().getLastParagraph();
// Create an instance of HtmlSaveOptions and set a few options.
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.setExportHeadersFootersMode(ExportHeadersFootersMode.PER_SECTION);
saveOptions.setExportRelativeFontSize(true);
// Convert the document to HTML and return as a string. Pass the instance of HtmlSaveOptions to
// to use the specified options during the conversion.
String nodeAsHtml = node.toString(saveOptions);
toString | → inherited from Node |
public java.lang.String toString(int saveFormat)
throws java.lang.Exception |
-
Exports the content of the node into a string in the specified format.
- Returns:
- The content of the node in the specified format.
- Parameters:
saveFormat
- A SaveFormat value.
Example:
Shows how to extract the label of each paragraph in a list as a value or a String.
Document doc = new Document(getMyDir() + "Lists.PrintOutAllLists.doc");
doc.updateListLabels();
int listParaCount = 1;
for (Paragraph paragraph : (Iterable<Paragraph>) doc.getChildNodes(NodeType.PARAGRAPH, true))
{
// Find if we have the paragraph list. In our document our list uses plain arabic numbers,
// which start at three and ends at six.
if (paragraph.getListFormat().isListItem())
{
System.out.println(MessageFormat.format("Paragraph #{0}", listParaCount));
// This is the text we get when actually getting when we output this node to text format.
// The list labels are not included in this text output. Trim any paragraph formatting characters.
String paragraphText = paragraph.toString(SaveFormat.TEXT).trim();
System.out.println("Exported Text: " + paragraphText);
ListLabel label = paragraph.getListLabel();
// This gets the position of the paragraph in current level of the list. If we have a list with multiple level then this
// will tell us what position it is on that particular level.
System.out.println("Numerical Id: " + label.getLabelValue());
// Combine them together to include the list label with the text in the output.
System.out.println("List label combined with text: " + label.getLabelString() + " " + paragraphText);
listParaCount++;
}
}
Example:
Shows the difference between calling the GetText and ToString methods on a node.
Document doc = new Document();
// Enter a dummy field into the document.
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField("MERGEFIELD Field");
// GetText will retrieve all field codes and special characters
System.out.println("GetText() Result: " + doc.getText());
// ToString will export the node to the specified format. When converted to text it will not retrieve fields code
// or special characters, but will still contain some natural formatting characters such as paragraph markers etc.
// This is the same as "viewing" the document as if it was opened in a text editor.
System.out.println("ToString() Result: " + doc.toString(SaveFormat.TEXT));
Example:
Exports the content of a node to string in HTML format using default options.
Document doc = new Document(getMyDir() + "Document.doc");
// Extract the last paragraph in the document to convert to HTML.
Node node = doc.getLastSection().getBody().getLastParagraph();
// When ToString is called using the SaveFormat overload then conversion is executed using default save options.
// When saving to HTML using default options the following settings are set:
// ExportImagesAsBase64 = true
// CssStyleSheetType = CssStyleSheetType.Inline
// ExportFontResources = false
String nodeAsHtml = node.toString(SaveFormat.HTML);
See Also:
Aspose.Words Documentation - the home page for the Aspose.Words Product Documentation.
Aspose.Words Support Forum - our preferred method of support.