Aspose::Words::Fields::FieldXE Class Reference

Implements the XE field.

Examples

Shows how to create an INDEX field, and then use XE fields to populate it with entries.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side
// and the page containing the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
 
// Configure the INDEX field only to display XE fields that are within the bounds
// of a bookmark named "MainBookmark", and whose "EntryType" properties have a value of "A".
// For both INDEX and XE fields, the "EntryType" property only uses the first character of its string value.
index->set_BookmarkName(u"MainBookmark");
index->set_EntryType(u"A");
 
ASSERT_EQ(u" INDEX  \\b MainBookmark \\f A", index->GetFieldCode());
 
// On a new page, start the bookmark with a name that matches the value
// of the INDEX field's "BookmarkName" property.
builder->InsertBreak(BreakType::PageBreak);
builder->StartBookmark(u"MainBookmark");
 
// The INDEX field will pick up this entry because it is inside the bookmark,
// and its entry type also matches the INDEX field's entry type.
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Index entry 1");
indexEntry->set_EntryType(u"A");
 
ASSERT_EQ(u" XE  \"Index entry 1\" \\f A", indexEntry->GetFieldCode());
 
// Insert an XE field that will not appear in the INDEX because the entry types do not match.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Index entry 2");
indexEntry->set_EntryType(u"B");
 
// End the bookmark and insert an XE field afterwards.
// It is of the same type as the INDEX field, but will not appear
// since it is outside the bookmark's boundaries.
builder->EndBookmark(u"MainBookmark");
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Index entry 3");
indexEntry->set_EntryType(u"A");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.Filtering.docx");

Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
index->set_LanguageId(u"1033");
 
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index->set_Heading(u"A");
 
// Set the table created by the INDEX field to span over 2 columns.
index->set_NumberOfColumns(u"2");
 
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index->set_LetterRange(u"a-c");
 
ASSERT_EQ(u" INDEX  \\z 1033 \\h A \\c 2 \\p a-c", index->GetFieldCode());
 
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder->InsertBreak(BreakType::PageBreak);
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Apple");
indexEntry->set_IsItalic(true);
 
ASSERT_EQ(u" XE  Apple \\i", indexEntry->GetFieldCode());
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Apricot");
indexEntry->set_IsBold(true);
 
ASSERT_EQ(u" XE  Apricot \\b", indexEntry->GetFieldCode());
 
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Banana");
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Cherry");
 
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Avocado");
 
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Durian");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.Formatting.docx");

#include <Aspose.Words.Cpp/Fields/FieldXE.h>

Inheritance diagram for Aspose::Words::Fields::FieldXE:

Public Member Functions
String	get_EntryType ()
	Gets or sets an index entry type. More...
bool	get_HasPageRangeBookmarkName ()
	Gets a value indicating whether a page range bookmark name is provided through the field's code. More...
bool	get_IsBold ()
	Gets or sets whether to apply bold formatting to the entry's page number. More...
bool	get_IsItalic ()
	Gets or sets whether to apply italic formatting to the entry's page number. More...
String	get_PageNumberReplacement ()
	Gets or sets text used in place of a page number. More...
String	get_PageRangeBookmarkName ()
	Gets or sets the name of the bookmark that marks a range of pages that is inserted as the entry's page number. More...
String	get_Text ()
	Gets or sets the text of the entry. More...
String	get_Yomi ()
	Gets or sets the yomi (first phonetic character for sorting indexes) for the index entry. More...
FieldSwitchType	GetSwitchType (String switchName) override
virtual const TypeInfo &	GetType () const override
virtual bool	Is (const TypeInfo &target) const override
void	set_EntryType (String value)
	Setter for get_EntryType. More...
void	set_IsBold (bool value)
	Setter for get_IsBold. More...
void	set_IsItalic (bool value)
	Setter for get_IsItalic. More...
void	set_PageNumberReplacement (String value)
	Setter for get_PageNumberReplacement. More...
void	set_PageRangeBookmarkName (String value)
	Setter for get_PageRangeBookmarkName. More...
void	set_Text (String value)
	Setter for get_Text. More...
void	set_Yomi (String value)
	Setter for get_Yomi. More...
Public Member Functions inherited from Field
String	get_DisplayResult ()
	Gets the text that represents the displayed field result. More...
SharedPtr< FieldEnd >	get_End () const
	Gets the node that represents the field end. More...
