diff --git a/doc/images/ui/action-bool-with-state.png b/doc/images/ui/action-bool-with-state.png index 9a4c7241..20ebd473 100644 Binary files a/doc/images/ui/action-bool-with-state.png and b/doc/images/ui/action-bool-with-state.png differ diff --git a/doc/images/ui/action-bool-without-state.png b/doc/images/ui/action-bool-without-state.png index 47f831a4..d6fdb19e 100644 Binary files a/doc/images/ui/action-bool-without-state.png and b/doc/images/ui/action-bool-without-state.png differ diff --git a/doc/images/ui/action-int-param-alternative.png b/doc/images/ui/action-int-param-alternative.png index 28b3f627..f8a244eb 100644 Binary files a/doc/images/ui/action-int-param-alternative.png and b/doc/images/ui/action-int-param-alternative.png differ diff --git a/doc/images/ui/action-int-param-combobox-closed.png b/doc/images/ui/action-int-param-combobox-closed.png index 65f47f76..12eb4477 100644 Binary files a/doc/images/ui/action-int-param-combobox-closed.png and b/doc/images/ui/action-int-param-combobox-closed.png differ diff --git a/doc/images/ui/action-int-param-combobox-open.png b/doc/images/ui/action-int-param-combobox-open.png index b672f8de..5e38648f 100644 Binary files a/doc/images/ui/action-int-param-combobox-open.png and b/doc/images/ui/action-int-param-combobox-open.png differ diff --git a/doc/images/ui/action-int-param-slider.png b/doc/images/ui/action-int-param-slider.png index 72a2ba0f..0473de0b 100644 Binary files a/doc/images/ui/action-int-param-slider.png and b/doc/images/ui/action-int-param-slider.png differ diff --git a/doc/images/ui/action-int-param.png b/doc/images/ui/action-int-param.png index e687628b..830716d6 100644 Binary files a/doc/images/ui/action-int-param.png and b/doc/images/ui/action-int-param.png differ diff --git a/doc/images/ui/action-multiple-params.png b/doc/images/ui/action-multiple-params.png new file mode 100644 index 00000000..da9dab93 Binary files /dev/null and b/doc/images/ui/action-multiple-params.png differ diff --git a/doc/images/ui/action-string-input-ipv4.png b/doc/images/ui/action-string-input-ipv4.png deleted file mode 100644 index 6f45617b..00000000 Binary files a/doc/images/ui/action-string-input-ipv4.png and /dev/null differ diff --git a/doc/images/ui/action-string-input-macaddress.png b/doc/images/ui/action-string-input-macaddress.png deleted file mode 100644 index 26887734..00000000 Binary files a/doc/images/ui/action-string-input-macaddress.png and /dev/null differ diff --git a/doc/images/ui/action-string-input-mail.png b/doc/images/ui/action-string-input-mail.png deleted file mode 100644 index 2791b8fe..00000000 Binary files a/doc/images/ui/action-string-input-mail.png and /dev/null differ diff --git a/doc/images/ui/action-string-input-password.png b/doc/images/ui/action-string-input-password.png deleted file mode 100644 index 864f0419..00000000 Binary files a/doc/images/ui/action-string-input-password.png and /dev/null differ diff --git a/doc/images/ui/action-string-input-search.png b/doc/images/ui/action-string-input-search.png deleted file mode 100644 index 19bb4ab8..00000000 Binary files a/doc/images/ui/action-string-input-search.png and /dev/null differ diff --git a/doc/images/ui/action-string-input-textarea.png b/doc/images/ui/action-string-input-textarea.png deleted file mode 100644 index 74423773..00000000 Binary files a/doc/images/ui/action-string-input-textarea.png and /dev/null differ diff --git a/doc/images/ui/action-string-input-textline.png b/doc/images/ui/action-string-input-textline.png deleted file mode 100644 index 3a7dd674..00000000 Binary files a/doc/images/ui/action-string-input-textline.png and /dev/null differ diff --git a/doc/images/ui/action-string-input-url.png b/doc/images/ui/action-string-input-url.png deleted file mode 100644 index f38a0712..00000000 Binary files a/doc/images/ui/action-string-input-url.png and /dev/null differ diff --git a/doc/images/ui/action-string-param-alternative.png b/doc/images/ui/action-string-param-alternative.png index fadd5a9a..3ef313ca 100644 Binary files a/doc/images/ui/action-string-param-alternative.png and b/doc/images/ui/action-string-param-alternative.png differ diff --git a/doc/images/ui/action-string-param-combobox-closed.png b/doc/images/ui/action-string-param-combobox-closed.png index 8bef0947..66584c1a 100644 Binary files a/doc/images/ui/action-string-param-combobox-closed.png and b/doc/images/ui/action-string-param-combobox-closed.png differ diff --git a/doc/images/ui/action-string-param-combobox-open.png b/doc/images/ui/action-string-param-combobox-open.png index 0bff90d1..a53a38b7 100644 Binary files a/doc/images/ui/action-string-param-combobox-open.png and b/doc/images/ui/action-string-param-combobox-open.png differ diff --git a/doc/images/ui/action-string-param.png b/doc/images/ui/action-string-param.png index 1ac3690d..0f32c011 100644 Binary files a/doc/images/ui/action-string-param.png and b/doc/images/ui/action-string-param.png differ diff --git a/doc/images/ui/action-without-params.png b/doc/images/ui/action-without-params.png index 5b45031f..83a558a6 100644 Binary files a/doc/images/ui/action-without-params.png and b/doc/images/ui/action-without-params.png differ diff --git a/doc/images/ui/param-bool.png b/doc/images/ui/param-bool.png new file mode 100644 index 00000000..ea1dd4c5 Binary files /dev/null and b/doc/images/ui/param-bool.png differ diff --git a/doc/images/ui/param-string-input-ipv4.png b/doc/images/ui/param-string-input-ipv4.png new file mode 100644 index 00000000..e0746226 Binary files /dev/null and b/doc/images/ui/param-string-input-ipv4.png differ diff --git a/doc/images/ui/param-string-input-macaddress.png b/doc/images/ui/param-string-input-macaddress.png new file mode 100644 index 00000000..d31ba17f Binary files /dev/null and b/doc/images/ui/param-string-input-macaddress.png differ diff --git a/doc/images/ui/param-string-input-mail.png b/doc/images/ui/param-string-input-mail.png new file mode 100644 index 00000000..cda82bbc Binary files /dev/null and b/doc/images/ui/param-string-input-mail.png differ diff --git a/doc/images/ui/param-string-input-password.png b/doc/images/ui/param-string-input-password.png new file mode 100644 index 00000000..4a4b9c8a Binary files /dev/null and b/doc/images/ui/param-string-input-password.png differ diff --git a/doc/images/ui/param-string-input-search.png b/doc/images/ui/param-string-input-search.png new file mode 100644 index 00000000..48a2a552 Binary files /dev/null and b/doc/images/ui/param-string-input-search.png differ diff --git a/doc/images/ui/param-string-input-textarea.png b/doc/images/ui/param-string-input-textarea.png new file mode 100644 index 00000000..f8036b76 Binary files /dev/null and b/doc/images/ui/param-string-input-textarea.png differ diff --git a/doc/images/ui/param-string-input-textline.png b/doc/images/ui/param-string-input-textline.png new file mode 100644 index 00000000..e467c956 Binary files /dev/null and b/doc/images/ui/param-string-input-textline.png differ diff --git a/doc/images/ui/param-string-input-url.png b/doc/images/ui/param-string-input-url.png new file mode 100644 index 00000000..25ec759f Binary files /dev/null and b/doc/images/ui/param-string-input-url.png differ diff --git a/doc/images/ui/param-time.png b/doc/images/ui/param-time.png new file mode 100644 index 00000000..bdca56ff Binary files /dev/null and b/doc/images/ui/param-time.png differ diff --git a/doc/images/ui/param-unixtime.png b/doc/images/ui/param-unixtime.png new file mode 100644 index 00000000..9fa13a5e Binary files /dev/null and b/doc/images/ui/param-unixtime.png differ diff --git a/doc/paramtypes-ui-elements.qdoc b/doc/paramtypes-ui-elements.qdoc index 02efe95e..43893343 100644 --- a/doc/paramtypes-ui-elements.qdoc +++ b/doc/paramtypes-ui-elements.qdoc @@ -2,246 +2,397 @@ \page paramtypes-ui-elements.html \title Paramtypes and the coresponding UI elements - \chapter Actions + 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 \i 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 \i 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}. + 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 + \code + { + "id": "uuid", + "name": "Action name", + "paramTypes": [] + } + \endcode - \image ui/action-without-params.png + \image ui/action-without-params.png - \section2 Bool param + \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}. + 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 Bool param with 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 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 Numeric param with 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 Numeric param with 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", - "allowedValues": [ - 10, - 20, - 30 + \code + { + "id": "uuid", + "name": "Set power", + "paramTypes": [ + { + "name": "power", + "type": "Bool", + "defaultValue": false + } ] - "defaultValue": 20 - ] - } - \endcode + } + \endcode - \image ui/action-int-param-combobox-closed.png - \image ui/action-int-param-combobox-open.png + \image ui/action-bool-without-state.png - \section2 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. + \section2 With one \tt Bool param and corresponding state - 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. + 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. - 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 + The button name can be created with the \tt {paramType name + On/Off}. - \image ui/action-string-param.png + The description of the button could be the name of the \l{ActionType}. - 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 - - - Depending on the \l{Types::InputType} a string input can be look different: - - \b InputTypeTextLine - \image ui/action-string-input-textline.png - - \b InputTypeTextArea - \image ui/action-string-input-textarea.png - - \b InputTypeSearch - \image ui/action-string-input-search.png - - \b InputTypePassword - \image ui/action-string-input-password.png - - \b InputTypeIPv4 - \image ui/action-string-input-ipv4.png - - \b InputTypeMacAddress - \image ui/action-string-input-macaddress.png - - \b InputTypeUrl - \image ui/action-string-input-url.png - - \b InputTypeMail - \image ui/action-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 String param with 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", - "allowedValues": [ - "String x", - "String y", - "String z" + \code + { + "id": "uuid", + "name": "Set power", + "paramTypes": [ + { + "name": "power", + "type": "Bool", + "defaultValue": false + } ] - "defaultValue": "String y" - ] - } - \endcode + } + \endcode - \image ui/action-string-param-combobox-closed.png - \image ui/action-string-param-combobox-open.png + \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 + */