format

2.6 format

You can define format resources in order to format strings in editable texts and tablefields.

A format resource connects a string as a format description with an optional format function which interprets the string.

Definition

{ export | reexport } format <Identifier> <formatSpec> | <variantDef>

formatSpec ::=
  <format string> [ <format function> ] ;

variantDef ::=
{
           0 : <formatSpec>
  [ <number> : <formatSpec> ]
}

If no format function is given, the format string is interpreted internally by the Dialog Manager. If a format function is given, it has to be defined as formatfunc (please see chapter “Format Function” in manual “Rule Language”).

Variants can be used, for example, to make adaptations to different languages.

The following format descriptions are permitted, if the Dialog Manager has to interpret the format string internally:

Empty string

If the format is an empty string, the input strings will not be formatted.

Input pattern

The following characters are available within the format string:

A	alphabetic characters
C	numbers and uppercase letters
H	hexadecimal digits
N	digits
U	alphabetic characters, only uppercase letters
X	any input permitted
9	digits (like N)
/	formatting character
,	formatting character
.	formatting character
-	formatting character
:	formatting character
Space (BLANK)	formatting character

The formatting characters are inserted into the display string for display and input. They are skipped during input and thus cannot be overwritten. After the input, they are not adopted in the contents string and are not available there.

Example

Time input:

.format "NN:NN:NN";

Input of 120300

Hidden formatting

If the format string starts with an "S", the contents string is displayed and edited invisibly.

The character following "S" is interpreted as a special sign for hiding. If no further character is following "S", "*" is chosen as hiding sign. Then, the following format strings are possible:

empty string
input pattern
numeric format

With hidden formatting, you can e.g. make a password input.

Example

.format "SxAAA";

allows the input of three characters which, however, are all displayed as "x".

Numeric format

allows the formatting of numbers. The format string has to be specified according to the following pattern (element in square brackets [ ] is optional, i.e. it may be left out):

% [<|>] [+|-] [ [0] 0] length [' [sepch] sepcount ] [ ( . | , ) [0] trail ]
[u|s] (b|d|f|h|o|x|X) [<|>] [+|-] [/(c[0]|p|t|z)+]

Meaning of the Various Elements

Formatzeichen	Zeichen	Bedeutung
%		Indicating initial character for numeric formats.
[<\|>]		Alignment with left margin:
	no entry	Padding with blanks before sign.
	>	Padding with blanks between sign and digits.
	<	No padding, left-justified.
[+\|-]		Leading sign:
	no entry	Display of negative sign only, if no trailing sign is defined.
	-	Display of negative sign only.
	+	Display of positive and negative sign.
[[0]0]		Display of leading zeros:
	no entry	No leading zeros are displayed.
	0	A single leading zero is displayed, if the integral part is zero.
	00	Displays zeros for all non-occupied digits of the integral part.
length		Overall number of digits (not counting special characters).
[' [sepch] sepcount ]		At each sepcount-position of the integral part a sepch-character or a ' if no sepch is specified is displayed (e.g. as thousands marker in digit grouping). If sepcount is 0 then 3 will be used by default.
[(.\|,) [0] trail]		Description of the fractional part: Defines either a point or a comma as decimal mark.
		trail defines the number of decimal places. If the optional zero is used, non-occupied places will be filled with zeros.
[u\|s]		Input of negative numbers:
	u	unsigned, no negative numbers permitted
	s	signed, negative numbers are permitted
(b\|d\|f\|h\|o\|x\|X)		Formatting signs indicating the number system:
	b	Binary numbers.
	d	Decimal numbers.
	f	Floating point values with decimal mark in the input string.
	h	Same as x.
	o	Octal numbers.
	x	Hexadecimal numbers with lowercase letters.
	X	Hexadecimal numbers with uppercase letters.
		Except when using the formatting sign f, the content string may contain no decimal mark. The decimal mark is only inserted into the display string for display and input.
[<\|>]		Alignment with right margin:
	no entry	Padding with blanks after sign.
	>	Padding with blanks between sign and digits.
	<	No padding, right-justified.
[+\|-]		Trailing sign:
	no entry	No display of sign.
	-	Display of negative sign only.
	+	Display of positive and negative sign.
[/(c[0]\|p\|t\|z)+]		Format modifier:
		The format behavior can be determined by specifying one or more modifiers. Default behavior: During input, the digits are shifted over the decimal mark. Empty strings are allowed as input and are different from zero. The decimal mark is always displayed, even if the content string is empty.
	c	Digit deleting mode: Deleting the very last digit in a string leads to an empty string and not to a string with the value 0. This modifier has no impact when it is combined with the z format modifier (zero-mode).
	c0	0-deletion-mode: When a string represents the numerical value 0 after an entry or a deletion, then the string will be replaced with an empty string. In 0-deletion-mode a content string can change to an empty string when only one digit not equal to 0 exists and this digit is deleted. Example: 7000.00 will be changed to an empty string after deleting the 7 by using the `Del` or `Backspace` key. This modifier has no impact when it is combined with the z format modifier (zero-mode).
	p	Point-mode: if the content string is empty, no decimal mark is displayed.
	t	Technical number input: the places before and after the decimal point are edited separately.
	z	Zero-mode: empty strings are converted to zeros, empty strings cannot be input, depending on the format, zeros may be displayed as empty string.

Remarks

Leading and trailing zeros are inserted into the display string only. They will not be taken into the content string, not even after the entry has been finished and therefore are not present in it.
Given a one-digit content string, this digit may not be situated rightmost within the formatted string. Rather it can be the first digit left of the comma, e.g. at technical number input.
In an entry field characters that are inserted into the display string by a format cannot be deleted using the Backspace or Del keys.

A sign inserted by a format can be altered using the + and - keys. In doing so + switches to a positive sign or retains it. Entering - toggles between positive and negative sign (just like multiplying by -1).

Regular Expression

Availability

Since IDM version A.06.02.g

A matching expression of the form "/ … /" is accepted in order to allow the content or input to be validated.

If the content does not match the pattern, an empty string is displayed or the input is prevented.

Examples

format FmtKommaZahl "/^(\\d+(\\.\\d*)?)?$/";

Permitted strings e.g. "", "1", "07654.321"
format FmtHexZahl "/^[abcdefABCDEF0123456789]*$/";

Permitted strings e.g. "", "AF4513c", "a", "7EF"
format FmtSpecial "/^([[:alpha:]]*\n\\d*\n[01]*)?$/";

Permitted strings e.g. "", "City\n999\n01", "Milwaukee\n53288\n01101110"