add input type docs

doc/guh.qdoc

@@ -33,7 +33,7 @@
 
     \section1 Write your own plugin
     Here you can find some tutorials for developing and working with guh:
-        \list
+    \list
         \li \l{Set up the build environment}
         \li \l{Getting started}
         \li \l{The plugin JSON File}
@@ -41,6 +41,11 @@
         \li \l{Tutorials}
     \endlist
 
+    \section1 Client developers
+    \list
+        \li \l{Paramtypes and the coresponding UI elements}
+    \endlist
+
     \section1 Quicklinks
     Overview of all classes and modules in guh
     \list

doc/paramtypes-ui-elements.qdoc

@@ -0,0 +1,247 @@
+/*!
+    \page paramtypes-ui-elements.html
+    \title Paramtypes and the coresponding UI elements
+
+    \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 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 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
+                ]
+                "defaultValue": 20
+            ]
+        }
+    \endcode
+
+    \image ui/action-int-param-combobox-closed.png
+    \image ui/action-int-param-combobox-open.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.
+
+    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
+
+
+    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"
+                ]
+                "defaultValue": "String y"
+            ]
+        }
+    \endcode
+
+    \image ui/action-string-param-combobox-closed.png
+    \image ui/action-string-param-combobox-open.png
+
+
+
+*/