mirror of https://github.com/nymea/nymea.git
399 lines
14 KiB
Plaintext
399 lines
14 KiB
Plaintext
/*!
|
|
\page paramtypes-ui-elements.html
|
|
\title Paramtypes and the coresponding UI elements
|
|
|
|
On this page you can find different examples how a \l{ParamType} can be displayed in a client application.
|
|
The images used for this examples were created with the Ubuntu SDK and are ment as an example, not as a directive.
|
|
|
|
Depending on where a \l{ParamType} will be read there are different methods how to present them to the user.
|
|
If you have an \l{Action}, you can check out the \e Actions list to get a feeling how an \l{ActionType} can
|
|
be interpreted.
|
|
|
|
If a user has to fill out a list of \l{Params}{Param} for a \l{Device} setup or configuration, some examples can be found
|
|
in the \e Params list.
|
|
|
|
\chapter Actions
|
|
\section2 Without params
|
|
|
|
A \l{Device} \l{Action} without \l{Param}{Params} can be represented by a single button.
|
|
The button contains the name of the \l{ActionType}.
|
|
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "Action name",
|
|
"paramTypes": []
|
|
}
|
|
\endcode
|
|
|
|
\image ui/action-without-params.png
|
|
|
|
\section2 With one \tt Bool param
|
|
|
|
A \l{Device} \l{Action} with a \tt{bool} \l{Param} which has no corresponding state value can be represented with two buttons.
|
|
One button for \tt{true}, one button for \tt{false}. The button name can be created with the \tt {paramType name + On/Off}.
|
|
The description of the button could be the name of the \l{ActionType}.
|
|
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "Set power",
|
|
"paramTypes": [
|
|
{
|
|
"name": "power",
|
|
"type": "Bool",
|
|
"defaultValue": false
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/action-bool-without-state.png
|
|
|
|
|
|
\section2 With one \tt Bool param and corresponding state
|
|
|
|
A \l{Device} \l{Action} with a \tt{bool} \l{Param} which has a corresponding state value can be represented a toggle button.
|
|
If the corresponding state currently has the value \tt{true}, the button offers the \tt{Off} action, otherwise the \tt{On} action.
|
|
|
|
The button name can be created with the \tt {paramType name + On/Off}.
|
|
|
|
The description of the button could be the name of the \l{ActionType}.
|
|
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "Set power",
|
|
"paramTypes": [
|
|
{
|
|
"name": "power",
|
|
"type": "Bool",
|
|
"defaultValue": false
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/action-bool-with-state.png
|
|
|
|
|
|
\section2 With one \tt Numeric param
|
|
An \l{Action} with one numeric \l{Param} (\tt{int}, \tt{uint} or \tt{double}) can be represented by a text line and an button.
|
|
The \l{Action} will be executed with the value in the text line. The client developer has to make sure
|
|
the user can only enter the corresponding numeric value, otherwise the API will respond with an error code.
|
|
|
|
If this \l{Action} has a corresponding \l{State} (with the same UUID), the placeholder should be initialized with the current
|
|
corresponding state value, otherwise with the \tt defaultValue.
|
|
|
|
Here is an example for an \tt int \l{Param}:
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "Set int value",
|
|
"paramTypes": [
|
|
{
|
|
"name": "Int value",
|
|
"type": "Int",
|
|
"defaultValue": 50
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/action-int-param.png
|
|
|
|
If the text line element is smart enough to recognize if the user is finished with the input
|
|
(i.e. pressed the \tt enter button), the execute button can be dispensed. The default value
|
|
can be shown as placeholder in the textfield.
|
|
|
|
\image ui/action-int-param-alternative.png
|
|
|
|
|
|
\section2 With one \tt Numeric param and limits
|
|
An \l{Action} with one numeric \l{Param} (\tt{int}, \tt{uint} or \tt{double}) and limits (\tt minValue and \tt maxValue) can be
|
|
represented with a slider. The \l{Action} will be executed with the value from the slider. The client developer should make sure
|
|
the action will only be executed once the slider has been released or if the slider hasn't changed the value for ~200 ms,
|
|
otherwise there would be to much useless traffic.
|
|
|
|
If this \l{Action} has a corresponding \l{State} (with the same UUID), the slider should be initialized with the current
|
|
corresponding state value, otherwise with the \tt{defaultValue}.
|
|
|
|
If there is a \tt{Unit} in the \l{ParamType}, the unit should be visible in the \l{Action} description.
|
|
|
|
Here is an example for an \tt{int} param:
|
|
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "Set value",
|
|
"paramTypes": [
|
|
{
|
|
"name": "Int value",
|
|
"type": "Int",
|
|
"minValue": 0,
|
|
"maxValue": 100,
|
|
"unit": "UnitPercentage",
|
|
"defaultValue": 50
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/action-int-param-slider.png
|
|
|
|
|
|
\section2 With one \tt Numeric param and allowed values
|
|
An \l{Action} with one numeric \l{Param} (\tt{int}, \tt{uint} or \tt{double}) and an array of \tt allowedValue can be
|
|
represented as combobox. The \l{Action} will be executed with the selected value of the combobox.
|
|
|
|
If this \l{Action} has a corresponding \l{State} (with the same UUID), the combobox should initially show
|
|
corresponding state value, otherwise with the \tt{defaultValue}.
|
|
|
|
If there is a \tt{Unit} in the \l{ParamType}, the unit should be visible in the \l{Action} description.
|
|
|
|
Here is an example for an \tt{int} param:
|
|
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "Set int value",
|
|
"paramTypes": [
|
|
{
|
|
"name": "value",
|
|
"type": "Int",
|
|
"unit": "UnitPercentage",
|
|
"defaultValue": 20,
|
|
"allowedValues": [
|
|
10,
|
|
20,
|
|
30
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/action-int-param-combobox-closed.png
|
|
\image ui/action-int-param-combobox-open.png
|
|
|
|
|
|
\section2 With one \tt String param
|
|
An \l{Action} with one string \l{Param} can be represented by a text line and an button.
|
|
The \l{Action} will be executed with the value in the text line once the button will be pressed.
|
|
|
|
If this \l{Action} has a corresponding \l{State} (with the same UUID), the placeholder should be initialized with the current
|
|
corresponding state value, otherwise with the \tt defaultValue.
|
|
|
|
Here is an example for an \tt int \l{Param}:
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "Set string value",
|
|
"paramTypes": [
|
|
{
|
|
"name": "String value",
|
|
"type": "String",
|
|
"inputType": "InputTypeTextLine",
|
|
"defaultValue": "Hello world"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/action-string-param.png
|
|
|
|
If the text line element is smart enough to recognize if the user is finished with the input
|
|
(i.e. pressed the \tt enter button), the execute button can be dispensed. The default value
|
|
can be shown as placeholder in the textfield.
|
|
|
|
\image ui/action-string-param-alternative.png
|
|
|
|
|
|
\section2 With one \tt String param and allowed values
|
|
An \l{Action} with one string \l{Param} and an array of \tt allowedValue can be
|
|
represented as combobox. The \l{Action} will be executed with the selected value of the combobox.
|
|
|
|
If this \l{Action} has a corresponding \l{State} (with the same UUID), the combobox should initially show
|
|
corresponding state value, otherwise with the \tt{defaultValue}.
|
|
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "Set string value",
|
|
"paramTypes": [
|
|
{
|
|
"name": "value",
|
|
"type": "String",
|
|
"defaultValue": "String y",
|
|
"allowedValues": [
|
|
"String x",
|
|
"String y",
|
|
"String z"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/action-string-param-combobox-closed.png
|
|
\image ui/action-string-param-combobox-open.png
|
|
|
|
|
|
\section2 With multiple params
|
|
A \l{Device} \l{Action} with multiple \l{Param}{Params} can be represented by a list of param inputs in combination with an execute button.
|
|
Each \l{ParamType} has an input for the corresponding type. If the user does not insert a value for one of the \l{Params}{Param}, the
|
|
default value should be inserted once the user clicks the execute button.
|
|
|
|
The button contains the name of the \l{ActionType}.
|
|
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "Configure something",
|
|
"paramTypes": [
|
|
{
|
|
"name": "Mail",
|
|
"type": "String",
|
|
"inputType": "InputTypeMail",
|
|
"defaultValue": "name@example.com"
|
|
},
|
|
{
|
|
"name": "Note",
|
|
"type": "String"
|
|
},
|
|
{
|
|
"name": "Note",
|
|
"type": "String",
|
|
"inputType": "InputTypeTextArea",
|
|
"defaultValue": "I am Batman!"
|
|
},
|
|
{
|
|
"name": "Brightness",
|
|
"type": "Int",
|
|
"minValue": 0,
|
|
"maxValue": 100,
|
|
"unit": "UnitPercentage",
|
|
"defaultValue": 70
|
|
},
|
|
{
|
|
"name": "Details",
|
|
"type": "Bool",
|
|
"defaultValue": true
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/action-multiple-params.png
|
|
|
|
|
|
|
|
\chapter Params
|
|
|
|
\section2 \tt Bool param
|
|
A \l{Param} from the type \tt Bool can be represented as a switch.
|
|
|
|
\code
|
|
{
|
|
"paramTypes": [
|
|
"name": "Bool value",
|
|
"type": "Bool",
|
|
"defaultValue": true
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/param-bool.png
|
|
|
|
|
|
\section2 \tt String input types
|
|
Depending on the \l{Types::InputType} a string \l{Param} can look different:
|
|
|
|
\b InputTypeTextLine
|
|
\image ui/param-string-input-textline.png
|
|
|
|
\b InputTypeTextArea
|
|
\image ui/param-string-input-textarea.png
|
|
|
|
\b InputTypeSearch
|
|
\image ui/param-string-input-search.png
|
|
|
|
\b InputTypePassword
|
|
\image ui/param-string-input-password.png
|
|
|
|
\b InputTypeIPv4
|
|
\image ui/param-string-input-ipv4.png
|
|
|
|
\b InputTypeMacAddress
|
|
\image ui/param-string-input-macaddress.png
|
|
|
|
\b InputTypeUrl
|
|
\image ui/param-string-input-url.png
|
|
|
|
\b InputTypeMail
|
|
\image ui/param-string-input-mail.png
|
|
|
|
All other \l{Types::InputType}{InputTypes} (or if the \tt inputType is not specified) can be represented by a simple text line.
|
|
|
|
|
|
\section2 \tt Time param
|
|
A \l{Param} from the type \tt Time can be represented on the api as string "\tt{hh:mm}".
|
|
For the user there should be some kind of time picker.
|
|
|
|
\code
|
|
{
|
|
"paramTypes": [
|
|
{
|
|
"name": "Time",
|
|
"type": "Time",
|
|
"defaultValue": "00:00"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/param-time.png
|
|
|
|
|
|
\section2 \tt Unixtime param
|
|
A \l{Param} from the type \tt int with the unit \tt UnitUnixTime can be represented in the API as \tt{int}.
|
|
For the user there should be some kind of date time picker.
|
|
|
|
\code
|
|
{
|
|
"paramTypes": [
|
|
{
|
|
"name": "Datetime",
|
|
"type": "int",
|
|
"unit": "UnitUnixTime",
|
|
"defaultValue": 0
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\image ui/param-unixtime.png
|
|
|
|
|
|
\section2 \tt Color param
|
|
A \l{Param} from the type \tt Color can be represented in the API as html string \tt{#RRGGBBAA}.
|
|
|
|
For the user there should be some kind of date time picker.
|
|
|
|
\code
|
|
{
|
|
"paramTypes": [
|
|
{
|
|
"name": "Color",
|
|
"type": "Color",
|
|
"defaultValue": "#000000
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\note: Todo: Color picker image
|
|
|
|
|
|
*/
|