Numeric input

Reference

For a more technical API reference, please see the following pages:

NumberField - decimal numbers

A NumberField is a generic numeric field that can contain numbers with decimals. It can be visualized as numerical input or slider variant:

import viktor as vkt


class Parametrization(vkt.Parametrization):
    number = vkt.NumberField('Insert a Number here')
    slider = vkt.NumberField('Adjust the Number', min=0, max=8, variant='slider')

The user input can be obtained through the params argument and can have the following values:

float: when user inputs a decimal number (e.g. 1.5)
int: when user inputs a whole number (e.g. 1)
None: when empty (not applicable to the slider variant)

Expand to see all available arguments

In alphabetical order:

default: a default value will be prefilled

number = vkt.NumberField('Insert a Number here', default=7.5)

description: add a tooltip with additional information

number = vkt.NumberField('Insert a Number here', description="This number represents the ...")

flex: the width of the field between 0 and 100 (default=33)

number = vkt.NumberField('Insert a Number here', flex=50)

max: when the user enters a value higher than the maximum boundary, the field is marked as invalid
```
number = vkt.NumberField('Insert a Number here', max=10)
```
See 'Setting min/max' for more information on setting a dynamic boundary.
min: when the user enters a value lower than the minimum boundary, the field is marked as invalid
```
number = vkt.NumberField('Insert a Number here', min=0)
```
See 'Setting min/max' for more information on setting a dynamic boundary.

name: defines the position of the parameter in the params

number = vkt.NumberField('Insert a Number here', name="n")  # obtained using params.n

num_decimals: defines the number of decimals shown in the interface

number = vkt.NumberField('Insert a Number here', num_decimals=2)

prefix: a prefix will be put in front of the ui name

number = vkt.NumberField('Insert a Number here', prefix="€")

step: stepping interval when clicking the increment / decrement buttons
```
number = vkt.NumberField('Insert a Number here', step=0.5)
```

suffix: a suffix will be placed behind the ui name

number = vkt.NumberField('Insert a Number here', suffix="mm")

variant: the field can be shown as slider, in this case specifying a min and max is required
```
number = vkt.NumberField('Adjust the Number', min=0, max=8, variant='slider')
```
note
The variants are ignored within a Table
visible: can be used when the visibility depends on other input fields
```
number = vkt.NumberField('Insert a Number here', visible=vkt.Lookup("another_field"))
```
See 'Hide a field' for elaborate examples.

IntegerField - whole numbers

An IntegerField is a numeric field that can contain integers only.

import viktor as vkt


class Parametrization(vkt.Parametrization):
    integer = vkt.IntegerField('Input an Integer')

The user input can be obtained through the params argument and can have the following values:

int: when user inputs a number (e.g. 1)
None: when empty

Expand to see all available arguments

In alphabetical order:

default: a default value will be prefilled

integer = vkt.IntegerField('Input an Integer here', default=7.5)

description: add a tooltip with additional information

integer = vkt.IntegerField('Input an Integer here', description="This number represents the ...")

flex: the width of the field between 0 and 100 (default=33)

integer = vkt.IntegerField('Input an Integer here', flex=50)

max: when the user enters a value higher than the maximum boundary, the field is marked as invalid
```
integer = vkt.IntegerField('Input an Integer here', max=10)
```
See 'Setting min/max' for more information on setting a dynamic boundary.
min: when the user enters a value lower than the minimum boundary, the field is marked as invalid
```
integer = vkt.IntegerField('Input an Integer here', min=0)
```
See 'Setting min/max' for more information on setting a dynamic boundary.

name: defines the position of the parameter in the params

integer = vkt.IntegerField('Input an Integer here', name="i")  # obtained using params.i

prefix: a prefix will be put in front of the ui name

integer = vkt.IntegerField('Input an Integer here', prefix="€")

step: stepping interval when clicking the increment / decrement buttons
```
integer = vkt.IntegerField('Input an Integer here', step=3)
```

suffix: a suffix will be placed behind the ui name

integer = vkt.IntegerField('Input an Integer here', suffix="mm")

visible: can be used when the visibility depends on other input fields
```
integer = vkt.IntegerField('Input an Integer here', visible=vkt.Lookup("another_field"))
```
See 'Hide a field' for elaborate examples.

Setting min/max

The min and max value of the field can be set using the min and max arguments respectively:

vkt.NumberField('X', min=0, max=10)  # also on IntegerField

When the user enters a value that exceeds these bounds, the fields are marked as invalid.

If the value for min or max needs to be calculated 'dynamically', one of the below methods can be used.

Depending on another field

If the constraint depends on another numeric field, the easiest solution is to use a Lookup:

import viktor as vkt


class Parametrization(vkt.Parametrization):
    param_x = vkt.NumberField('X')
    param_y = vkt.NumberField('Y', min=vkt.Lookup('param_x'))

In case of a nested parametrization structure, the dotted path should be used:

vkt.Lookup('tab.section.param_x')

When the target field cannot be found, a warning is logged in your terminal and the constraint is ignored.

Inside a DynamicArray

If the value for min or max depends on the result of another numeric field within a DynamicArray, a RowLookup can be used. Using the RowLookup, a field of a specific row within the array can be made dependent of another field within the same row:

import viktor as vkt


class Parametrization(vkt.Parametrization):
    array = vkt.DynamicArray('Array')
    array.param_x = vkt.NumberField('X')
    array.param_y = vkt.NumberField('Y', min=vkt.RowLookup('param_x'))

Using a function

The most generic way to dynamically set the min/max value is to use a callback function. Upon evaluation of the min or max constraint, the platform passes the params, entity_id, entity_name, and workspace_id (>= v14.7.1) to the custom function:

import viktor as vkt


def param_y_min(params, **kwargs):
    return params.param_x


class Parametrization(vkt.Parametrization):
    param_x = vkt.NumberField('X')
    param_y = vkt.NumberField('Y', min=param_y_min)

For constraints that have to be applied to fields within a DynamicArray, make sure that the callback function returns a list of the constraint values, one for each row in the array. The length of this list must be equal to the number of rows in the array, otherwise (a warning is logged and) the constraint is ignored:

import viktor as vkt


def param_y_min(params, **kwargs):
    return [row.param_x for row in params.array]


class Parametrization(vkt.Parametrization):    
    array = vkt.DynamicArray('Array')
    array.param_x = vkt.NumberField('X')
    array.param_y = vkt.NumberField('Y', min=param_y_min)

tip

All individual kwargs can be added explicitly in the signature if needed:

def param_y_min(params, entity_id, entity_name, workspace_id, **kwargs):
    ...

When the value for min/max depends on data from another entity, the entity_id can be used to navigate and obtain data using the SDK API.

Numeric input

NumberField - decimal numbers​

IntegerField - whole numbers​

Setting min/max​

Depending on another field​

Inside a DynamicArray​

Using a function​