Formatting values in cells

TreeGrid v4.6

Basic

You can display values in cells in various formats according their types.

The supported formatting types are text, number and date. Text type you can use for column types “Text” and “Lines”, number for column types “Int” and “Float” and date for column type “Date”.

There also special formats for these types: Img, Link, List and Radio.

Column type can be set in <C> attribute Type. The type can be set also for singular cells by <I> attribute xxxType, where xxx is column name.

There are two possible formats:

Format to display values when are not edited. It can be set by <C> attribute Format or <I> attribute xxxFormat, where xxx is column name.

Format to edit values in <input type=text> HTML control. It can be set by <C> attribute EditFormat or <I> attribute xxxEditFormat, where xxx is column name.

If you want to add HTML formatting before and after cell value, use cell attributes HtmlPrefix and HtmlPostfix instead of Format attribute.

In HTML codes avoid the tags <U> and <CENTER> to better compatibility with TreeGrid.

Formatting text

This format is used for column types of “Text” and “Lines”.

Syntax: |LetterType|Prefix|Postfix|Search|Flags|Replace

‘|’ is any character not contained in any section to separate section values.

‘LetterType’ is number specifies case conversion: 0 – none, 1 – lowercase, 2 – uppercase, 3 – locale lowercase, 4 – locale uppercase

‘Prefix’ is string added before value

‘Postfix’ is string added after value

‘Search’ is RegExp string to replace it for ‘Replace’ string. This runs before LetterType conversion. ‘Flags’ are flags for RegExp, any of ‘g’, ‘i’, ‘m’.

In Prefix and Postix don’t use HTML tags, use rather cell attributes HtmlPrefix and HtmlPostfix instead. Prefix and Postfix are appended also when sorting and filtering.

In Prefix and Postfix you can use HTML tags if set <Cfg NoFormatEscape=’1’>. The HTML tags can be set in Format only, not in EditFormat. The value itself is always escaped, after replacing search.

If you use Prefix and/or Postfix in EditFormat set also appropriate EditMask to not let user to change Prefix and Postfix parts, because Prefix and Postfix are stripped from edited value only if are exactly the same as original.

Formatting numbers

This format is used for column types of “Int” and “Float”.

This format string uses almost the same formatting as Microsoft .NET System.Single.ToString (string format) function.

Format string can be one letter as standard format or more letters as user format.

Standard format

Standard format is one letter format. This format loads user format from file Text.xml, tag <Format>, attributes “n..”

“g” General (ng = "0.######" , ngg = "0.###### E+00"), for numbers under 1e10 uses ng, above uses ngg.

“f” Fixed (nf = "0.00")

“c” Currency (nc = "$###########0.00")

“p” Percent (np = "0.00%")

“r” Rounded (nr = "0.0000", nrg = "0.0000 E+00"), for numbers under 1e10 uses nr, above uses nrg.

“e” Scientific (ne = "0.000000 E+000")

User format

User format can contain any characters but only few have special meaning and other are written into output without any change.

0 Place for a digit, displays digit or 0

# Place for a digit, displays digit or nothing if there are no more digits.

. (Dot) Decimal separator. Displays decimal separator defined in file Text.xml, tag <Format>, attribute DecimalSeparator. (dot by default).

Can be only used only once.

, (Comma) This character has two meanings:

