com.ur.urcap.api.contribution.driver.general.userinput

Interface CustomUserInputConfiguration

public interface CustomUserInputConfiguration

This interface handles registration of custom user inputs (typically for device configuration in an installation node).
After all user inputs have been registered and the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method) has been exited, an UI with corresponding UI elements (that allows the end user to configure the settings) will be generated.
The order in which user inputs (including fillers and texts) are registered will be the order in which elements are displayed in the UI. The order is similar to adding cells to a HTML table, i.e. row-based adding, so the first element is added in the first row and first column, the second element is added in the first row and second column. The third element will be in the second row and first column and so on.
A total maximum of 10 user input elements and/or non-user input UI elements (such as text components and fillers) can be defined. Registering more elements will throw a TooManyUserInputsRegistered exception, except for setting the description text (using the setDescriptionText(String) method).
Labels are all limited in space. Text which is too long, will automatically be truncated with 3 dots accordingly in order to fit within the space provided.
The id identifier parameter of all the user input registration methods must be unique and constant over time and versions of the driver URCap as this is used for persistence of user input values.

Since:

1.8.0

Method Summary

Modifier and Type	Method and Description
void	addFiller() Add a filler element to control/group layout.
TextComponent	addText(String label, Icon icon, String text) Add a label, an icon and an associated text.
TextComponent	addText(String label, String text) Add a label and an associated text.
<T> T	deprecateUserInput(UserInput<T> userInput) Deprecate a registered user input that was used in an older version of the driver URCap to handle backwards compatibility between driver URCap versions.
BooleanUserInput	registerBooleanInput(String id, String label, boolean initialSelection) T Request a boolean-based user input where the end user can check/uncheck a checkbox.
<T> SelectableUserInput<T>	registerComboBoxInput(String id, String label, String undefinedSelection, List<T> elements, ElementResolver<T> resolver) Request a combo box user input with a static list of elements (i.e.
DoubleUserInput	registerDoubleInput(String id, String label, String unit, double initialValue, double minValue, double maxValue) Request a user input where the end user can enter a double (a decimal number) through a number input field.
IntegerUserInput	registerIntegerInput(String id, String label, String unit, int initialValue, int minValue, int maxValue) Request a user input where the end user can enter an integer through a number input field.
StringUserInput	registerIPAddressInput(String id, String label, String initialIPAddressStr) Request a string-based user input where the end user can enter an IP-address through a text input field.
<T> SelectableUserInput<T>	registerPreselectedComboBoxInput(String id, String label, T initialSelection, List<T> elements, ElementResolver<T> resolver) Request a combo box user input with a static list of elements (i.e.
StringUserInput	registerStringInput(String id, String label, String initialText) Request a user input where the end user can enter a string through a text input field.
void	setDescriptionText(String text) Set a description text displayed in a dedicated section above the first registered user input.

Method Detail

setDescriptionText

void setDescriptionText(String text)

Set a description text displayed in a dedicated section above the first registered user input. The description allows roughly up to 4 full lines of text (undecorated). Text which is too long, will simply be cut-off without proper truncation support.

Parameters:

text - the description text, not null.

Throws:

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

registerStringInput

StringUserInput registerStringInput(String id,
                                    String label,
                                    String initialText)

Request a user input where the end user can enter a string through a text input field.

Parameters:

id - the unique identifier for the input, not null nor an empty string. Must be unique and constant over time and versions of the driver URCap as this is used for persistence of user input values.

label - the text displayed in front of the text input field, not null. The text will automatically be truncated (with 3 dots) when text is too long.

initialText - the initial (default) text displayed in the text input field field if the user has not yet entered a string, not null

Returns:

a user input instance used for retrieving the string values entered by the end user as well as optionally setting a value change listener and/or adding a custom error input validator

Throws:

TooManyUserInputsRegistered - if adding this user input will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

IDAlreadyDefined - if a different user input previously has been registered with the same id identifier

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

registerIPAddressInput

StringUserInput registerIPAddressInput(String id,
                                       String label,
                                       String initialIPAddressStr)

Request a string-based user input where the end user can enter an IP-address through a text input field. The user input accepts any IPv4 address (ensuring the correct address format).

Parameters:

id - the unique identifier for the input, not null nor an empty string. Must be unique and constant over time and versions of the driver URCap as this is used for persistence of user input values.

label - the text displayed in front of the text input field, not null. The text will automatically be truncated (with 3 dots) when text is too long.

initialIPAddressStr - the initial IP address string (default) displayed in the text input field if the user has not yet entered an IP address, not null

Returns:

a user input instance used for retrieving the IP address string values entered by the end user as well as optionally setting a value change listener and/or adding a custom error input validator

Throws:

TooManyUserInputsRegistered - if adding this user input will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

IDAlreadyDefined - if a different user input previously has been registered with the same id identifier

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

registerBooleanInput

BooleanUserInput registerBooleanInput(String id,
                                      String label,
                                      boolean initialSelection)

T Request a boolean-based user input where the end user can check/uncheck a checkbox.

Parameters:

id - the unique identifier for the input, not null nor an empty string. Must be unique and constant over time and versions of the driver URCap as this is used for persistence of user input values.

label - the text displayed in front of the checkbox, not null. The text will automatically be truncated (with 3 dots)when text is too long.

initialSelection - the initial (default) state of the checkbox if the user has not yet altered it. A true value corresponds to the checked state and false corresponds to the unchecked state.

Returns:

a user input instance used for retrieving boolean values selected by the end user as well as optionally setting a value change listener and/or adding a custom error input validator

Throws:

TooManyUserInputsRegistered - if adding this user input will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

IDAlreadyDefined - if a different user input previously has been registered with the same id identifier

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

registerIntegerInput

IntegerUserInput registerIntegerInput(String id,
                                      String label,
                                      String unit,
                                      int initialValue,
                                      int minValue,
                                      int maxValue)

Request a user input where the end user can enter an integer through a number input field.

Parameters:

id - the unique identifier for the input, not null nor an empty string. Must be unique and constant over time and versions of the driver URCap as this is used for persistence of user input values.

label - the text displayed in front of the number input field, not null. The text will automatically be truncated (with 3 dots) when text is too long.

unit - the text for the unit of the input displayed after the number input field, not null. Pass an empty string if the input is has no unit.

initialValue - the initial (default) value displayed in the number input field if the user has not yet entered a value

minValue - the minimum value allowed to be entered

maxValue - the maximum value allowed to be entered

Returns:

a user input instance used for retrieving the values entered by the end user as well as optionally setting a value change listener and/or adding a custom error input validator

Throws:

TooManyUserInputsRegistered - if adding this user input will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

InvalidUserInputRange - if minValue > maxValue or initialValue is outside the range defined by minValue and maxValue.

IDAlreadyDefined - if a different user input previously has been registered with the same id identifier

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

registerDoubleInput

DoubleUserInput registerDoubleInput(String id,
                                    String label,
                                    String unit,
                                    double initialValue,
                                    double minValue,
                                    double maxValue)

Request a user input where the end user can enter a double (a decimal number) through a number input field.

Parameters:

id - the unique identifier for the input, not null nor an empty string. Must be unique and constant over time and versions of the driver URCap as this is used for persistence of user input values.

label - the text displayed in front of the number input field, not null. The text will automatically be truncated (with 3 dots) when text is too long.

unit - the text for the unit of the input displayed after the number input field, not null. Pass an empty string if the input is has no unit.

initialValue - the initial (default) value displayed in the number input field if the user has not yet entered a value

minValue - the minimum value allowed to be entered

maxValue - the maximum value allowed to be entered

Returns:

a user input instance used for retrieving the values entered by the end user as well as optionally setting a value change listener and/or adding a custom error input validator

Throws:

TooManyUserInputsRegistered - if adding this user input will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

InvalidUserInputRange - if minValue > maxValue or initialValue is outside the range defined by minValue and maxValue.

IDAlreadyDefined - if a different user input previously has been registered with the same id identifier

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

registerPreselectedComboBoxInput

<T> SelectableUserInput<T> registerPreselectedComboBoxInput(String id,
                                                            String label,
                                                            T initialSelection,
                                                            List<T> elements,
                                                            ElementResolver<T> resolver)

Request a combo box user input with a static list of elements (i.e. the combo box content can not be updated after registration) of a proprietary (custom) type with one of the elements pre-selected.

Type Parameters:

T - The (generic) type parameter for the method representing the type of elements selected by the user

Parameters:

id - the unique identifier for the input, not null nor an empty string. Must be unique and constant over time and versions of the driver URCap as this is used for persistence of user input values.

label - the text displayed in front of the combo box, not null. The text will automatically be truncated (with 3 dots) when text is too long.

initialSelection - the initial default selection if the user has not yet altered it.

elements - the elements to be selectable in the combo box, not null

resolver - a custom resolver responsible for correctly identifying each element in the combo box, not null

Returns:

a user input instance used for retrieving values selected by the end user as well as optionally setting a value change listener

Throws:

ElementListCannotBeEmpty - if elements is an empty list

TooManyUserInputsRegistered - if adding this user input will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

IDAlreadyDefined - if a different user input previously has been registered with the same id identifier

DuplicateElementID - if the ElementResolver.getId(Object) method does not return a unique identifier for all elements in the elements list.

InvalidSelection - if the initialSelection element is not in the elements list, i.e. the resolved identifier of the initialSelection element (returned by ElementResolver.getId(Object)) is not equal to the resolved identifier of any of the elements in the elements list.

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

registerComboBoxInput

<T> SelectableUserInput<T> registerComboBoxInput(String id,
                                                 String label,
                                                 String undefinedSelection,
                                                 List<T> elements,
                                                 ElementResolver<T> resolver)

Request a combo box user input with a static list of elements (i.e. the combo box content can not be updated after registration) of a proprietary (custom) type.

The initial selection is a string which by definition is not a valid selection. The string should guide the user to make a correct selection, i.e. describe what action to do or what is to be selected, e.g. "<Mounting>" or "Select".

The selection is not valid until the user changes it and will mark any program nodes for the driver contribution as undefined.

Type Parameters:

T - The (generic) type parameter for the method representing the type of elements selected by the user

Parameters:

id - the unique identifier for the input, not null nor an empty string. Must be unique and constant over time and versions of the driver URCap as this is used for persistence of user input values.

label - the text displayed in front of the combo box, not null. The text will automatically be truncated (with 3 dots) when text is too long.

undefinedSelection - the initial default selection if the user has not yet altered it, not null. The string should guide the user to make a correct selection (i.e. describe what action to do or what is to be selected, e.g. "<Mounting>" or "Select").

elements - the elements to be selectable in the combo box, not null.

resolver - a custom resolver responsible for correctly identifying each element in the combo box, not null

Returns:

a user input instance used for retrieving values selected by the end user as well as optionally setting a value change listener

Throws:

ElementListCannotBeEmpty - if elements is an empty list

TooManyUserInputsRegistered - if adding this user input will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

IDAlreadyDefined - if a different user input previously has been registered with the same id identifier

DuplicateElementID - if the ElementResolver.getId(Object) method does not return a unique identifier for all elements in the elements list.

InvalidSelection - if the initialSelection element is not in the elements list, i.e. the resolved identifier of the initialSelection element (returned by ElementResolver.getId(Object)) is not equal to the resolved identifier of any of the elements in the elements list.

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

addText

TextComponent addText(String label,
                      String text)

Add a label and an associated text. This can be used for, e.g. displaying status information for the end user.

Parameters:

label - the text displayed in front of the text itself, not null. The text will automatically be truncated (with 3 dots) when text is too long.

text - the text, not null. The text will automatically be truncated (with 3 dots) when text is too long.

Returns:

a text component instance with the option of updating the text

Throws:

TooManyUserInputsRegistered - if adding this UI element will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

addText

TextComponent addText(String label,
                      Icon icon,
                      String text)

Add a label, an icon and an associated text. This can be used for, e.g. displaying status information for the end user.

Supports 24x24 pixels icons for CB3 robots and 30x30 pixel icons for e-Series robots. The provided icon will be scaled automatically, if necessary.

Parameters:

label - the text displayed in front of the text itself, not null. The text will automatically be truncated (with 3 dots) when text is too long.

icon - the icon displayed immediately in front of the text itself. Passing null is allowed and will clear the icon.

text - the text, not null. The text will automatically be truncated (with 3 dots) when text is too long.

Returns:

a text component instance with the option of updating the text and updating/clearing the icon

Throws:

TooManyUserInputsRegistered - if adding this UI element will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

addFiller

void addFiller()

Add a filler element to control/group layout. A blank space will be added to fill the column element.

Throws:

TooManyUserInputsRegistered - if adding this UI element will exceed the total maximum of 10 registered user inputs and/or non-user input UI elements (such as text components and fillers) allowed

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)

deprecateUserInput

<T> T deprecateUserInput(UserInput<T> userInput)

Deprecate a registered user input that was used in an older version of the driver URCap to handle backwards compatibility between driver URCap versions. The end user will no longer be able see the deprecated user input UI element or modify the value of it in this URCap version.

Deprecating a user input is useful when a previous version of the driver URCap had a need for the given user input, but the current version no longer needs it. This can for instance be relevant when the "format" of the user input needs to be changed in a new URCap version, e.g. a previous checkbox user input needs to be changed to a combo box user input. Using this method, the old user input value can be migrated/adapted to the new user input definition/format, so the end user's previously stored configuration is not lost.

Note: The user input to be deprecated still needs to be registered (prior to deprecation) in order to have access to the old value.
Note: After deprecating a user input, the old user input value will no longer be available for the driver URCap.
Note: Deprecating a user input must happen immediately after registering it.

Parameters:

userInput - the user input to deprecate

Returns:

the value entered or selected by the user prior to deprecation. This value can be used to adapt/migrate the old user input value to the new user input "format".

Throws:

CalledOutsideUserInputConfigurationPhase - when this method is called from outside the method scope of the Configuration phase (e.g. the GripperContribution.configureInstallation(com.ur.urcap.api.contribution.driver.general.userinput.CustomUserInputConfiguration, com.ur.urcap.api.contribution.driver.gripper.SystemConfiguration, com.ur.urcap.api.contribution.driver.general.tcp.TCPConfiguration, com.ur.urcap.api.contribution.driver.gripper.GripperAPIProvider) method)