SharedPtr< FieldEnd >	get_FieldEnd () const
	Gets the node that represents the field end. More...
SharedPtr< FieldStart >	get_FieldStart () const
	Gets the node that represents the start of the field. More...
SharedPtr< FieldFormat >	get_Format ()
	Gets a FieldFormat object that provides typed access to field's formatting. More...
bool	get_IsDirty ()
	Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document. More...
bool	get_IsLocked ()
	Gets or sets whether the field is locked (should not recalculate its result). More...
int32_t	get_LocaleId ()
	Gets or sets the LCID of the field. More...
String	get_Result ()
	Gets or sets text that is between the field separator and field end. More...
SharedPtr< FieldSeparator >	get_Separator ()
	Gets the node that represents the field separator. Can be null. More...
SharedPtr< FieldStart >	get_Start () const
	Gets the node that represents the start of the field. More...
virtual FieldType	get_Type ()
	Gets the Microsoft Word field type. More...
String	GetFieldCode ()
	Returns text between field start and field separator (or field end if there is no separator). Both field code and field result of child fields are included. More...
String	GetFieldCode (bool includeChildFieldCodes)
	Returns text between field start and field separator (or field end if there is no separator). More...
SharedPtr< Node >	Remove ()
	Removes the field from the document. Returns a node right after the field. If the field's end is the last child of its parent node, returns its parent paragraph. If the field is already removed, returns null. More...
void	set_IsDirty (bool value)
	Setter for get_IsDirty. More...
void	set_IsLocked (bool value)
	Setter for get_IsLocked. More...
void	set_LocaleId (int32_t value)
	Setter for get_LocaleId. More...
void	set_Result (String value)
	Setter for get_Result. More...
bool	Unlink ()
	Performs the field unlink. More...
void	Update ()
	Performs the field update. Throws if the field is being updated already. More...
void	Update (bool ignoreMergeFormat)
	Performs a field update. Throws if the field is being updated already. More...

Static Public Member Functions
static const TypeInfo &	Type ()
Static Public Member Functions inherited from Field
static const TypeInfo &	Type ()

Member Function Documentation

get_EntryType()

System::String Aspose::Words::Fields::FieldXE::get_EntryType

(

)

Gets or sets an index entry type.

Examples

Shows how to create an INDEX field, and then use XE fields to populate it with entries.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side
// and the page containing the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
 
// Configure the INDEX field only to display XE fields that are within the bounds
// of a bookmark named "MainBookmark", and whose "EntryType" properties have a value of "A".
// For both INDEX and XE fields, the "EntryType" property only uses the first character of its string value.
index->set_BookmarkName(u"MainBookmark");
index->set_EntryType(u"A");
 
ASSERT_EQ(u" INDEX  \\b MainBookmark \\f A", index->GetFieldCode());
 
// On a new page, start the bookmark with a name that matches the value
// of the INDEX field's "BookmarkName" property.
builder->InsertBreak(BreakType::PageBreak);
builder->StartBookmark(u"MainBookmark");
 
// The INDEX field will pick up this entry because it is inside the bookmark,
// and its entry type also matches the INDEX field's entry type.
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Index entry 1");
indexEntry->set_EntryType(u"A");
 
ASSERT_EQ(u" XE  \"Index entry 1\" \\f A", indexEntry->GetFieldCode());
 
// Insert an XE field that will not appear in the INDEX because the entry types do not match.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Index entry 2");
indexEntry->set_EntryType(u"B");
 
// End the bookmark and insert an XE field afterwards.
// It is of the same type as the INDEX field, but will not appear
// since it is outside the bookmark's boundaries.
builder->EndBookmark(u"MainBookmark");
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Index entry 3");
indexEntry->set_EntryType(u"A");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.Filtering.docx");

get_HasPageRangeBookmarkName()

bool Aspose::Words::Fields::FieldXE::get_HasPageRangeBookmarkName

(

)

Gets a value indicating whether a page range bookmark name is provided through the field's code.

Examples

Shows how to specify a bookmark's spanned pages as a page range for an INDEX field entry.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
 
// For INDEX entries that display page ranges, we can specify a separator string
// which will appear between the number of the first page, and the number of the last.
index->set_PageNumberSeparator(u", on page(s) ");
index->set_PageRangeSeparator(u" to ");
 
ASSERT_EQ(u" INDEX  \\e \", on page(s) \" \\g \" to \"", index->GetFieldCode());
 
builder->InsertBreak(BreakType::PageBreak);
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"My entry");
 
// If an XE field names a bookmark using the PageRangeBookmarkName property,
// its INDEX entry will show the range of pages that the bookmark spans
// instead of the number of the page that contains the XE field.
indexEntry->set_PageRangeBookmarkName(u"MyBookmark");
 
ASSERT_EQ(u" XE  \"My entry\" \\r MyBookmark", indexEntry->GetFieldCode());
ASSERT_TRUE(indexEntry->get_HasPageRangeBookmarkName());
 
// Insert a bookmark that starts on page 3 and ends on page 5.
// The INDEX entry for the XE field that references this bookmark will display this page range.
// In our table, the INDEX entry will display "My entry, on page(s) 3 to 5".
builder->InsertBreak(BreakType::PageBreak);
builder->StartBookmark(u"MyBookmark");
builder->Write(u"Start of MyBookmark");
builder->InsertBreak(BreakType::PageBreak);
builder->InsertBreak(BreakType::PageBreak);
builder->Write(u"End of MyBookmark");
builder->EndBookmark(u"MyBookmark");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.PageRangeBookmark.docx");

get_IsBold()

bool Aspose::Words::Fields::FieldXE::get_IsBold

(

)

Gets or sets whether to apply bold formatting to the entry's page number.

Examples

Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
index->set_LanguageId(u"1033");
 
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index->set_Heading(u"A");
 
// Set the table created by the INDEX field to span over 2 columns.
index->set_NumberOfColumns(u"2");
 
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index->set_LetterRange(u"a-c");
 
ASSERT_EQ(u" INDEX  \\z 1033 \\h A \\c 2 \\p a-c", index->GetFieldCode());
 
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder->InsertBreak(BreakType::PageBreak);
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Apple");
indexEntry->set_IsItalic(true);
 
ASSERT_EQ(u" XE  Apple \\i", indexEntry->GetFieldCode());
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Apricot");
indexEntry->set_IsBold(true);
 
ASSERT_EQ(u" XE  Apricot \\b", indexEntry->GetFieldCode());
 
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Banana");
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Cherry");
 
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Avocado");
 
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Durian");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.Formatting.docx");

get_IsItalic()

bool Aspose::Words::Fields::FieldXE::get_IsItalic

(

)

Gets or sets whether to apply italic formatting to the entry's page number.

Examples

Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
index->set_LanguageId(u"1033");
 
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index->set_Heading(u"A");
 
// Set the table created by the INDEX field to span over 2 columns.
index->set_NumberOfColumns(u"2");
 
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index->set_LetterRange(u"a-c");
 
ASSERT_EQ(u" INDEX  \\z 1033 \\h A \\c 2 \\p a-c", index->GetFieldCode());
 
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder->InsertBreak(BreakType::PageBreak);
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Apple");
indexEntry->set_IsItalic(true);
 
ASSERT_EQ(u" XE  Apple \\i", indexEntry->GetFieldCode());
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Apricot");
indexEntry->set_IsBold(true);
 
ASSERT_EQ(u" XE  Apricot \\b", indexEntry->GetFieldCode());
 
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Banana");
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Cherry");
 
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Avocado");
 
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Durian");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.Formatting.docx");

get_PageNumberReplacement()

System::String Aspose::Words::Fields::FieldXE::get_PageNumberReplacement

(

)

Gets or sets text used in place of a page number.

Examples

Shows how to define cross references in an INDEX field.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
 
// We can configure an XE field to get its INDEX entry to display a string instead of a page number.
// First, for entries that substitute a page number with a string,
// specify a custom separator between the XE field's Text property value and the string.
index->set_CrossReferenceSeparator(u", see: ");
 
ASSERT_EQ(u" INDEX  \\k \", see: \"", index->GetFieldCode());
 
// Insert an XE field, which creates a regular INDEX entry which displays this field's page number,
// and does not invoke the CrossReferenceSeparator value.
// The entry for this XE field will display "Apple, 2".
builder->InsertBreak(BreakType::PageBreak);
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Apple");
 
ASSERT_EQ(u" XE  Apple", indexEntry->GetFieldCode());
 