If this is placed between any digits characters (‘0’ or ‘#’) left to decimal separator,

there will all three digits separated by thousand separator defined in file Text.xml, tag <Format>, attribute GroupSeparator. (comma by default).

Example: Val = “123456.789”, Format = “,0.00” => Result = “123,456.79”

If this is placed between last digit and decimal separator (or to the end if decimal separator is not used),

the value will be divided by 1000. There can be more commas to divide more times.

Example: Val = “123456.789”, Format = “0,,.00” => Result = “0.12”

% Place for ‘%’ character (it is defined in file Text.xml, tag <Format>, attribute Percent). If it is present, the number is also multiplied by 100.

E, e, E-, E+, e-, e+ Result will use exponential notation. To this location is placed ‘E’ or ‘e’ letter followed by digits of exponent.

If used exponential notation, the number of digits before decimal separator is given by count of all digit places (‘0’ or ‘#’) before decimal separator.

This letter must be followed by number digit places (‘0’ or ‘#’) to specify number of exponent digits.

E or e specifies case of E letter, E+ uses sign + for positive exponents, E- and E uses no sign for positive exponents.

Example: Val = “123456.789”, Format = “000.000 E+00” => Result = “123.456 E+03”

Example: Val = “-0.0123456789”, Format = “:0.0000(E000)” => Result = “:-1.2346(E-002)”

; (Semicolon) There can be up to three different formats separated by semicolon.

The first format is used for positive numbers (and for 0 if third format missing), second for negative numbers (without minus sign) and third for 0.

\ Escape character, the next character is placed to output without any changes. Use to place format characters as 0 # . , E e + - \ ” ’

‘xxx’ or “xxx” Characters in quotes or double quotes are placed to output without any changes. Use to place format characters as 0 # . , E e + - \ ” ’

If you want add HTML tags before and after value, use rather cell attributes HtmlPrefix and HtmlPostfix instead of Format.

If you really need to place HTML tags into output (for example to use different HTML tags for positive and negative numbers), set <Cfg NoFormatEscape=’1’>. The HTML tags can be set in Format only, not in EditFormat.

Formatting date and time

This format is used for column types of “Date”.

This format string uses almost the same formatting as Microsoft .NET System.DateTime.ToString (string format) function.

Format string can be one letter as standard format or more letters as user format.

Format determines showing date, time or both. If column has “Date” format and is editable there will be displayed date button to set dates. For time values is not useful and is better to hide it by <C Button=’None’>.

Standard format

Standard format is one letter format. This format loads user format from file Text.xml, tag <Format>, attributes “n..”

d Short date ("M/d/yyyy")

D Long date ("d. MMMM yyyy")

t Short time ("H:mm")

T Long time ("H:mm:ss")

f Long date + short time ("d. MMMM yyyy H:mm")

F Long date + long time ("d. MMMM yyyy H:mm:ss")

g Short date + short time ("M/d/yyyy H:mm")

G Short date + long time ("M/d/yyyy H:mm:ss")

m, M Day and month ("d. MMMM")

s Sortable date time ("yyyy-MM-ddTHH:mm:ss")

u Universal sortable date time ("yyyy-MM-dd HH:mm:ssZ")

There are more standard formats with fixed meaning that cannot be changed in Text.xml.

r, R RFC1123 for example: Tue, 13 Jan 2004 18:12:34 GMT

y, Y Month and year for example: January 2004. For month name uses the attribute LongMonthNames2 (from file Text.xml, tag <Format>)

LongMonthNames2 could contain noun’s first case if the language supports it.

U Universal date time for example: 13. January 2004 17:12:34. This date time is converted to GMT !

User format

User format can contain any characters but only few have special meaning and other are written into output without any change.

: Place for time separator, defined in file Text.xml, tag <Format>, attribute TimeSeparator. (colon by default).

/ Place for date separator, defined in file Text.xml, tag <Format>, attribute DateSeparator. (slash by default).

d Month days 1 – 31

dd Month days 01 – 31

ddd Weekdays Su – Sa

dddd Weekdays Sunday – Saturday

M Month 1 – 12

MM Month 01 – 12

MMM Month Jan – Dec

MMMM January – December

y Year 0 – 99

yy Year 00 – 99

yyyy Year 0000 – 9999

h Hours 1 – 12

hh Hours 01 – 12

H Hours 0 – 23

HH Hours 00 – 23

m Minutes 0 – 59

mm Minutes 00 – 59

s Seconds 0 – 59

ss Seconds 00 – 59

t First letter of AM/PM designator, by default A or P.

tt AM/PM designator, by default AM or PM. Defined in file Text.xml, tag <Format>, attributes AMDesignator and PMDesignator.

z Timezone hours -12, +0, +13

zz Timezone hours -12, +00, +13

zzz Timezone hours and minutes, -12:00, +0:00, +13:00

If you want add HTML tags before and after value, use rather cell attributes HtmlPrefix and HtmlPostfix instead of Format.

If you really need to place HTML tags into output (for example to use HTML tags for one part of date only), set <Cfg NoFormatEscape=’1’>. The HTML tags can be set in Format only, not in EditFormat.

Formatting images

This format is used for column types of “Img”.

Syntax: |UrlPrefix|UrlPostfix|HtmlPrefix|HtmlPostfix|LinkPrefix|LinkPostfix|BaseUrlType

‘|’ is any character not contained in any section to separate section values.

‘UrlPrefix’ is string added before source url

‘UrlPostfix’ is string added after source url

‘HtmlPrefix’ is html code added before image

‘HtmlPostfix’ is html code added after image

‘LinkPrefix’ is string added before link url

‘LinkPostfix’ is string added after link url

‘BaseUrlType is integer type, if BaseUrl (from <Cfg> tag) is added before urls, 0 – no, 1- before source, 2 – before link, 3 – before both

This format is used for editing of column types of “Img”. Default is “|0|1”

Syntax: |line|src|extents|link

‘|’ is any character not contained in any section to separate section values.

‘line’ = 0 to edit all at one line, 1 to edit at more lines if needed, 2 to edit every value (src,extents,link) at one line

‘src’ = 1 to display and edit source

‘extents’ = 1 to display and edit extents (left, top, width, height)

‘link’ = 1 to display and edit link

Formatting links

This format is used for column types of “Link”.

Syntax: |UrlPrefix|UrlPostfix|HtmlPrefix|HtmlPostfix|BaseUrlType

‘|’ is any character not contained in any section to separate section values.

‘UrlPrefix’ is string added before link url

‘UrlPostfix’ is string added after link url

‘HtmlPrefix’ is html code added before link text

‘HtmlPostfix’ is html code added after link text

‘BaseUrlType’ is integer type, if BaseUrl (from <Cfg> tag) is added before url, 0 – no, 1- yes

This format is used for editing of column types of “Link”. Default is “|0|1”

Syntax: |line|url|link

‘|’ is any character not contained in any section to separate section values.

‘line’ = 0 to edit all at one line, 1 to edit at more lines if needed, 2 to edit every value (url,text) at one line

‘url’ = 1 to display and edit link url

‘text’ = 1 to display and edit link text

Formatting lists

This format is used for column types of “List”.

Syntax: |BaseFlags|BasePrefix|BasePostfix|Reserved|ItemPrefix|ItemPostfix|Search|Flags|Replace|Reserved|... |ItemNPrefix|ItemNPostfix|NSearch|NFlags|NReplace|NReserved

‘|’ is any character not contained in any section to separate section values.

‘BaseFlags’ is bit array of main flags

1 does not insert ItemPrefix before the first item and ItemNPostfix after the last item

2 escape HTML code in item value

‘BasePrefix’ is HTML code added to the beginning

‘BasePostfix’ is HTML code added to the end

‘ItemPrefix’ is HTML code added in front of every item

‘ItemPostfix’ is HTML code added after every item

‘Search’ is RegExp string to replace it for ‘Replace’ string, for every item. ‘Flags’ are flags for RegExp, any of ‘g’, ‘i’, ‘m’.

‘Reserved’ is not use yet

If there are more sequences of ItemPrefix, Postfix, ..., the values are used for items in order. For example if there are three sequences, the first sequence will be used for the first, the fourth and the seventh item, the second sequence for the second, the fifth, ...

Formatting radio buttons

This format is used for column types of “Radio”.

Syntax: |BaseFlags|BasePrefix|BasePostfix|Reserved|ItemPrefix|ItemPostfix|Item0|Item1|...|ItemN

‘|’ is any character not contained in any section to separate section values.

‘BaseFlags’ is bit array of main flags

0 to show all items at one line, 1 to split items to more lines if needed, 2 to show every item at one line

4 display text on the left, by default is on the right

8 all radio buttons can be unchecked

16 more radio buttons can be checked. In this case the value is bit mask of all radio buttons’ values

So the first radio is 0 or 1, the second 0 or 2, third 0 or 4, fourth 0 or 8 and so on.

32 show checkboxes instead of radio buttons

Updates

4.0

Added formatting images and links

Added formatting lists

4.0.3

Added BaseUrlType flag to Img and Link types

4.1

Added formatting radio buttons

4.2

Added information about HtmlPrefix and HtmlPostfix

4.4

Updated base flags of Radio buttons (16,32)

4.6

Updated Date format, Timezone info