Field Result Formatting

Field Result Formatting

This guide shows how to control the numeric, date/time, and general formatting applied to a field’s calculated result in Aspose.Words FOSS for .NET, using the FieldFormat class, the GeneralFormat enum, and GeneralFormatCollection. Every Field instance exposes these formatting switches through its Format property; this page is the deep dive on what that property offers.

Accessing a Field’s Formatting

Every Field — and its typed subclasses such as FieldDate, FieldCreateDate, and FieldSymbol — exposes a Format property of type FieldFormat, used for typed access to the field’s numeric, date and time, and general formatting. Read Field.Format to inspect or change the switches attached to a field’s code without hand-editing the raw field code text.

Numeric and Date/Time Format Pictures

FieldFormat.NumericFormat is a writable string property holding the formatting applied to a numeric field result. FieldFormat.DateTimeFormat is a writable string property holding the formatting applied to a date and time field result. Set either property to change how the corresponding field type renders its calculated value.

General Formats

FieldFormat.GeneralFormats returns a GeneralFormatCollection — general-purpose formats applied to a numeric, text, or any field result. Its members are drawn from the GeneralFormat enum, which spans case transforms (Upper, Lower, FirstCap, Caps), Roman and ordinal numbering (UppercaseRoman, LowercaseRoman, Ordinal, OrdText), currency and cardinal text (DollarText, BahtText, CardText), locale-specific numbering systems (Aiueo, Arabic, ArabicAbjad, ArabicAlpha, ArabicDash, ChineseNum1–ChineseNum3, KanjiNum1–KanjiNum3, Hebrew1, Hebrew2, Ganada, Chosung, Zodiac1–Zodiac3, ThaiArabic, ThaiCardText, ThaiLetter, HindiArabic, HindiCardText, HindiLetter1, HindiLetter2, VietCardText, DBNum1–DBNum4, DBChar, SBChar, GB1–GB4, Hex, CircleNum, UppercaseAlphabetic, LowercaseAlphabetic), and the merge-field-specific values CharFormat, MergeFormat, and MergeFormatInet. None clears general formatting.

Managing the GeneralFormatCollection

GeneralFormatCollection implements IEnumerable<GeneralFormat>, so you can iterate it with GetEnumerator() in a foreach loop. Call Add(item) to append a GeneralFormat value, Remove(item) to remove every occurrence of a value, or RemoveAt(index) to remove the value at a specific position. Count reports how many general formats are currently applied.

Tips and Best Practices

• Set Field.Format.NumericFormat or Field.Format.DateTimeFormat rather than embedding a formatting picture directly in the field code string — the typed property keeps the field code and its formatting switch in sync.
• Combine multiple GeneralFormat values (for example Upper and MergeFormat) by adding each one to GeneralFormats individually; the collection permits more than one entry.
• After changing any FieldFormat property, call Update() on the owning field so the new formatting is reflected in Result / DisplayResult.
• Use GeneralFormat.None to explicitly clear a general format entry rather than leaving stale formatting values in the collection.
• Check GeneralFormatCollection.Count before assuming a field has no general formatting applied — an empty collection and a collection containing None are different states.

Common Issues

FAQ

What is FieldFormat used for?

It’s the typed formatting object exposed by Field.Format, giving access to a field’s numeric format (NumericFormat), date/time format (DateTimeFormat), and general formats (GeneralFormats).

Can a field have more than one general format applied?

Yes — GeneralFormats is a GeneralFormatCollection, and you can Add more than one GeneralFormat value to it.

How do I remove all general formatting from a field?

Iterate GeneralFormats and call Remove(item) for each value, or RemoveAt(index) for a specific entry.

Does setting FieldFormat properties automatically refresh the field’s displayed text?

No — call Update() on the field after changing its Format properties so Result and DisplayResult reflect the new formatting.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation