Format strings are currently used in attributes. Each type and line item within an object can specify a format string for the value. Currently, masked edit controls do not work with these format strings, though there is a provision in the format string format to work with a masked edit control.
Certain uses of format strings might be:
Formatting a phone number with parentheses for the area code and a hyphen after the NXX number where the value 5855551234 might be how a number is stored, but it is displayed as: (585) 555-1234.
Changing the format of negative numbers from –123 to (123).
Or, turning negative numbers red: (123).
All format strings share a general syntax. This syntax is used to define different parts of the format string. Each part within a format string is actually evaluated with respect to the type of data (e.g. string, int, decimal, etc…) that it is attempting to format.
Below is the general syntax of a format string:
[…]Default_f_item;{condition_0}[hint_0_0;…; hint _0_i]f_item_0;…;{condition_n}[…] f_item_n
This format string looks complicated, but it truly very simple to use, and understand. Once a few examples have been shown, it should become apparent what each section means.
A short explanation of each the general structure is below:
The format string is made up of multiple parts separated by semicolons.
Each of these parts is used in a different case.
The conditions inside the {}'s are evaluated as InfoScript and used to determine the correct format to use.
The first format listed (called Default_f_item in the syntax) never has a condition associated with it. This default format is only used if no other formats apply. Also, this default format will be used in conjunction with a masked edit control at some time in the future.
Each format item is dependent upon the type of the data, and is described in later sections how to use these format items in the context of each different type.
The hint sections are also InfoScript, used to assign hints to the format. The hints are things like, color and font style. The exact hints currently supported are detailed in later sections.
Condition Syntax
In general, the condition is evaluated as an InfoScript expression, with the additional knowledge that the symbol 'value' is used to represent the value being displayed.
Some examples of this might be:
{value < 0}
To fire on negative values, or
{value.Length > 10}
To fire on strings whose length is greater than 10.
Format Item Syntax
Format items have some similarities. In general any character not defined can be used to insert that character as a literal in the string. Also, the backslash character (\) is generally used as an escape character to allow the insertion of literals that are used in the format item. For instance if the pound sign is used in the format item to mean a digit, to insert a pound sign into the string use an escaped pound sign (\#)
String Item Symbols
The following table defines the characters used to when formatting strings:
Char | Explanation |
|---|---|
@ | Represents a character that must be there. If no character exists, this inserts a space into the output string. |
& | Represents a character that may be there. If no character exists, this inserts nothing into the output string. |
L | Similar to '&' but displays the character as a lowercase character. |
U | Similar to '&' but displays the character as an uppercase character. |
Integer Item Format
The following table defines the characters used when formatting integers:
Char | Explanation |
|---|---|
# | Represents a decimal digit that may exist. |
0 | Represents a decimal digit that displays as a 0 if it does not exist. |
X | Represents a hexadecimal digit that is a 0 if it does not exist. If it does, all hex letters are displayed as uppercase letters. |
x | Represents a hexadecimal digit that is a 0 if it does not exist. If it does, all hex letters are displayed as lowercase letters. |
H | Represents a hexadecimal digit that produces no output if it does not exist. If it does, all hex letters are displayed as uppercase letters. |
h | Represents a hexadecimal digit that produces no output if it does not exist. If it does, all hex letters are displayed as lowercase letters. |
- | Prints a negative sign (-) if the value is negative, nothing if it is non-negative. |
+ | Prints a negative sign (-) if the value is negative, or a positive sign (+) if it is non-negative. |
, | (comma) This value represents a digit separation. Usually used for thousands separation. This value only prints if there are digits to the left of the value. |
Decimal Item Format
The following table defines the characters used when formatting decimal numbers:
Char | Explanation |
|---|---|
# | Represents a decimal digit that may exist. |
0 | Represents a decimal digit that displays as a 0 if it does not exist. |
. | Represents the decimal point. There should only be one decimal point in the format item. |
E | Represents the scientific notation exponent. This will display as a capital E. There should only be one E or e in the format item. |
e | Similar to E. The only difference is that the exponent symbol is a lowercase e. |
, | (comma) This value represents a digit separation. It is only valid in the whole number part of the value. It will only display if there are digits remaining to the left of the separator. |
- | Prints a negative sign (-) if the value is negative, nothing if it is non-negative. This can be used both in the exponent and value parts of a scientific displayed number. |
+ | Prints a negative sign (-) if the value is negative, or a positive sign (+) if it is non-negative. This can be used both in the exponent and value parts of a scientific displayed number. |
Date Format Item
The following table defines the characters used to when formatting dates:
Specifier | Description |
|---|---|
d | Displays the current day of the month, measured as a number between 1 and 31, inclusive. If the day is a single digit only (1-9), then it is displayed as a single digit. |
dd | Displays the current day of the month, measured as a number between 1 and 31, inclusive. If the day is a single digit only (1-9), it is formatted with a preceding 0 (01-09). |
ddd | Displays the abbreviated name of the day for the specified value. |
dddd | Displays the full name of the day for the specified value. |
f | Displays seconds fractions represented in one digit. |
ff | Displays seconds fractions represented in two digits. |
fff | Displays seconds fractions represented in three digits. |
ffff | Displays seconds fractions represented in four digits. |
fffff | Displays seconds fractions represented in five digits. |
ffffff | Displays seconds fractions represented in six digits. |
fffffff | Displays seconds fractions represented in seven digits. |
g | Displays the era (A.D. for example) for the specified value. |
h | Displays the hour for the specified value in the range 1-12. The hour represents whole hours passed since either midnight (displayed as 12) or noon (also displayed as 12). If this format is used alone, then the same hour before or after noon is indistinguishable. If the hour is a single digit (1-9), it is displayed as a single digit. No rounding occurs when displaying the hour. For example, a value of 5:43 returns 5. |
hh | Displays the hour for the specified value in the range 1-12. The hour represents whole hours passed since either midnight (displayed as 12) or noon (also displayed as 12). If this format is used alone, then the same hour before or after noon is indistinguishable. If the hour is a single digit (1-9), it is formatted with a preceding 0 (01-09). |
H | Displays the hour for the specified value in the range 0-23. The hour represents whole hours passed since midnight (displayed as 0). If the hour is a single digit (0-9), it is displayed as a single digit. |
HH | Displays the hour for the specified value in the range 0-23. The hour represents whole hours passed since midnight (displayed as 0). If the hour is a single digit (0-9), it is formatted with a preceding 0 (01-09). |
m | Displays the minute for the specified value in the range 0-59. The minute represents whole minutes passed since the last hour. If the minute is a single digit (0-9), it is displayed as a single digit. |
mm | Displays the minute for the specified value in the range 0-59. The minute represents whole minutes passed since the last hour. If the minute is a single digit (0-9), it is formatted with a preceding 0 (01-09). |
M | Displays the current month, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is displayed as a single digit. |
MM | Displays the current month, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is formatted with a preceding 0 (01-09). |
MMM | Displays the abbreviated name of the month for the specified value. |
MMMM | Displays the full name of the month for the specified value. |
s | Displays the seconds for the specified value in the range 0-59. The second represents whole seconds passed since the last minute. If the second is a single digit (0-9), it is displayed as a single digit only. |
ss | Displays the seconds for the specified value in the range 0-59. The second represents whole seconds passed since the last minute. If the second is a single digit (0-9), it is formatted with a preceding 0 (01-09). |
t | Displays the first character of the A.M./P.M. designator for the specified value. |
tt | Displays the A.M./P.M. designator for the specified value. |
y | Displays the year for the specified value as a maximum two-digit number. The first two digits of the year are omitted. If the year is a single digit (1-9), it is displayed as a single digit. |
yy | Displays the year for the specified value as a maximum two-digit number. The first two digits of the year are omitted. If the year is a single digit (1-9), it is formatted with a preceding 0 (01-09). |
yyyy | Displays the year for the specified value, including the century. If the year is less than four digits in length, then preceding zeros are appended as necessary to make the displayed year four digits long. |
z | Displays the time zone offset for the system's current time zone in whole hours only. The offset is always displayed with a leading or trailing sign (zero is displayed as '+0'), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is displayed as a single digit with the appropriate leading sign. The setting for the time zone is specified as +X or –X where X is the offset in hours from GMT. The displayed offset is affected by daylight time. |
zz | Displays the time zone offset for the system's current time zone in whole hours only. The offset is always displayed with a leading or trailing sign (zero is displayed as '+00'), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is formatted with a preceding 0 (01-09) with the appropriate leading sign. The setting for the time zone is specified as +X or –X where X is the offset in hours from GMT. The displayed offset is affected by daylight time. |
zzz | Displays the time zone offset for the system's current time zone in hours and minutes. The offset is always displayed with a leading or trailing sign (zero is displayed as '+00:00'), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is formatted with a preceding 0 (01-09) with the appropriate leading sign. The setting for the time zone is specified as +X or –X where X is the offset in hours from GMT. The displayed offset is affected by daylight time. |
: | Time separator. |
/ | Date separator. |
Formatting Hints
The following items are available as formatting hints:
Hint | Explanation |
|---|---|
Color | A named color. This is used as a string in most cases: [Color:="Red"] |
Style | Style is a set of flag values that dictate how the font is printed. The following style selections are currently available:
|
Justification | Specifies the justification of the text. The following values are available:
|