Cformat

Updated March 2021; see History

The cformat parameter is made up of one or more of the following characters, which are used to determine how the column should be justified and sorted. Note that they do not cause the data in the column to be re-formatted. For example, if a column contains dates, it is up to the calling program to preformat them appropriately to match the cformat specification. (The only purpose of defining such a column as a date is to allow sorting to work properly.) The most generic and common type would be S (String).

Switch

Meaning

!

Preserve foreground color.

@

List hierarchy.

#

Numeric data, allows 0 - 9. Use "." and "-" to allow decimal points and minus signs.

\

Literal backslash.

.

(Decimal point) Use with # to allow numbers with decimal points. See Numeric data.

+

Added to T (Editable checkbox) extends the checkbox functionality.

++

Added to T (Editable checkbox) further extends the checkbox functionality.

-

(Minus sign) Use with # to allow numbers with minus signs. Negative numbers are automatically displayed in red. See Numeric data.

]

May be added to any column in a file-mode tree to force trailing blanks to be stripped before loading the cell. (This is automatic in array mode, but in file-mode, the blanks may be needed to preserve the interpretation of the returned selection string.)

=

Expand/Collapse State.

1, 8

Character Set allows you to specify ANSI/Latin1 or UTF8 at the column level.

3

3 state version of checkbox. When used in conjunction with either T or t allows the checkbox to have 3 states (0=unchecked, 1=checked, 2=indeterminate).

A

ASCII Sort.

B

Background cell color.

b

Background row color.

C

Row color.

c

Row color option

D

Standard Date Format.

d

Superceded by expanded capability of code D; retained only for backward compatibility. Date in dd-mon-yr format.

E

Column contains editable text.

f

Font definition column.

H

Hidden column.

h

Indicates a column with times in it. This acts like a string column except for sorting purposes, where any time format supported by IDTIM will be recognized and sorted accordingly.

I

(Capital i) Image column.

K

Keep column position (i.e. do not allow it to be reordered by the user). Needed (as an override) only when flags XTF_REORD set

L

Lock column—i.e., do not allow it to be resized by the user or by XTREE itself. Must be accompanied by Dspwid or Dspmin or else the column will become hidden.

l

(Lower case el). Combo Box. Previously called "list," hence the "l".

ll

(Lower case double el) Use in place of "l" for list substitution in a non-editable column or tree.

M

Allow embedded CRLFs.

m

Used with E to specify a multi-line edit, while retaining single-line display. For both multi-line edit and display, use M with E.

n

Causes empty cells to always sort to the bottom, regardless of whether sorting up or down. May be used with any column type. Added in build 961 of 17 July 06.

O

(Upper case "O") Indicates that this column is allowed to overflow into the next column (provided the next column contains the "o" option and the cell is empty.)

o

(Lower case "o") Indicates that an overflowing previous column may overwrite this column, provided the cell is empty. This setting is not just automatic based on the prior column, because of the possibility of the user reordering the columns at runtime. Note also that this could affect the layout of the returned item in the array parameter; so if it is critical to you that all spaces be preserved in that line, don't use this code.

P

The First Position Reserved option may be used with editable cells to indicate that the first position is reserved for either a space (editable) or a "|" (not editable).

R

Editable radio button.

r

Non-editable radio button. Just like t (which see for details about the column data format) except for the appearance (a circle with a dot in it rather than a square with a checkmark or "tick").

S

String data (left justified by default).

s

Defines the column as being capable of referencing the List. Similar in concept to B (Background cell color) in that it reserves the first character of each cell in the column for the index letters that associate the cell with one of the predefined lists.

ss

Use in place of "s" for list substitution using a shared list in a non-editable column or tree.

T

Editable checkbox. Also see + above.

t

Non-editable checkbox.

tt

Acts like "t" , but instead of always displaying in dim intensity, instead uses the same formula based on the value of the cell as with editable checkboxes. In other words, by default, "tt" checkboxes display in normal intensity; to force individual checkboxes to display as dim, add +4 to the cell value.

U

Application-editable only.

u

Read-only editable.

uu

Works like "u" but displays only a frame around the cell rather than overlaying the cell with an edit or combo control. This is just an aesthetic variation. Note that "uu" automatically exits on Enter, rather than acting like Tab, as it does in most other cell navigation situations. The theory here is that uu is mainly intended for people who prefer the keyboard to the mouse, for whom Enter would be the most natural way to "select" (i.e. exit from) the current cell.

W

Auto-wrap columnar data onto multiple lines. See XTR.ITEMLINES and Comments in Allow embedded CRLFs. Sample image here.

X

Conditional validation.

x

Unconditional validation.

Z

Same as # (numeric) except that it overrides a Mask, causing zero-value cells to display as blank. S has the same zero-blanking mask override, but Z columns use the numeric sort rather than the natural sort.

Left justify column (default).

|

Center justify column. This applies during editing, as well as for display.

Right justify column. Note that in file mode, this causes the trailing blanks for this column to be stripped, which affects the return data. See the flags option XTF_FILANS. This applies during editing, as well as for display.

^

Causes sort to be case insensitive. Note that whether case sensitive or not, the collating sequence is based on the Windows locale and not the LDF. Added in build 961 of 17 July 06.

 

(blank) No Strip.

_

(underscore) May be used with editable columns to cause the edit cell to shrink to fit only the number of allowed characters (so as to not give the user an initial false impression of the number of allowed characters). This will probably only be reasonable when a fixed pitch font is used.

 

History

2020 October, A-Shell 6.5.1692:  Add Z option