Date and Time Fields

Date and Time Fields

This guide shows how to work with the calendar-aware date and time field classes in Aspose.Words FOSS for .NET — FieldDate, FieldCreateDate, FieldPrintDate, and FieldSaveDate — which implement Word’s DATE, CREATEDATE, PRINTDATE, and SAVEDATE fields respectively. Each class derives from Field and implements IFieldWithCalendar; for the base Field object model itself (updating, unlinking, removing, and formatting any field), see the Working with Fields guide.

The Four Date and Time Field Classes

FieldDate implements the DATE field. FieldCreateDate implements CREATEDATE, the date the document was created. FieldPrintDate implements PRINTDATE, the date the document was last printed. FieldSaveDate implements SAVEDATE, the date the document was last saved. All four are subclasses of Field and implement IFieldCodeTokenInfoProvider and IFieldWithCalendar, so they share Field’s GetFieldCode(), Update(), Unlink(), Remove(), and formatting (Format) members alongside their own calendar switches described below.

Selecting a Non-Gregorian Calendar

Each of the four classes exposes UseLunarCalendar (bool) to render the result using the Hijri Lunar or Hebrew Lunar calendar, UseSakaEraCalendar (bool) for the Saka Era calendar, and UseUmAlQuraCalendar (bool) for the Um-al-Qura calendar. Set the corresponding property to true before calling Update() to have the field recalculate its result using that calendar system instead of the default Gregorian calendar.

FieldDate’s Application-Format Switch

FieldDate additionally exposes UseLastFormat (bool), which controls whether the field uses a format last used by the hosting application when a new DATE field is inserted. FieldCreateDate, FieldPrintDate, and FieldSaveDate do not expose this property.

Tips and Best Practices

• Set a calendar switch (UseLunarCalendar, UseSakaEraCalendar, or UseUmAlQuraCalendar) and then call Update() on the field — changing the property alone does not recalculate Result.
• Set only one calendar switch to true on a given field instance; combining more than one produces an ambiguous result.
• Use Field.Format (a FieldFormat, covered in the Field Result Formatting guide) alongside these calendar switches to also control the numeric or date/time formatting picture applied to the result.
• Pick the class that matches the semantic you need — FieldSaveDate and FieldPrintDate read timestamps recorded in the document, while FieldDate reflects whatever date the field is updated.

Common Issues

FAQ

What’s the difference between FieldDate and FieldCreateDate?

FieldDate implements the DATE field (recalculates to the current date each time it updates); FieldCreateDate implements CREATEDATE (the date the document was created).

How do I make a date field use the Hijri Lunar calendar?

Set UseLunarCalendar = true on the FieldDate, FieldCreateDate, FieldPrintDate, or FieldSaveDate instance, then call Update().

Which of the four classes tracks when a document was last saved?

FieldSaveDate, which implements the SAVEDATE field.

Do these classes support custom formatting pictures, not just calendar switches?

Yes — each exposes a Format property (FieldFormat) inherited from the base field infrastructure; see the Field Result Formatting guide for NumericFormat and DateTimeFormat.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation