/// <reference path="./sigApi.ApiBase.d.ts" />
/// <reference path="./sigApi.Datapoint.d.ts" />

declare namespace SigApi {
    interface ApiKeyboardManager extends ApiBase {
        /**
         * Opens a keyboard window or activates a keyboard on the dashboard
         * 
         * @param {number|string} type the type constant of the keyboard which should be opened (SIG_CONST.SYSTEM_WINDOW_KEYBOARD_...)
         * @param {string|object} title a string or a property which should be written in the header
         * 
         * object {src: `number`, dest: `number`, value: `number|string`}
         * @param {object} [properties] an Object with the property name as key, and the value which should be set as the value. This values are written to the keyboard properties
         * 
         * object {any: `number|string|boolean|function`}
         * 
         * * {@link PropertyObject} keyboardcurrentvalue - custom keyboard value when not using parameters instance/propName
         * * {string} keyboardplaceholder - the keyboard's input field placeholder
         * * {number} keyboardmin - the minimal value of the numeric keyboard input
         * * {number} keyboardmax - the maximal value of the numeric keyboard input
         * * {number} keyboardmaxlength - the maximal number of characters to be inputted
         * * {string} keyboardlang - currently active language
         * * {boolean} ispassword - if true input field value should be masked
         * * {boolean} ignoremin - if true the keyboardmin should be ignored
         * * {boolean} ignoremax - if true the keyboardmax should be ignored
         * * {string} keyboardunittext - the unit text of the input value
         * * {boolean} writeonincrement - if true DP is instantly updated with inc/dec value
         * * {string} datapointtype - the type of datapoint bound to input
         * * {boolean} sanitizeInput - if true, only allowed html tags are rendered, the rest is converted to unicode placeholder characters
         * * {Function} customInputValidation - callback function for input validation
         * 
         *   function signature: ({string} newval, {string} oldval, {{@link DataPoint}} dataPoint, {object} result):{object}
         *
         *   {object} result, {object} function-return-value - { {boolean} isvalid, {boolean} revertChange }
         * * {Function} customCheckLimits - callback function for limit check
         * 
         *    function signature: ({number} val):{any[]} - details: {@link ApiKeyboardManager#checkLimits}
         * * {Function} customIncDataPoint - callback function for increment datapoint
         * 
         *    function signature: ({boolean} writeOnIncrement, {string} value):{string}
         * * {Function} customDecDataPoint - callback function for decrement datapoint
         * 
         *    function signature: ({boolean} writeOnIncrement, {string} value):{string}
         * @param {HTMLElement} [instance=null] the instance of the control which requested the keyboard
         * @param {string} [propName=null] the name of the property for which the keyboard should be opened
         * @param {number|string|null} [keyboardWindowId=null] keyboard window index or keyboard window name
         * 
         * if no keyboardWindowId is set the default keyboard determined by 'type' parameter will be used
         * @param {boolean} [openNearControl=false] try to position keyboard window near input control
         * @param {string} [keyboardInstanceId=null] instanceId of a keyboard on the dashboard
         * 
         * if keyboardInstanceId could not be found a keyboard window is being opened
         *
         * @returns {Promise} Promise -> resolve: (string|number) => void, reject: () => {}
         * 
         * A Promise which is resolved with the entered value, or rejected if the keyboard was closed without entering a value
         */
        open(
            type: number | string,
            title: string | object,
            properties?: object,
            instance?: HTMLElement,
            propName?: string,
            keyboardWindowId?: number | string,
            openNearControl?: boolean,
            keyboardInstanceId?: string
        ): Promise<string | number>
        /**
         * Validates input format based on data point settings: It checks if the newvalue does not have more decimals and digits than allowed (this can be configured in LVD - Data point manager - Unit).
         * If a [custom validation callback](#custom-input-validation) is passed in the keyboard open() call, the result of the callback is returned.
         * @param {string} newval A new keyboard input value that should be validated.
         * @param {string} [oldval=''] An old keyboard input value.
         * 
         * @returns {object} Returns a result object with the following properties:
         * * **revertChange** {boolean} - If true, the keyboard will revert the new keyboard value back to the old value.
         * * **isvalid** {boolean} - If true, the keyboard value is valid and can be submitted. If false, the keyboard value is invalid and it cannot be submitted.
         */
        validateInputFormat(newval: string, oldval?: string): any
        /**
         * This function is used in the keyboard control, to validate the entered value. 
         * It uses the information provided with the open call and data point settings to find the corresponding limits
         * @param {number} val The value which should be checked. 
         * @returns {any[]} The first part of the result describes if the value is over the limit(1), under the limit(-1) or within the limits(0) `number`
         * The second part of the result is the value formatted with the correct unit `string`
         */
        checkLimits(value: number): any[]
        /**
         * This function is used in the keyboard control, to increment a given value.  It uses the information provided with the open call to find the corresponding limits and the format
         * 
         * @param {boolean} writeOnIncrement A flag which, if set to true, automatically writes the incremented value to the corresponding datapoint
         * @param {string} value The old value, which should be incremented. It must be parseable to a number
         * 
         * @returns {string} The result of the increment formatted with the correct unit
         */
        incDataPoint(writeOnIncrement: boolean, value: string): string
        /**
         * This function is used in the keyboard control, to decrement a given value.  It uses the information provided with the open call to find the corresponding limits and the format
         * 
         * @param {boolean} writeOnIncrement A flag which, if set to true, automatically writes the decremented value to the corresponding datapoint
         * @param {string} value The old value, which should be decremented. It must be parseable to a number
         * 
         * @returns {string} The result of the decrement formatted with the correct unit
         */
        decDataPoint(writeOnIncrement: boolean, value: string): string
        /**
         * Returns a Datapoint object of the currently active keyboard or null if nothing was found.
         * 
         * @returns {Datapoint|null} The Datapoint object of the currently active keyboard or null if nothing was found
         */
        getActiveDatapoint(): Datapoint | null
        /**
         * Registers a callback function to overrule result of keyboard selection process
         * Only one callback can be registered at a time. Successive calls replace the previous callback function.
         * The Callback function may return:
         *   * {string} Keyboard Container name which actually should be opened
         *   * {number} Keyboard Container index which actually should be opened
         *   * {undefined} Undefined, if no Keyboard Component is to be opened
         * @param {Function} callback callback({string} keyboardName, {Datapoint} activeDatapoint, {string} instanceId) -> {undefined|number|string} keyboardWindowId
         * @returns {boolean} True if Callback registration has succeeded, in other case False.
         */
        registerSelectionCallback(
            callback: (
                keyboardName: string,
                activeDatapoint: Datapoint,
                instanceId: string
            ) => number | string | undefined
        ): boolean
        /**
         * Unregisters the previously registered selection callback function.
         * @returns {boolean} True if callback un-registration has succeeded, otherwise false.
         */
        unregisterSelectionCallback(): boolean
    }
}
