FieldChar Class
Complex Field Character.When the object is serialized out as xml, its qualified name is w:fldChar.
Inheritance Hierarchy
System.Object
DocumentFormat.OpenXml.OpenXmlElement
DocumentFormat.OpenXml.OpenXmlCompositeElement
DocumentFormat.OpenXml.Wordprocessing.FieldChar
Namespace: DocumentFormat.OpenXml.Wordprocessing
Assembly: DocumentFormat.OpenXml (in DocumentFormat.OpenXml.dll)
Syntax
'Declaration
<ChildElementInfoAttribute(GetType(FieldData))> _
<ChildElementInfoAttribute(GetType(NumberingChange))> _
<ChildElementInfoAttribute(GetType(FormFieldData))> _
Public Class FieldChar _
Inherits OpenXmlCompositeElement
'Usage
Dim instance As FieldChar
[ChildElementInfoAttribute(typeof(FieldData))]
[ChildElementInfoAttribute(typeof(NumberingChange))]
[ChildElementInfoAttribute(typeof(FormFieldData))]
public class FieldChar : OpenXmlCompositeElement
Remarks
The following table lists the possible child types:
FieldData <w:fldData>
FormFieldData <w:ffData>
NumberingChange <w:numberingChange>
[ISO/IEC 29500-1 1st Edition]
17.16.13 fldChar (Complex Field Character)
This element specifies the presence of a complex field character at the current location in the parent run. A complex field character is a special character which delimits the start and end of a complex field or separates its field codes from its current field result.
A complex field is defined via the use of the two required complex field characters: a start character, which specifies the beginning of a complex field within the document content; and an end character, which specifies the end of a complex field. This syntax allows multiple fields to be embedded (or "nested") within each other in a document.
As well, because a complex field can specify both its field codes and its current result within the document, these two items are separated by the optional separator character, which defines the end of the field codes and the beginning of the field contents. The omission of this character shall be used to specify that the contents of the field are entirely field codes (i.e. the field has no result).
[Example: Consider the following complex field definition within a WordprocessingML document:
<w:r>
<w:fldChar w:fldCharType="begin" />
</w:r>
<w:r>
<w:instrText>AUTHOR</w:instrText>
</w:r>
<w:r>
<w:fldChar w:fldCharType="separate" />
</w:r>
<w:r>
<w:t>Rex Jaeschke</w:t>
</w:r>
<w:r>
<w:fldChar w:fldCharType="end" />
</w:r>
The three fldChar elements specify:
The beginning of the field, using the type attribute value of start
The separator between the field codes and the current field results, using the type attribute value of separate
The end of the field, using the type attribute value of end
end example]
If a complex field character is located in an inappropriate location in a WordprocessingML document, then its presence shall be ignored and no field shall be present in the resulting document when displayed. Also, if a complex field is not closed before the end of a document story, then no field shall be generated and each individual run shall be processed as if the field characters did not exist (i.e. the contents of all field code run content shall not be displayed, and the field results shall be displayed as literal text).
[Example: Consider the following WordprocessingML document:
<w:body>
<w:p>
<w:r>
<w:fldChar w:fldCharType="start" />
</w:r>
<w:r>
<w:instrText>AUTHOR</w:instrText>
</w:r>
<w:r>
<w:fldChar w:fldCharType="separate" />
</w:r>
<w:r>
<w:t>Rex Jaeschke</w:t>
</w:r>
</w:p>
</w:body>
The complex field is technically incorrect since no end character exists in the main document story. The resulting content must be interpreted as though no field characters exist, resulting in only the literal text Rex Jaeschke being displayed in the document. end example]
Parent Elements |
|---|
r (§22.1.2.87); r (§17.3.2.25) |
Child Elements |
Subclause |
|---|---|
ffData (Form Field Properties) |
§17.16.17 |
Attributes |
Description |
|---|---|
dirty (Field Result Invalidated) |
Specifies that this field has been flagged by an application to indicate that its current results are no longer correct (stale) due to other modifications made to the document, and these contents should be updated before they are displayed if this functionality is supported by the next processing application. [Rationale: This functionality allows applications with limited subsets of the full functionality of ISO/IEC 29500 to process Word Open XML documents without needing to understand and update all fields based on the semantics for their field codes. For example, an application can add a new paragraph and flag the table of contents as dirty, without needing to understand anything about how to recalculate that field's content. end rationale] If this attribute is omitted, then its value shall be assumed to be false. If the type of the current field character is not start, then his setting can be ignored. [Example: Consider the following WordprocessingML for a complex field: The dirty attribute value of true specifies that the contents of this field are no longer current based on the contents of the document, and should be recalculated whenever an application with this functionality reads the document. end example] The possible values for this attribute are defined by the ST_OnOff simple type (§22.9.2.7). |
fldCharType (Field Character Type) |
Specifies the type of the current complex field character in the document. [Example: Consider the following WordprocessingML for a complex field character: The type attribute value of separate specifies that this is a complex field separator character; therefore it is being used to separate the field codes from the field contents in a complex field. end example] The possible values for this attribute are defined by the ST_FldCharType simple type (§17.18.29). |
fldLock (Field Should Not Be Recalculated) |
Specifies that the parent complex field shall not have its field result recalculated, even if an application attempts to recalculate the results of all fields in the document or a recalculation is explicitly requested. If this attribute is omitted, then its value shall be assumed to be false. If the type of the current field character is not start, then his setting can be ignored. [Example: Consider the following WordprocessingML for a complex field: The fldLock attribute value of true specifies that the contents of this field must remain field result regardless of the actual result of the current field codes. end example] The possible values for this attribute are defined by the ST_OnOff simple type (§22.9.2.7). |
[Note: The W3C XML Schema definition of this element’s content model (CT_FldChar) is located in §A.1. end note]
© ISO/IEC29500: 2008.
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.