/*!
    \page paramtypes-ui-elements.html
    \title Paramtypes and the corresponding 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


*/
