FormCalc Locale and Picture Functions
Enable TXFAWidgetRuntimeOptions.ScriptOptions.EnableJavaScript to use these functions in general FormCalc events, calculate and validate scripts through the shipped QuickJS engine
Locale selection
The executing field inherits the nearest nonempty locale attribute from its ancestors; an empty chain selects the configured native Windows or Linux ICU locale
A document localeSet entry overrides native number/currency symbols, month/day/meridiem names and date/time/number patterns; missing values inherit system data, with en_US fallback for custom locale names
Locale identifiers accept underscore and hyphen spellings case-insensitively; computed names such as Concat("de", "_DE") resolve at execution time
Internal locale requests share the event deadline and permit 64 named lookups, 256 UTF-16 code units per identifier and 2 MiB of aggregate metadata; retries restore the JavaScript checkpoint, and committed session replay consumes recorded metadata without another provider call
Picture functions
| Function | Behaviour |
|---|---|
Format(picture, value, ...) | Formats values using date, time, datetime, num or text clauses; standard compound clauses format the same value, with an optional extension accepting corresponding value arguments |
Parse(picture, text) | Parses typed clauses, compound clauses or alternatives into ISO date/time text, decimal numeric text or text with literals removed |
Use date(de_DE){D. MMMM YYYY} for an explicit locale, num.currency for a locale style, and a vertical bar for alternatives; quoted literals and doubled apostrophes preserve literal characters
Date, time and datetime styles use the resolved default, short, medium, long or full patterns; the standard localeSet numeric pattern supplies both num.decimal and its integer part for num.integer
Date/time pictures support year, month, day, weekday names, 12/24-hour clocks, minutes, seconds, fractional milliseconds, meridiems and explicit GMT/UTC offsets; invalid dates such as February 30 return empty text
Numeric pictures support mandatory 9, optional z, space-padded Z, decimal/group separators, currency symbols and ISO currency codes, percentages, signs, parentheses, credit/debit suffixes and implied decimal radix
Text pictures support A for Unicode letters, O or 0 for Unicode alphanumeric characters, 9 for digits and X for Unicode code points, including supplementary characters
Advanced picture clauses add numeric scientific notation and retained fractional precision, ordinal and week dates, additional clocks, global character/whitespace symbols and compound input parsing
Null parameters return null; invalid pictures, invalid values or unavailable locales return empty text
target = Format("num(de_DE){z,zz9.99}", 1234.5)
target = Parse("date{MMM D, YYYY}", "Sep 1, 2002")
target = Format("date{YYYY-MM-DD} 'at' time{HH:MM}", "2024-03-15T13:45:09")Date and time functions
| Function | Parameters and result |
|---|---|
DateFmt(style=0, locale), TimeFmt(style=0, locale) | Return XFA patterns for default 0, short 1, medium 2, long 3 or full 4; invalid styles select default |
Date2Num(text, picture, locale) | Returns serial days with 1900-01-01 as day 1; omitted picture uses the locale default and also accepts ISO dates |
Num2Date(serial, picture, locale) | Formats serial days using the supplied or default locale date picture |
IsoDate2Num(text) | Parses compact or hyphenated ISO dates, including optional time suffixes |
IsoTime2Num(text), Time2Num(text, picture, locale) | Return milliseconds since GMT midnight plus 1; explicit offsets are applied and absent offsets use the current timezone |
Num2GMTime(serial, picture, locale), Num2Time(serial, picture, locale) | Format time serials 1 through 86400000 in GMT or the current timezone |
Date(), Time() | Return current date/time serials with recorded clock inputs during session replay |
Omitted Num2Date pictures now produce localised output; migrate callers that require ISO output to Num2Date(serial, "YYYY-MM-DD")
Units, encoding and text utilities
| Function | Parameters and result |
|---|---|
UnitType(measurement) | Recognises in, cm, mm, pt, pc and mp aliases; unrecognised units default to inches |
UnitValue(measurement, targetUnit="in") | Converts measurements with 72 points per inch, 12 points per pica and 1000 millipoints per point |
Encode(text, encoding="url"), Decode(text, encoding="url") | Support URL escaping, XML entities and HTML named/numeric entities with Unicode scalar validation |
Uuid(style=0) | Returns 32 hexadecimal digits or style 1 with hyphens, with version 4 and variant bits; replay uses recorded random inputs |
WordNum(value, style=0, locale) | Produces English number words, style 1 dollar amounts or style 2 dollars and cents; invalid numeric domains return an asterisk |
Current picture boundaries
Alternate eras, ideographic or full-width representations, localised digit alphabets, localised display-only pattern symbols and complete grouping policies remain separate targets; WordNum emits English words
The native scalar evaluator retains its existing ISO and finance functions; locale/picture functions require general execution
Lower-level APIs
TXFALocaleData, HPDFXFALoadLocale, HPDFXFALoadDocumentLocale and HPDFXFALocaleJavaScript expose Unicode locale metadata and safe engine serialisation
HPDFXFAExecuteJavaScriptEvent accepts TXFALocaleDataProvider for custom read-only metadata lookup