// Insert another XE field on page 3 and set a value for the PageNumberReplacement property.
// This value will show up instead of the number of the page that this field is on,
// and the INDEX field's CrossReferenceSeparator value will appear in front of it.
// The entry for this XE field will display "Banana, see: Tropical fruit".
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Banana");
indexEntry->set_PageNumberReplacement(u"Tropical fruit");
 
ASSERT_EQ(u" XE  Banana \\t \"Tropical fruit\"", indexEntry->GetFieldCode());
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.CrossReferenceSeparator.docx");

get_PageRangeBookmarkName()

System::String Aspose::Words::Fields::FieldXE::get_PageRangeBookmarkName

(

)

Gets or sets the name of the bookmark that marks a range of pages that is inserted as the entry's page number.

Examples

Shows how to specify a bookmark's spanned pages as a page range for an INDEX field entry.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
 
// For INDEX entries that display page ranges, we can specify a separator string
// which will appear between the number of the first page, and the number of the last.
index->set_PageNumberSeparator(u", on page(s) ");
index->set_PageRangeSeparator(u" to ");
 
ASSERT_EQ(u" INDEX  \\e \", on page(s) \" \\g \" to \"", index->GetFieldCode());
 
builder->InsertBreak(BreakType::PageBreak);
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"My entry");
 
// If an XE field names a bookmark using the PageRangeBookmarkName property,
// its INDEX entry will show the range of pages that the bookmark spans
// instead of the number of the page that contains the XE field.
indexEntry->set_PageRangeBookmarkName(u"MyBookmark");
 
ASSERT_EQ(u" XE  \"My entry\" \\r MyBookmark", indexEntry->GetFieldCode());
ASSERT_TRUE(indexEntry->get_HasPageRangeBookmarkName());
 
// Insert a bookmark that starts on page 3 and ends on page 5.
// The INDEX entry for the XE field that references this bookmark will display this page range.
// In our table, the INDEX entry will display "My entry, on page(s) 3 to 5".
builder->InsertBreak(BreakType::PageBreak);
builder->StartBookmark(u"MyBookmark");
builder->Write(u"Start of MyBookmark");
builder->InsertBreak(BreakType::PageBreak);
builder->InsertBreak(BreakType::PageBreak);
builder->Write(u"End of MyBookmark");
builder->EndBookmark(u"MyBookmark");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.PageRangeBookmark.docx");

get_Text()

System::String Aspose::Words::Fields::FieldXE::get_Text

(

)

Gets or sets the text of the entry.

Examples

Shows how to create an INDEX field, and then use XE fields to populate it with entries.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side
// and the page containing the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
 
// Configure the INDEX field only to display XE fields that are within the bounds
// of a bookmark named "MainBookmark", and whose "EntryType" properties have a value of "A".
// For both INDEX and XE fields, the "EntryType" property only uses the first character of its string value.
index->set_BookmarkName(u"MainBookmark");
index->set_EntryType(u"A");
 
ASSERT_EQ(u" INDEX  \\b MainBookmark \\f A", index->GetFieldCode());
 
// On a new page, start the bookmark with a name that matches the value
// of the INDEX field's "BookmarkName" property.
builder->InsertBreak(BreakType::PageBreak);
builder->StartBookmark(u"MainBookmark");
 
// The INDEX field will pick up this entry because it is inside the bookmark,
// and its entry type also matches the INDEX field's entry type.
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Index entry 1");
indexEntry->set_EntryType(u"A");
 
ASSERT_EQ(u" XE  \"Index entry 1\" \\f A", indexEntry->GetFieldCode());
 
// Insert an XE field that will not appear in the INDEX because the entry types do not match.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Index entry 2");
indexEntry->set_EntryType(u"B");
 
// End the bookmark and insert an XE field afterwards.
// It is of the same type as the INDEX field, but will not appear
// since it is outside the bookmark's boundaries.
builder->EndBookmark(u"MainBookmark");
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Index entry 3");
indexEntry->set_EntryType(u"A");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.Filtering.docx");

Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
index->set_LanguageId(u"1033");
 
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index->set_Heading(u"A");
 
// Set the table created by the INDEX field to span over 2 columns.
index->set_NumberOfColumns(u"2");
 
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index->set_LetterRange(u"a-c");
 
ASSERT_EQ(u" INDEX  \\z 1033 \\h A \\c 2 \\p a-c", index->GetFieldCode());
 
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder->InsertBreak(BreakType::PageBreak);
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Apple");
indexEntry->set_IsItalic(true);
 
ASSERT_EQ(u" XE  Apple \\i", indexEntry->GetFieldCode());
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Apricot");
indexEntry->set_IsBold(true);
 
ASSERT_EQ(u" XE  Apricot \\b", indexEntry->GetFieldCode());
 
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Banana");
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Cherry");
 
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Avocado");
 
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"Durian");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.Formatting.docx");

get_Yomi()

System::String Aspose::Words::Fields::FieldXE::get_Yomi

(

)

Gets or sets the yomi (first phonetic character for sorting indexes) for the index entry.

Examples

Shows how to sort INDEX field entries phonetically.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
auto index = System::DynamicCast<FieldIndex>(builder->InsertField(FieldType::FieldIndex, true));
 
// The INDEX table automatically sorts its entries by the values of their Text properties in alphabetic order.
// Set the INDEX table to sort entries phonetically using Hiragana instead.
index->set_UseYomi(sortEntriesUsingYomi);
 
if (sortEntriesUsingYomi)
{
    ASSERT_EQ(u" INDEX  \\y", index->GetFieldCode());
}
else
{
    ASSERT_EQ(u" INDEX ", index->GetFieldCode());
}
 
// Insert 4 XE fields, which would show up as entries in the INDEX field's table of contents.
// The "Text" property may contain a word's spelling in Kanji, whose pronunciation may be ambiguous,
// while the "Yomi" version of the word will spell exactly how it is pronounced using Hiragana.
// If we set our INDEX field to use Yomi, it will sort these entries
// by the value of their Yomi properties, instead of their Text values.
builder->InsertBreak(BreakType::PageBreak);
auto indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"愛子");
indexEntry->set_Yomi(u"あ");
 
ASSERT_EQ(u" XE  愛子 \\y あ", indexEntry->GetFieldCode());
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"明美");
indexEntry->set_Yomi(u"あ");
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"恵美");
indexEntry->set_Yomi(u"え");
 
builder->InsertBreak(BreakType::PageBreak);
indexEntry = System::DynamicCast<FieldXE>(builder->InsertField(FieldType::FieldIndexEntry, true));
indexEntry->set_Text(u"愛美");
indexEntry->set_Yomi(u"え");
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.INDEX.XE.Yomi.docx");

GetSwitchType()

Aspose::Words::Fields::FieldSwitchType Aspose::Words::Fields::FieldXE::GetSwitchType ( System::String  switchName )

override

GetType()

virtual const System::TypeInfo& Aspose::Words::Fields::FieldXE::GetType ( ) const

overridevirtual

Reimplemented from Aspose::Words::Fields::Field.

Is()

virtual bool Aspose::Words::Fields::FieldXE::Is ( const System::TypeInfo &  target ) const

overridevirtual

Reimplemented from Aspose::Words::Fields::Field.

set_EntryType()

void Aspose::Words::Fields::FieldXE::set_EntryType

(

System::String

value

)

Setter for Aspose::Words::Fields::FieldXE::get_EntryType.

set_IsBold()

void Aspose::Words::Fields::FieldXE::set_IsBold

(

bool

value

)

Setter for Aspose::Words::Fields::FieldXE::get_IsBold.

set_IsItalic()

void Aspose::Words::Fields::FieldXE::set_IsItalic

(

bool

value

)

Setter for Aspose::Words::Fields::FieldXE::get_IsItalic.

set_PageNumberReplacement()

void Aspose::Words::Fields::FieldXE::set_PageNumberReplacement

(

System::String

value

)

Setter for Aspose::Words::Fields::FieldXE::get_PageNumberReplacement.

set_PageRangeBookmarkName()

void Aspose::Words::Fields::FieldXE::set_PageRangeBookmarkName

(

System::String

value

)

Setter for Aspose::Words::Fields::FieldXE::get_PageRangeBookmarkName.

set_Text()

void Aspose::Words::Fields::FieldXE::set_Text

(

System::String

value

)

Setter for Aspose::Words::Fields::FieldXE::get_Text.

set_Yomi()

void Aspose::Words::Fields::FieldXE::set_Yomi

(

System::String

value

)

Setter for Aspose::Words::Fields::FieldXE::get_Yomi.

Type()

static const System::TypeInfo& Aspose::Words::Fields::FieldXE::Type ( )

static