ValueFormatProperty

Tool

You can refer to this tool in any formula, macro, module, or other script in Blockpad. You can use either its name or its full path:

  • To refer to it by name, use ValueFormatProperty (make sure the library Library.Tools.Properties is included with Include Libaries)
  • To refer to it by its full path, use Library.Tools.Properties.ValueFormatProperty

 

See also:

The Value Format property controls the display of values in spreadsheet cells, text labels, results of dynamic expression, and more. With Value Format, you can specify how numbers, dates, and boolean values are displayed.

Change the formatting for a value:
  1. Select the value.
  2. Click the Value Format icon in the toolbar.***
  3. Specify the format.
  4. Click OK.

          ***This may not appear in all top level frames.

Another option:

  1. Select the value.
  2. Open the properties window.
  3. Under Style, click Value Format.
  4. Specify the format.
  5. Click OK.

Formatting options

Formatting options fall into the following categories:

  • General
  • Number
  • Date/Time
  • Object
  • True/False

General is a catch-all for all types of values (numbers, text, date, etc). Number, Date/Time, and True/False apply to their respective value types - number, date, and boolean. The Object value format is not available right now, and will be for future use.

General

The General format typically shows values in the default format, depending on the context.

For numbers in value cells, the General format may round the number to show as many decimal places as will fit.

For dates and times, the General format displays the values according to the computer's settings.

If incompatible formatting is applied to a value, then the formatting will display as general/default. For example, if a date format is applied to a number, the number value format will reset to default.

Number

There are 4 basic options for number decimal display:

  • As many digits after decimal as will fit.
  • Fixed count of decimal places or significant figures.
  • Round to decimal places, with a minimum number of significant figures.
  • Fraction, with a maximum denominator specified.
More on fractions

When Blockpad displays a number as a fraction, it finds a numerator that corresponds to the denominator specified, then rounds that numerator to a whole number. If Reduce if possible is checked, then Blockpad will reduce the resulting fraction if possible.

For example, say the result of an equation is 0.3 and the value format is changed to fraction, with 16 as the maximum denominator. Blockpad will find a numerator that corresponds to 16: 0.3*16 = 4.8, and then round it to a whole number 4.8 -> 5. 5/16 can't be reduced, so 0.3 will display as 5/16 in this example.

Note that even when Blockpad displays a number as a fraction, it is stored as a decimal point of the original value, the value isn't changed. So in our example, even though 5/16 is shown, the value is still stored as 0.3. Notice the difference between A*10 and B*10 in the snapshot below.

0.3 vs 5/16

Priority units

You can specify priority units, which act like default units for the specified values. Any time a value has the same fundamental dimensions (length, mass, etc) as any priority unit, the value display is converted to the priority unit.

For example, if 3 m * 5 lbf is typed into a cell, and that cell has lbf*ft as a priority unit, then the result displayed is 49.213 lbf*ft.

Set priority units:
  1. Select the value or values.
  2. Open the value format window (see above).
  3. Select Number.
  4. Under Priority Units, click Add.
  5. Type in the unit in the box that appears. The dropdown suggests single units, but unit combinations may be typed in (N*m, in^2, etc).
  6. Click OK
  7. Click OK to exit the value format window.
Positive and negative number display options:
  • '-' for negative numbers
  • '-' for negative numbers, and '+' for positive numbers
  • Parentheses for negative numbers
Additional options may be specified:
  • Use scientific notation
  • Show grouping symbol
  • Show as percentage
  • Show currency as symbol
  • Hide units
  • Append '~' if rounded
  • Keep input format

Date/Time

When a date value is displayed with the general value format, it's displayed the same as the computer default. So, a date may display differently depending on the computer opening the file.

Custom date/time formats

The Date / Time format allows you to create custom formats for dates and times.

Apply custom date format:
  1. Select the value or values.
  2. Open the value format window (see above).
  3. Select Date/Time.
  4. Type in the custom date format using specifiers (see below) and normal characters (: , / etc).
  5. Click OK.

For custom date formats, Blockpad follows conventional shorthand for specifying date/time formatting. For more information, see the following link:

Below are some common specifiers for custom date formatting.

Specifier Description
dThe day of the month, from 1 through 31.
ddThe day of the month, from 01 through 31.
dddThe abbreviated name of the day of the week (for example, Mon).
ddddThe full name of the day of the week (for example, Monday).
hThe hour, using a 12-hour clock from 1 to 12.
hhThe hour, using a 12-hour clock from 01 to 12.
HThe hour, using a 24-hour clock from 0 to 23.
HHThe hour, using a 24-hour clock from 00 to 23.
[...]
Examples:

In the following examples, the date value 2019.05.28.13.30 is displayed in different custom formats.

Custom Format Display
yyyy-MM-dd 2019-05-28
MM/dd/yyyy 05/28/2019
yyyy-MM-dd hh:mm tt 2019-05-28 01:30 PM
HH:mm:ss ddd MMMM dd, yyyy 13:30:00 Tue May 28, 2019
hh:mm tt, dddd 01:30 PM, Tuesday

Object

For future use

True/False

True / False format allows any built-in or custom text to be specified each for a true or false value. Because Blockpad does not support number values as boolean values, if true / false format is applied to anything other than a boolean value, the default text will be shown.

Notes:
  • Value Format only changes how values are displayed, not how they are stored. So, if the number 4.3333333333 is displayed as 4.3, it is still stored as 4.3333333333.
  • When value formats are applied to arrays, the formatting applies to every member of the array.
    • If the array has mixed value types, then the format will apply to the appropriate value type, and the rest will have default formatting.
  • Using style rules, value formatting can be set for multiple objects or for all objects of a certain type (dynamic expressions, value cells, etc).
See also: