Data-Related Properties

The next set of properties generally apply to data controls (such as KBField and KBChoice), though again not all apply in all cases.

Row Count (rowcount)

This is not actually a property of a data control, but rather of the block which contains the data control, and specifies the number of rows of data which are displayed. Hence, it gives the number of instances of the data control which will appear.

If the value is zero, then the block will calculate the number of rows according to the block size and the block X- and Y-delta properties. As noted above, this check also includes any containers that are embedded in the block; the minimum value is chosen. If the value is still calculated as zero, then a single row will be displayed (so you might get a scrambled display, but at least something will appear!).

X and Y Spacing (dx, dy)

These are also properties of the block which contains a data control. If the block has the rowcount property set to zero, then these values are used for the spacing between controls, and hence affect the number of rows of data that are displayed in the block.

Where the rowcount is zero, and the block contains embedded containers, the same spacing values are used in the containers.

Default Value (defval)

If a row of data is saved to the server database and a data control has not been set, then the Default value will be used, if any. This is typically useful in a form to save the user having repeatedly enter the a common value. Note that this is completely independant of any column default value that may be provided by the server database itself.

Null OK (nullok)

This property should be set if it is OK for the data value to be empty when data is saved to the server database. If the property is not set then the user must enter some data.

This is also independant of any column not-null setting provided by the server database itself. However, where Rekall detects that a column is marked not-null in the server database it will check the control value whether this property is set or not.

Validator (evalid)

If this is not blank, then it is used as a regular expression against which user-entered data is checked. The regular expressions are those supported by Troll Techs QT library ( Rekall uses QT3.x regular expressions, even in versions which are built on top of QT2.x (that is, on KDE or Qtopia). ) . Note that as of this release, the expression is not anchored at either end.

Ignore Case (igncase)

Setting this property causes user-entered data validation to be case insensitive.

Read Only (rdonly)

If set then the user cannot alter the value, ie., it is for display only (although it can still be changed by a script). If you do set this option, then you might want to do something like change the text colour to give the user a hint.

Format (format)

The Format property is used to specify how the raw data from the server database is formatted for display.

The properties dialog will display a set of options that allow you to construct a valid format specification, although you can edit the format by hand. The format specification must match the type of data coming from the server database; again, the properties dialog will select the appropriate type for you. If you do run a form and the specified format is not applicable to the value (for instance, if a table column type has been changed) then the control will display something like Format?Date.

The simplest way to specify advanced formatting (for example, of dates and times, which uses the strftime style of description) is to use the properties dialog to generate the nearest and then to edit that. The table below lists the main format types.

Date Formats dates using strftime formatting. The time formats associated with strftime should not be used.
Time Formats times using strftime formatting. The date formats associated with strftime should not be used.
DateTime Again formats using strftime formatting; both date and time parts are value.
Fixed Used for fixed (integer) values. The format string uses printf formatting; the single argument to this is the integer value.
Float Used for floating point values. The format string uses printf formatting; the single argument to this is the double value.
Number The format string is similar to that used for formatting in another well-known database product, and is described below.
Currency This format attempts to format the value as a currency value. The format string is interpreted as a locale (eg., gb for the UK, de for Germany, and so forth), and is used to retrieve locale-specific formatting. If it cannot be found ( Which locales are available depends on which are supported and installed on your system. ) then a default is used. An empty format string means the current locale.

In the case of Number formatting, the format string can contain the following:

. Decimal point. Number is separated into whole and fractional parts.
0 Outputs a digit. This format character converts leading spaces to the digit zero, hence 134 formatted with 00000 would output as 00134.
# Outputs a digit, but supresses leading zeros. Hence 134 formatted with ####0 would output as 134.
$ Outputs the currency symbol for the current locale, falling back on $ itself if if cannot be determined.
\ Escapes the following character, which is output as is, hence \$ will output the dollar character and not the currency character for the current locale.
E Starts exponent part of number. Lower-case e can also be used.
" Starts quoted string; quoted string is output as-is.

In addition, a number format can be comprise of up to four sections, separated by a semi-colon ; character. If the value is null then the fourth section is used if present; if the value is zero the the third section is used if present; if the value is negative then the second section is used if present; otherwise, the first section is used. Null is treated as zero in this context.

Text Alignment (align)

This specifies text alignment in a simple text fields and in labels. The default is left, the alternatives are right and centered.

In addition, labels have the setting rich text, which uses the QT rich text formatting, essentially simple HTML. This allows effects like bolding and underlining; also, text will be wrapped to fit if neccessary.

Input Mask (mask)

The Input Mask property gives some control over text entry. The mask is a text string where the following characters are significant (note thay any other character stands for itself):

A An upper-case character. Lower-case will be converted
a A lower-case character. Upper-case will be converted
0 A digit
Z Zero or more optional upper-case characters. Lower-case will be converted
z Zero or more optional lower-case characters. Upper-case will be converted
9 Zero or more optional digits.
_ Any single character

Note that masks for options characters (Z, z and 9) must follow non-optional mask characters. For instance, for a decimal number which has at least two digits before, and at least two digits after, the decimal point, use the mask 009.009 (and not 900.900).

This area of Rekall is under development, so expect more mask functionality in future releases. This may require incompatible changes.

No Update (noupdate)

Setting this property stops Rekall using the value in the control to update the database when a record is saved (ie., it does not include the control in any insert or update SQL statement).

Rekall automatically treats controls this way if the display expression is not a column name, since trying to use a value which is (for example) the concatenation of two columns (such as a person's first name last name) does not make any sense. However, it is sometimes neccessary to prevent update event when the expression is a column name ( Leaping ahead rather, this is particularly useful in hidden controls in reusable components which need to retrieve some column from the database which might be already displayed in another control. Setting the no update property prevents Rekall generating insert and update SQL queries that refer to the same column more than once. ) .