From 8a9d07bca57769ee6b747a31b46980503c46cfb5 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Thu, 12 May 2022 22:07:38 +0200 Subject: [PATCH 01/34] Declarations for engine and controller scripting API --- res/controllers/engine-api.d.ts | 59 ++++++++++++++++++++++++ res/controllers/hid-controller-api.d.ts | 46 ++++++++++++++++++ res/controllers/midi-controller-api.d.ts | 11 +++++ 3 files changed, 116 insertions(+) create mode 100644 res/controllers/engine-api.d.ts create mode 100644 res/controllers/hid-controller-api.d.ts create mode 100644 res/controllers/midi-controller-api.d.ts diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts new file mode 100644 index 00000000000..e4707425128 --- /dev/null +++ b/res/controllers/engine-api.d.ts @@ -0,0 +1,59 @@ + +declare var print = function(message : string) {}; + +declare class ControllerScriptInterfaceLegacy { + public getValue(group : string, name : string) : number; + public setValue(group : string, name : string, newValue: number) : void; + public softTakeover(group : string, name : string, set : boolean) : void; + public getParameter(group : string, name : string) : number; + public setParameter(group : string, name : string, newValue : number) : void; + public getParameterForValue(group : string, name : string, value : number) : number; + public reset(group : string, name : string) : void; + public getDefaultValue(group : string, name : string) : number; + public getDefaultParameter(group : string, name : string) : number; + + /** + * Callback function called from the engine, when the value of a specified control changes + * @callback controlCallback + * @param {number} value + * @param {string} group + * @param {string} name + */ + + /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes + * @details This connection has a FIFO buffer - all value change events are processed in serial order. + * @param {string} group Group of the control e.g. "[Channel1]" + * @param {string} name Name of the control e.g. "play_indicator" + */ + public makeConnection(group : string, name : string, callback : controlCallback); + + /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes + * @details This connection is unbuffered - when value change events occur faster, than the mapping can process them, + * only the last value set for the control is processed. + * @param {string} group Group of the control e.g. "[Channel1]" + * @param {string} name Name of the control e.g. "VuMeter" + */ + public makeUnbufferedConnection(group : string, name : string, callback : controlCallback); + /** @deprecated Use makeConnection instead */ + public connectControl(group : string, name : string, passedCallback : controlCallback, disconnect:boolean = false); + + /** Called indirectly by the objects returned by connectControl */ + public trigger(group : string, name : string) : void; + public log(message : string) : void; + /** + * Callback function called from the engine, when the the interval of a timer is reached + * @callback timerCallback + */ + public beginTimer(interval:number, scriptCode : timerCallback, oneShot:boolean = false); + public stopTimer(timerId : number) : void; + public scratchEnable(deck : number, intervalsPerRev : number, rpm : number, alpha : number, beta : number, ramp:boolean = true) : void; + public scratchTick(deck : number, interval : number) : void; + public scratchDisable(deck : number, ramp:boolean = true) : void; + public isScratching(deck : number) : boolean; + public softTakeover(group : string, name : string, set : boolean) : void; + public softTakeoverIgnoreNextValue(group : string, name : string) : void; + public brake(deck : number, activate : boolean, factor:number = 1.0, rate:number = 1.0) : void; + public spinback(deck : number, activate : boolean, factor:number = 1.8, rate:number = -10.0) : void; + public softStart(deck : number, activate : boolean, factor:number = 1.0) : void; + } +var engine = new ControllerScriptInterfaceLegacy; diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts new file mode 100644 index 00000000000..1f7864c4a41 --- /dev/null +++ b/res/controllers/hid-controller-api.d.ts @@ -0,0 +1,46 @@ + +declare class HidControllerJSProxy { + /** Sends HID OutputReport with hard coded ReportID 0 to HID device + * This function only works with HID devices, which don't use ReportIDs + * @param dataList Data to send as list of bytes + * @param length Unused optional argument + */ + public send(dataList : number[], length : number=0) : void; + /** Sends HID OutputReport to HID device + * @param dataList Data to send as list of bytes + * @param length Unused but mandatory argument + * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs + * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending + */ + public send(dataList : number[], length : number, reportID : number, resendUnchangedReport:boolean = false) : void; + + /** Sends an OutputReport to HID device + * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs + * @param dataArray Data to send as byte array (Javascript type Uint8Array) + * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending + */ + public sendOutputReport(reportID : number, dataArray : ArrayBuffer, resendUnchangedReport:boolean = false) : void; + + /** getInputReport receives an InputReport from the HID device on request. + * @details This can be used on startup to initialize the knob positions in Mixxx + * to the physical position of the hardware knobs on the controller. + * This is an optional command in the HID standard - not all devices support it. + * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use + * @return Returns report data with ReportID byte as prefix + */ + public getInputReport(reportID : number) : Uint8Array; + + /** Sends a FeatureReport to HID device + * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use + * @param reportData Data to send as byte array + */ + public sendFeatureReport(reportID : number, reportData : ArrayBuffer) : void; + + /** getFeatureReport receives a FeatureReport from the HID device on request. + * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use + * @return The returned array matches the input format of sendFeatureReport, + * allowing it to be read, modified and sent it back to the controller. + */ + public getFeatureReport(reportID : number) : Uint8Array; + } +var controller = new HidControllerJSProxy; diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts new file mode 100644 index 00000000000..d174c803e71 --- /dev/null +++ b/res/controllers/midi-controller-api.d.ts @@ -0,0 +1,11 @@ + +declare class MidiControllerJSProxy { + + public sendShortMsg(status : number, byte1 : number, byte2 : number) : void; + + /** Alias for sendSysexMsg */ + public send(dataList : number[], length : number=0) : void; + public sendSysexMsg(dataList : number[], length : number=0) : void; + + } +var controller = new MidiControllerJSProxy; From b1d689c3bde1a0956ec484f2d59cdcae302d69fe Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Mon, 6 Jun 2022 15:07:54 +0200 Subject: [PATCH 02/34] Added missing declarations for QJSEngine::ConsoleExtension --- res/controllers/console-api.d.ts | 73 ++++++++++++++++++++++++++++++++ res/controllers/engine-api.d.ts | 1 - 2 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 res/controllers/console-api.d.ts diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts new file mode 100644 index 00000000000..e866f5771fc --- /dev/null +++ b/res/controllers/console-api.d.ts @@ -0,0 +1,73 @@ + +/** Mixxx installs the QJSEngine::ConsoleExtension for the use in controller mapping scripts. + See also: https://doc.qt.io/qt-5/qtquick-debugging.html#console-api +*/ + +declare class QJSEngineConsoleExtension { + /** + * Prints debugging information to the console. + */ + public log(message? : any, ...args : any[]) : void; + public debug(message? : any, ...args : any[]) : void; + public info(message? : any, ...args : any[]) : void; + public warn(message? : any, ...args : any[]) : void; + public error(message? : any, ...args : any[]) : void; + + /** + * Tests that an expression is true. + * If not, it writes an optional message to the console and prints the stack trace. + */ + public assert(value: any, message? : string, ...args: any[]) : void; + + /** + * Starts the time measurement, which will be printed by timeEnd + * + * @param {string} [label] string argument that identifies the measurement. + */ + public time(label? : string) : void; + /** + * Logs the time (in milliseconds) that was spent since the call of the time method. + * + * @param {string} [label] string argument that identifies the measurement. + */ + public timeEnd(label? : string) : void; + + /** + * Prints the stack trace of the JavaScript execution at the point where it was called. + * This stack trace information contains the function name, file name, line number, and column number. + * The stack trace is limited to last 10 stack frames. + * + * @param {*} [message] + * @param {...any[]} args + */ + public trace(message? : any, ...args : any[]) : void; + + /** + * Prints the current number of times a particular piece of code has run, along with a message. + * + * @param {string} [label] + */ + public count(label? : string) : void; + + /** + * Turns on the JavaScript profiler. + * @deprecated Not usable for mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 + * + */ + public profile(label? : string) : void; + + /** + * Turns off the JavaScript profiler. + * @deprecated Not usable for mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 + * + */ + public profileEnd(label? : string) : void; + + /** + * Prints an error message together with the stack trace of JavaScript execution at the point where it is called. + * + */ + public exception(message? : any, ...args : any[]) : void; + + } +var console = new QJSEngineConsoleExtension; diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index e4707425128..5ea2f1be734 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -1,5 +1,4 @@ -declare var print = function(message : string) {}; declare class ControllerScriptInterfaceLegacy { public getValue(group : string, name : string) : number; From 3b146e95cd7c5b6779fec63a096e9e3b077f610c Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Tue, 7 Jun 2022 21:05:13 +0200 Subject: [PATCH 03/34] Added/Improved documentation --- res/controllers/console-api.d.ts | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index e866f5771fc..129bc3c0627 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -5,19 +5,36 @@ declare class QJSEngineConsoleExtension { /** - * Prints debugging information to the console. + * Prints debugging information to the console. (same as console.debug) */ public log(message? : any, ...args : any[]) : void; + + /** + * Prints debugging information to the console. (same as console.log) + */ public debug(message? : any, ...args : any[]) : void; + + /** + * Prints information to the console. + */ public info(message? : any, ...args : any[]) : void; + + /** + * Prints a warning message to the console. + */ public warn(message? : any, ...args : any[]) : void; + + /** + * Prints an error message to the console. + */ public error(message? : any, ...args : any[]) : void; /** * Tests that an expression is true. - * If not, it writes an optional message to the console and prints the stack trace. + * + * @param {boolean} [expression] If not true, it writes an optional message to the console and prints the stack trace. */ - public assert(value: any, message? : string, ...args: any[]) : void; + public assert(expression : boolean, message? : string, ...args: any[]) : void; /** * Starts the time measurement, which will be printed by timeEnd @@ -51,14 +68,14 @@ declare class QJSEngineConsoleExtension { /** * Turns on the JavaScript profiler. - * @deprecated Not usable for mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 + * @deprecated Not usable for controller mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 * */ public profile(label? : string) : void; /** * Turns off the JavaScript profiler. - * @deprecated Not usable for mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 + * @deprecated Not usable for controller mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 * */ public profileEnd(label? : string) : void; From 9397e8a94e66a491e9e97a79d1a0bb7b19d172d7 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Tue, 7 Jun 2022 21:58:15 +0200 Subject: [PATCH 04/34] Documented controlCallback functions --- res/controllers/engine-api.d.ts | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index 5ea2f1be734..99ba880fc48 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -14,15 +14,16 @@ declare class ControllerScriptInterfaceLegacy { /** * Callback function called from the engine, when the value of a specified control changes * @callback controlCallback - * @param {number} value - * @param {string} group - * @param {string} name + * @param {number} value New value of the connected control + * @param {string} group Group of the control e.g. "[Channel1]" + * @param {string} name Name of the control e.g. "play_indicator" */ /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * @details This connection has a FIFO buffer - all value change events are processed in serial order. * @param {string} group Group of the control e.g. "[Channel1]" * @param {string} name Name of the control e.g. "play_indicator" + * @param {controlCallback} callback JS function, which will be called everytime, the value of the connected control changes. */ public makeConnection(group : string, name : string, callback : controlCallback); @@ -31,6 +32,7 @@ declare class ControllerScriptInterfaceLegacy { * only the last value set for the control is processed. * @param {string} group Group of the control e.g. "[Channel1]" * @param {string} name Name of the control e.g. "VuMeter" + * @param {controlCallback} callback JS function, which will be called everytime, the value of the connected control changes. */ public makeUnbufferedConnection(group : string, name : string, callback : controlCallback); /** @deprecated Use makeConnection instead */ From f7bf17916b04d3a9ebbc407f3fbcf3f003615228 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Tue, 7 Jun 2022 22:00:23 +0200 Subject: [PATCH 05/34] Marked engine.log as deprecated --- res/controllers/console-api.d.ts | 2 +- res/controllers/engine-api.d.ts | 2 ++ .../scripting/legacy/controllerscriptinterfacelegacy.h | 1 + 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index 129bc3c0627..0e6ed196583 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -31,7 +31,7 @@ declare class QJSEngineConsoleExtension { /** * Tests that an expression is true. - * + * * @param {boolean} [expression] If not true, it writes an optional message to the console and prints the stack trace. */ public assert(expression : boolean, message? : string, ...args: any[]) : void; diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index 99ba880fc48..b4a511b5534 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -40,6 +40,8 @@ declare class ControllerScriptInterfaceLegacy { /** Called indirectly by the objects returned by connectControl */ public trigger(group : string, name : string) : void; + + /** @deprecated Use console.log instead */ public log(message : string) : void; /** * Callback function called from the engine, when the the interval of a timer is reached diff --git a/src/controllers/scripting/legacy/controllerscriptinterfacelegacy.h b/src/controllers/scripting/legacy/controllerscriptinterfacelegacy.h index 8dc78254cdf..be8589f4d1a 100644 --- a/src/controllers/scripting/legacy/controllerscriptinterfacelegacy.h +++ b/src/controllers/scripting/legacy/controllerscriptinterfacelegacy.h @@ -44,6 +44,7 @@ class ControllerScriptInterfaceLegacy : public QObject { bool disconnect = false); // Called indirectly by the objects returned by connectControl Q_INVOKABLE void trigger(const QString& group, const QString& name); + // DEPRECATED: Use console.log instead. Q_INVOKABLE void log(const QString& message); Q_INVOKABLE int beginTimer(int interval, QJSValue scriptCode, bool oneShot = false); Q_INVOKABLE void stopTimer(int timerId); From 92e35a04f4ebb928d0c726cc251acb9e97511337 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Wed, 8 Jun 2022 21:52:00 +0200 Subject: [PATCH 06/34] Documented engine API functions --- res/controllers/engine-api.d.ts | 267 +++++++++++++++++++++++++------- 1 file changed, 208 insertions(+), 59 deletions(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index b4a511b5534..c3ad6ae98e0 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -1,62 +1,211 @@ - declare class ControllerScriptInterfaceLegacy { - public getValue(group : string, name : string) : number; - public setValue(group : string, name : string, newValue: number) : void; - public softTakeover(group : string, name : string, set : boolean) : void; - public getParameter(group : string, name : string) : number; - public setParameter(group : string, name : string, newValue : number) : void; - public getParameterForValue(group : string, name : string, value : number) : number; - public reset(group : string, name : string) : void; - public getDefaultValue(group : string, name : string) : number; - public getDefaultParameter(group : string, name : string) : number; - - /** - * Callback function called from the engine, when the value of a specified control changes - * @callback controlCallback - * @param {number} value New value of the connected control - * @param {string} group Group of the control e.g. "[Channel1]" - * @param {string} name Name of the control e.g. "play_indicator" - */ - - /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes - * @details This connection has a FIFO buffer - all value change events are processed in serial order. - * @param {string} group Group of the control e.g. "[Channel1]" - * @param {string} name Name of the control e.g. "play_indicator" - * @param {controlCallback} callback JS function, which will be called everytime, the value of the connected control changes. - */ - public makeConnection(group : string, name : string, callback : controlCallback); - - /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes - * @details This connection is unbuffered - when value change events occur faster, than the mapping can process them, - * only the last value set for the control is processed. - * @param {string} group Group of the control e.g. "[Channel1]" - * @param {string} name Name of the control e.g. "VuMeter" - * @param {controlCallback} callback JS function, which will be called everytime, the value of the connected control changes. - */ - public makeUnbufferedConnection(group : string, name : string, callback : controlCallback); - /** @deprecated Use makeConnection instead */ - public connectControl(group : string, name : string, passedCallback : controlCallback, disconnect:boolean = false); - - /** Called indirectly by the objects returned by connectControl */ - public trigger(group : string, name : string) : void; - - /** @deprecated Use console.log instead */ - public log(message : string) : void; - /** - * Callback function called from the engine, when the the interval of a timer is reached - * @callback timerCallback - */ - public beginTimer(interval:number, scriptCode : timerCallback, oneShot:boolean = false); - public stopTimer(timerId : number) : void; - public scratchEnable(deck : number, intervalsPerRev : number, rpm : number, alpha : number, beta : number, ramp:boolean = true) : void; - public scratchTick(deck : number, interval : number) : void; - public scratchDisable(deck : number, ramp:boolean = true) : void; - public isScratching(deck : number) : boolean; - public softTakeover(group : string, name : string, set : boolean) : void; - public softTakeoverIgnoreNextValue(group : string, name : string) : void; - public brake(deck : number, activate : boolean, factor:number = 1.0, rate:number = 1.0) : void; - public spinback(deck : number, activate : boolean, factor:number = 1.8, rate:number = -10.0) : void; - public softStart(deck : number, activate : boolean, factor:number = 1.0) : void; - } + /** + * Gets the control value + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + * @returns Value of the control (within it's range according Mixxx Controls manual page) + */ + public getValue(group:string, name:string):number; + + /** + * Sets a control value + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + * @param newValue Value to be set (within it's range according Mixxx Controls manual page) + */ + public setValue(group:string, name:string, newValue: number):void; + + /** + * Gets the control value normalized to a range of 0..1 + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + * @returns Value of the control normalized to range of 0..1 + */ + public getParameter(group:string, name:string):number; + + /** + * Sets the control value specified with normalized range of 0..1 + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + * @param newValue Value to be set, normalized to a range of 0..1 + */ + public setParameter(group:string, name:string, newValue:number):void; + + /** + * Normalizes a specified value using the range of the given control, + * to the range of 0..1 + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + * @param value Value with the controls range according Mixxx Controls manual page + * @returns Value normalized to range of 0..1 + */ + public getParameterForValue(group:string, name:string, value:number):number; + + /** + * Resets the control to its default value + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + */ + public reset(group:string, name:string):void; + + /** + * Returns the default value of a control + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + * @returns Default value with the controls range according Mixxx Controls manual page + */ + public getDefaultValue(group:string, name:string):number; + + /** + * Returns the default value of a control, normalized to a range of 0..1 + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + * @returns Default value of the specified control normalized to range of 0..1 + */ + public getDefaultParameter(group:string, name:string):number; + + /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes + * @details This connection has a FIFO buffer - all value change events are processed in serial order. + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + * @param callback JS function, which will be called everytime, the value of the connected control changes. + */ + public makeConnection(group:string, name:string, callback:(value:number, group:string, name:string)=>any):any; + + /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes + * @details This connection is unbuffered - when value change events occur faster, than the mapping can process them, + * only the last value set for the control is processed. + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "VuMeter" + * @param callback JS function, which will be called everytime, the value of the connected control changes. + */ + public makeUnbufferedConnection(group:string, name:string, callback:(value:number, group:string, name:string)=>any):any; + + /** @deprecated Use makeConnection instead */ + public connectControl(group:string, name:string, passedCallback:(value:number, group:string, name:string)=>any, disconnect:boolean = false):any; + + + /** + * Triggers the execution of the connected callback functions, with the actual value of a control + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "play_indicator" + */ + public trigger(group:string, name:string):void; + + /** @deprecated Use console.log instead */ + public log(message:string):void; + + /** + * Starts a timer that will call the specified script function + * @param interval Time in milliseconds until the function is executed + * @param scriptCode Function to be executed, + * you can also use closures as: + * function() { print("Executed Timer") } + * @param oneShot If true the function is only once, + * if false the function is executed repeatedly + * @returns timerId which is needed to stop a timer. + * In case of an error, 0 is returned. + */ + public beginTimer(interval:number, scriptCode:()=>any, oneShot:boolean = false):number; + + /** + * Stops the specified timer + * @param timerId ID of the timer + */ + public stopTimer(timerId:number):void; + + /** + * Jogwheel function to be called when scratching starts (usually when the wheel is touched) + * This function contains an parametrizeable alpha-beta filter, which influences the + * responsiveness and looseness of the imaginary slip mat + * @param deck The deck number to use, e.g: 1 + * @param intervalsPerRev The resolution of the MIDI control (in intervals per revolution, typically 128.) + * @param rpm The speed of the imaginary record at 0% pitch (in revolutions per minute (RPM) typically 33+1/3, adjust for comfort) + * @param alpha The alpha coefficient of the filter (start with 1/8 (0.125) and tune from there) + * @param beta The beta coefficient of the filter (start with alpha/32 and tune from there) + * @param ramp Set true to ramp the deck speed down. Set false to stop instantly + */ + public scratchEnable(deck:number, intervalsPerRev:number, rpm:number, alpha:number, beta:number, ramp:boolean = true):void; + + /** + * Function to be called each time the jogwheel is moved during scratching + * @param deck The deck number to use, e.g: 1 + * @param interval The movement value (typically 1 for one "tick" forwards, -1 for one "tick" backwards) + */ + public scratchTick(deck:number, interval:number):void; + + /** + * Jogwheel function to be called when scratching ends (usually when the wheel is released) + * @param deck The deck number to use, e.g: 1 + * @param ramp Set true to ramp the deck speed up. Set false to jump to normal play speed instantly + */ + public scratchDisable(deck:number, ramp:boolean = true):void; + + /** + * Returns true if scratching is enabled + * @param deck The deck number to use, e.g: 1 + * @returns True if scratching is enabled + */ + public isScratching(deck:number):boolean; + + /** + * If enabled, soft-takeover prevents sudden wide parameter changes, + * when on-screen control and hardware control divert. + * With soft-takeover you need to turn a hardware knob, until it reachs + * the position of the on-screen knob - than it takes over control. + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "pregain" + * @param enable Set true to enable soft-takeover for the specified control + */ + public softTakeover(group:string, name:string, enable:boolean):void; + + /** + * Inhibits a suden value change from the hardware control. + * Should be called when receiving input for the knob/fader, + * that switches its behavior (e.g. Shift-Button pressed) + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "pregain" + */ + public softTakeoverIgnoreNextValue(group:string, name:string):void; + + /** + * To achieve a brake effect of the playback speed + * Both engine.softStart() and engine.brake()/engine.spinback() can interrupt each other. + * @param deck The deck number to use, e.g: 1 + * @param activate Set true to activate, or false to disable + * @param factor Defines how quickly the deck should come to a stop. + * Start with a value of 1 and increase to increase the acceleration. + * Be aware that brake called with low factors (about 0.5 and lower), + * would keep the deck running altough the resulting very low sounds are not audible anymore. + * @param rate The initial speed of the deck when enabled. "1" (default) means 10x speed in forward. + * Negative values like "-1" also work, though then it's spinning reverse obviously. + */ + public brake(deck:number, activate:boolean, factor:number = 1.0, rate:number = 1.0):void; + + /** + * To achieve a spinback effect of the playback speed + * Both engine.softStart() and engine.brake()/engine.spinback() can interrupt each other. + * @param deck The deck number to use, e.g: 1 + * @param activate Set true to activate, or false to disable + * @param factor Defines how quickly the deck should come to normal playback rate. + * Start with a value of 1 and increase to increase the acceleration. + * Be aware that spinback called with low factors (about 0.5 and lower), + * would keep the deck running altough the resulting very low sounds are not audible anymore. + * @param rate The initial speed of the deck when enabled. "-10" (default) means 10x speed in reverse. + * Positive values like "10" also work, though then it's spinning forward obviously. + */ + public spinback(deck:number, activate:boolean, factor:number = 1.8, rate:number = -10.0):void; + + /** + * To achieve a forward acceleration effect from standstill to normal speed. + * Both engine.softStart() and engine.brake()/engine.spinback() can interrupt each other. + * @param deck The deck number to use, e.g: 1 + * @param activate Set true to activate, or false to disable + * @param factor Defines how quickly the deck should come to normal playback rate. + * Start with a value of 1 and increase to increase the acceleration. + * SoftStart with low factors would take a while until sound is audible. + */ + public softStart(deck:number, activate:boolean, factor:number = 1.0):void; +} var engine = new ControllerScriptInterfaceLegacy; From 573a615b15b15950edc8bd119a4f168913094706 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Wed, 8 Jun 2022 21:52:21 +0200 Subject: [PATCH 07/34] Formatting --- res/controllers/console-api.d.ts | 42 +++++++++++++----------- res/controllers/engine-api.d.ts | 6 ++-- res/controllers/hid-controller-api.d.ts | 13 ++++---- res/controllers/midi-controller-api.d.ts | 17 +++++++--- 4 files changed, 46 insertions(+), 32 deletions(-) diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index 0e6ed196583..86bbbd04c70 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -7,84 +7,88 @@ declare class QJSEngineConsoleExtension { /** * Prints debugging information to the console. (same as console.debug) */ - public log(message? : any, ...args : any[]) : void; + public log(message?:any, ...args:any[]):void; /** * Prints debugging information to the console. (same as console.log) */ - public debug(message? : any, ...args : any[]) : void; + public debug(message?:any, ...args:any[]):void; /** * Prints information to the console. */ - public info(message? : any, ...args : any[]) : void; + public info(message?:any, ...args:any[]):void; /** * Prints a warning message to the console. */ - public warn(message? : any, ...args : any[]) : void; + public warn(message?:any, ...args:any[]):void; /** * Prints an error message to the console. */ - public error(message? : any, ...args : any[]) : void; + public error(message?:any, ...args:any[]):void; /** * Tests that an expression is true. * - * @param {boolean} [expression] If not true, it writes an optional message to the console and prints the stack trace. + * @param expression If not true, it writes an optional message to the console and prints the stack trace. + * @param message + * @param args */ - public assert(expression : boolean, message? : string, ...args: any[]) : void; + public assert(expression:boolean, message?:string, ...args: any[]):void; /** * Starts the time measurement, which will be printed by timeEnd * - * @param {string} [label] string argument that identifies the measurement. + * @param label string argument that identifies the measurement. */ - public time(label? : string) : void; + public time(label?:string):void; /** * Logs the time (in milliseconds) that was spent since the call of the time method. * - * @param {string} [label] string argument that identifies the measurement. + * @param label string argument that identifies the measurement. */ - public timeEnd(label? : string) : void; + public timeEnd(label?:string):void; /** * Prints the stack trace of the JavaScript execution at the point where it was called. * This stack trace information contains the function name, file name, line number, and column number. * The stack trace is limited to last 10 stack frames. * - * @param {*} [message] - * @param {...any[]} args + * @param message + * @param args */ - public trace(message? : any, ...args : any[]) : void; + public trace(message?:any, ...args:any[]):void; /** * Prints the current number of times a particular piece of code has run, along with a message. * - * @param {string} [label] + * @param label */ - public count(label? : string) : void; + public count(label?:string):void; /** * Turns on the JavaScript profiler. * @deprecated Not usable for controller mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 * */ - public profile(label? : string) : void; + public profile(label?:string):void; /** * Turns off the JavaScript profiler. * @deprecated Not usable for controller mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 * */ - public profileEnd(label? : string) : void; + public profileEnd(label?:string):void; /** * Prints an error message together with the stack trace of JavaScript execution at the point where it is called. * + * @param message + * @param args */ - public exception(message? : any, ...args : any[]) : void; + public exception(message?:any, ...args:any[]):void; } var console = new QJSEngineConsoleExtension; diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index c3ad6ae98e0..e8a57edcd31 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -9,7 +9,7 @@ declare class ControllerScriptInterfaceLegacy { public getValue(group:string, name:string):number; /** - * Sets a control value + * Sets a control value * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @param newValue Value to be set (within it's range according Mixxx Controls manual page) @@ -103,7 +103,7 @@ declare class ControllerScriptInterfaceLegacy { * you can also use closures as: * function() { print("Executed Timer") } * @param oneShot If true the function is only once, - * if false the function is executed repeatedly + * if false the function is executed repeatedly * @returns timerId which is needed to stop a timer. * In case of an error, 0 is returned. */ @@ -203,7 +203,7 @@ declare class ControllerScriptInterfaceLegacy { * @param deck The deck number to use, e.g: 1 * @param activate Set true to activate, or false to disable * @param factor Defines how quickly the deck should come to normal playback rate. - * Start with a value of 1 and increase to increase the acceleration. + * Start with a value of 1 and increase to increase the acceleration. * SoftStart with low factors would take a while until sound is audible. */ public softStart(deck:number, activate:boolean, factor:number = 1.0):void; diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index 1f7864c4a41..7130e50ecad 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -5,21 +5,22 @@ declare class HidControllerJSProxy { * @param dataList Data to send as list of bytes * @param length Unused optional argument */ - public send(dataList : number[], length : number=0) : void; + public send(dataList:number[], length:number=0):void; + /** Sends HID OutputReport to HID device * @param dataList Data to send as list of bytes * @param length Unused but mandatory argument * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending */ - public send(dataList : number[], length : number, reportID : number, resendUnchangedReport:boolean = false) : void; + public send(dataList:number[], length:number, reportID:number, resendUnchangedReport:boolean = false):void; /** Sends an OutputReport to HID device * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs * @param dataArray Data to send as byte array (Javascript type Uint8Array) * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending */ - public sendOutputReport(reportID : number, dataArray : ArrayBuffer, resendUnchangedReport:boolean = false) : void; + public sendOutputReport(reportID:number, dataArray:ArrayBuffer, resendUnchangedReport:boolean = false):void; /** getInputReport receives an InputReport from the HID device on request. * @details This can be used on startup to initialize the knob positions in Mixxx @@ -28,19 +29,19 @@ declare class HidControllerJSProxy { * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @return Returns report data with ReportID byte as prefix */ - public getInputReport(reportID : number) : Uint8Array; + public getInputReport(reportID:number):Uint8Array; /** Sends a FeatureReport to HID device * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @param reportData Data to send as byte array */ - public sendFeatureReport(reportID : number, reportData : ArrayBuffer) : void; + public sendFeatureReport(reportID:number, reportData:ArrayBuffer):void; /** getFeatureReport receives a FeatureReport from the HID device on request. * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @return The returned array matches the input format of sendFeatureReport, * allowing it to be read, modified and sent it back to the controller. */ - public getFeatureReport(reportID : number) : Uint8Array; + public getFeatureReport(reportID:number):Uint8Array; } var controller = new HidControllerJSProxy; diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts index d174c803e71..214182a6dfc 100644 --- a/res/controllers/midi-controller-api.d.ts +++ b/res/controllers/midi-controller-api.d.ts @@ -1,11 +1,20 @@ declare class MidiControllerJSProxy { - public sendShortMsg(status : number, byte1 : number, byte2 : number) : void; + public :ShortMsg(status:number, byte1:number, byte2:number):void; - /** Alias for sendSysexMsg */ - public send(dataList : number[], length : number=0) : void; - public sendSysexMsg(dataList : number[], length : number=0) : void; + /** + * Alias for :SysexMsg + * @param dataList + * @param length + */ + public :(dataList:number[], length:number=0):void; + /** + * + * @param dataList + * @param length + */ + public :SysexMsg(dataList:number[], length:number=0):void; } var controller = new MidiControllerJSProxy; From a743f33e68c459b668c14b5ac6e79d2721273d47 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Thu, 9 Jun 2022 22:35:46 +0200 Subject: [PATCH 08/34] Documented MIDI API and corrected console command docu --- res/controllers/console-api.d.ts | 22 ++++++++++++++----- res/controllers/hid-controller-api.d.ts | 2 +- res/controllers/midi-controller-api.d.ts | 28 +++++++++++++++--------- 3 files changed, 36 insertions(+), 16 deletions(-) diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index 86bbbd04c70..fa1ca50c22f 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -5,27 +5,39 @@ declare class QJSEngineConsoleExtension { /** - * Prints debugging information to the console. (same as console.debug) + * Prints debugging information to the console, when + * QT_LOGGING_RULES="js.debug=true;" or + * Mixxx is started with --controllerDebug + * This fuction is identical to console.debug */ public log(message?:any, ...args:any[]):void; /** - * Prints debugging information to the console. (same as console.log) + * Prints debugging information to the console, when + * QT_LOGGING_RULES="js.debug=true;" or + * Mixxx is started with --controllerDebug + * This function is identical to console.log */ public debug(message?:any, ...args:any[]):void; /** - * Prints information to the console. + * Prints information to the console, when + * QT_LOGGING_RULES="js.info=true;" or + * Mixxx is started with --controllerDebug */ public info(message?:any, ...args:any[]):void; /** - * Prints a warning message to the console. + * Prints a warning message to the console, when + * QT_LOGGING_RULES="js.warning=true;" or + * Mixxx is started with --controllerDebug */ public warn(message?:any, ...args:any[]):void; /** - * Prints an error message to the console. + * Prints an error message to the console, when + * QT_LOGGING_RULES="js.critical=true;" or + * Mixxx is started with --controllerDebug */ public error(message?:any, ...args:any[]):void; diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index 7130e50ecad..3963a791272 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -3,7 +3,7 @@ declare class HidControllerJSProxy { /** Sends HID OutputReport with hard coded ReportID 0 to HID device * This function only works with HID devices, which don't use ReportIDs * @param dataList Data to send as list of bytes - * @param length Unused optional argument + * @param length This optional argument is no longer evaluated, and only here for backwards compatibility */ public send(dataList:number[], length:number=0):void; diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts index 214182a6dfc..06db00ac8c7 100644 --- a/res/controllers/midi-controller-api.d.ts +++ b/res/controllers/midi-controller-api.d.ts @@ -1,20 +1,28 @@ declare class MidiControllerJSProxy { - public :ShortMsg(status:number, byte1:number, byte2:number):void; - /** - * Alias for :SysexMsg - * @param dataList - * @param length + * Sends a 3 byte MIDI short message + * @param status Status byte + * @param byte1 Data byte 1 + * @param byte2 Data byte 2 */ - public :(dataList:number[], length:number=0):void; + public sendShortMsg(status:number, byte1:number, byte2:number):void; + + /** + * Alias for sendSysexMsg. + * Sends a MIDI system-exclusive message of arbitrary number of bytes + * @param dataList List of bytes to send + * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts + */ + public send(dataList:number[], length:number=0):void; + /** - * - * @param dataList - * @param length + * Sends a MIDI system-exclusive message of arbitrary number of bytes + * @param dataList List of bytes to send + * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts */ - public :SysexMsg(dataList:number[], length:number=0):void; + public sendSysexMsg(dataList:number[], length:number=0):void; } var controller = new MidiControllerJSProxy; From fb8a3b6ca0250212f1dc7d25c95ad2442abaecca Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Sun, 12 Jun 2022 21:44:51 +0200 Subject: [PATCH 09/34] --controllerDebug => --controller-debug --- res/controllers/console-api.d.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index fa1ca50c22f..bd3235af7a4 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -7,7 +7,7 @@ declare class QJSEngineConsoleExtension { /** * Prints debugging information to the console, when * QT_LOGGING_RULES="js.debug=true;" or - * Mixxx is started with --controllerDebug + * Mixxx is started with --controller-debug * This fuction is identical to console.debug */ public log(message?:any, ...args:any[]):void; @@ -15,7 +15,7 @@ declare class QJSEngineConsoleExtension { /** * Prints debugging information to the console, when * QT_LOGGING_RULES="js.debug=true;" or - * Mixxx is started with --controllerDebug + * Mixxx is started with --controller-debug * This function is identical to console.log */ public debug(message?:any, ...args:any[]):void; @@ -23,21 +23,21 @@ declare class QJSEngineConsoleExtension { /** * Prints information to the console, when * QT_LOGGING_RULES="js.info=true;" or - * Mixxx is started with --controllerDebug + * Mixxx is started with --controller-debug */ public info(message?:any, ...args:any[]):void; /** * Prints a warning message to the console, when * QT_LOGGING_RULES="js.warning=true;" or - * Mixxx is started with --controllerDebug + * Mixxx is started with --controller-debug */ public warn(message?:any, ...args:any[]):void; /** * Prints an error message to the console, when * QT_LOGGING_RULES="js.critical=true;" or - * Mixxx is started with --controllerDebug + * Mixxx is started with --controller-debug */ public error(message?:any, ...args:any[]):void; From 5fc2ca19ce4859903d94898c468bf08a432813f9 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Sun, 12 Jun 2022 21:47:17 +0200 Subject: [PATCH 10/34] Changed text why console.profiling functions are not usable for mappings now --- res/controllers/console-api.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index bd3235af7a4..979802de8e9 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -82,14 +82,14 @@ declare class QJSEngineConsoleExtension { /** * Turns on the JavaScript profiler. - * @deprecated Not usable for controller mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 + * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} * */ public profile(label?:string):void; /** * Turns off the JavaScript profiler. - * @deprecated Not usable for controller mappings, because JavaScript profile does only workin GUI thread: https://bugreports.qt.io/browse/QTBUG-65419 + * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} * */ public profileEnd(label?:string):void; From 8d6edaf0344e3f6e2906b2a9006333419135d005 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Sun, 12 Jun 2022 21:49:43 +0200 Subject: [PATCH 11/34] Fixed typo --- res/controllers/engine-api.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index e8a57edcd31..76852efbeb5 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -152,7 +152,7 @@ declare class ControllerScriptInterfaceLegacy { /** * If enabled, soft-takeover prevents sudden wide parameter changes, * when on-screen control and hardware control divert. - * With soft-takeover you need to turn a hardware knob, until it reachs + * With soft-takeover you need to turn a hardware knob, until it reaches * the position of the on-screen knob - than it takes over control. * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "pregain" From 07abdf411bd07eda3f1e82d263c4de990100b1a9 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Sun, 26 Jun 2022 11:19:22 +0200 Subject: [PATCH 12/34] Add hyperlink for alias --- res/controllers/midi-controller-api.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts index 06db00ac8c7..51e9ad576d9 100644 --- a/res/controllers/midi-controller-api.d.ts +++ b/res/controllers/midi-controller-api.d.ts @@ -10,7 +10,7 @@ declare class MidiControllerJSProxy { public sendShortMsg(status:number, byte1:number, byte2:number):void; /** - * Alias for sendSysexMsg. + * Alias for {@link sendSysexMsg} * Sends a MIDI system-exclusive message of arbitrary number of bytes * @param dataList List of bytes to send * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts From 039cf93114655a692bad8af0cea51f3b86a84642 Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Sun, 26 Jun 2022 11:25:35 +0200 Subject: [PATCH 13/34] Added information about the 20ms minimum interval of JS timers --- res/controllers/engine-api.d.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index 76852efbeb5..e41b8c328ee 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -98,7 +98,8 @@ declare class ControllerScriptInterfaceLegacy { /** * Starts a timer that will call the specified script function - * @param interval Time in milliseconds until the function is executed + * @param interval Time in milliseconds until the function is executed. + * Intervals below 20ms are not allowed. * @param scriptCode Function to be executed, * you can also use closures as: * function() { print("Executed Timer") } From 98502bff1f60924f61ae01b531c691c753e252cc Mon Sep 17 00:00:00 2001 From: JoergAtGithub Date: Sun, 26 Jun 2022 13:24:42 +0200 Subject: [PATCH 14/34] Replaced declare class with declare namespace --- res/controllers/console-api.d.ts | 29 +++++----- res/controllers/engine-api.d.ts | 69 ++++++++++++------------ res/controllers/hid-controller-api.d.ts | 23 ++++---- res/controllers/midi-controller-api.d.ts | 15 +++--- 4 files changed, 69 insertions(+), 67 deletions(-) diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index 979802de8e9..fe8b18c191a 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -3,14 +3,14 @@ See also: https://doc.qt.io/qt-5/qtquick-debugging.html#console-api */ -declare class QJSEngineConsoleExtension { +declare namespace console { /** * Prints debugging information to the console, when * QT_LOGGING_RULES="js.debug=true;" or * Mixxx is started with --controller-debug * This fuction is identical to console.debug */ - public log(message?:any, ...args:any[]):void; + function log(message?:any, ...args:any[]):void; /** * Prints debugging information to the console, when @@ -18,28 +18,28 @@ declare class QJSEngineConsoleExtension { * Mixxx is started with --controller-debug * This function is identical to console.log */ - public debug(message?:any, ...args:any[]):void; + function debug(message?:any, ...args:any[]):void; /** * Prints information to the console, when * QT_LOGGING_RULES="js.info=true;" or * Mixxx is started with --controller-debug */ - public info(message?:any, ...args:any[]):void; + function info(message?:any, ...args:any[]):void; /** * Prints a warning message to the console, when * QT_LOGGING_RULES="js.warning=true;" or * Mixxx is started with --controller-debug */ - public warn(message?:any, ...args:any[]):void; + function warn(message?:any, ...args:any[]):void; /** * Prints an error message to the console, when * QT_LOGGING_RULES="js.critical=true;" or * Mixxx is started with --controller-debug */ - public error(message?:any, ...args:any[]):void; + function error(message?:any, ...args:any[]):void; /** * Tests that an expression is true. @@ -48,20 +48,20 @@ declare class QJSEngineConsoleExtension { * @param message * @param args */ - public assert(expression:boolean, message?:string, ...args: any[]):void; + function assert(expression:boolean, message?:string, ...args: any[]):void; /** * Starts the time measurement, which will be printed by timeEnd * * @param label string argument that identifies the measurement. */ - public time(label?:string):void; + function time(label?:string):void; /** * Logs the time (in milliseconds) that was spent since the call of the time method. * * @param label string argument that identifies the measurement. */ - public timeEnd(label?:string):void; + function timeEnd(label?:string):void; /** * Prints the stack trace of the JavaScript execution at the point where it was called. @@ -71,28 +71,28 @@ declare class QJSEngineConsoleExtension { * @param message * @param args */ - public trace(message?:any, ...args:any[]):void; + function trace(message?:any, ...args:any[]):void; /** * Prints the current number of times a particular piece of code has run, along with a message. * * @param label */ - public count(label?:string):void; + function count(label?:string):void; /** * Turns on the JavaScript profiler. * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} * */ - public profile(label?:string):void; + function profile(label?:string):void; /** * Turns off the JavaScript profiler. * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} * */ - public profileEnd(label?:string):void; + function profileEnd(label?:string):void; /** * Prints an error message together with the stack trace of JavaScript execution at the point where it is called. @@ -100,7 +100,6 @@ declare class QJSEngineConsoleExtension { * @param message * @param args */ - public exception(message?:any, ...args:any[]):void; + function exception(message?:any, ...args:any[]):void; } -var console = new QJSEngineConsoleExtension; diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index e41b8c328ee..166ae11f9ce 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -1,12 +1,14 @@ -declare class ControllerScriptInterfaceLegacy { +/** ControllerScriptInterfaceLegacy */ + +declare namespace engine { /** * Gets the control value * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @returns Value of the control (within it's range according Mixxx Controls manual page) */ - public getValue(group:string, name:string):number; + function getValue(group:string, name:string):number; /** * Sets a control value @@ -14,7 +16,7 @@ declare class ControllerScriptInterfaceLegacy { * @param name Name of the control e.g. "play_indicator" * @param newValue Value to be set (within it's range according Mixxx Controls manual page) */ - public setValue(group:string, name:string, newValue: number):void; + function setValue(group:string, name:string, newValue: number):void; /** * Gets the control value normalized to a range of 0..1 @@ -22,7 +24,7 @@ declare class ControllerScriptInterfaceLegacy { * @param name Name of the control e.g. "play_indicator" * @returns Value of the control normalized to range of 0..1 */ - public getParameter(group:string, name:string):number; + function getParameter(group:string, name:string):number; /** * Sets the control value specified with normalized range of 0..1 @@ -30,7 +32,7 @@ declare class ControllerScriptInterfaceLegacy { * @param name Name of the control e.g. "play_indicator" * @param newValue Value to be set, normalized to a range of 0..1 */ - public setParameter(group:string, name:string, newValue:number):void; + function setParameter(group:string, name:string, newValue:number):void; /** * Normalizes a specified value using the range of the given control, @@ -40,14 +42,14 @@ declare class ControllerScriptInterfaceLegacy { * @param value Value with the controls range according Mixxx Controls manual page * @returns Value normalized to range of 0..1 */ - public getParameterForValue(group:string, name:string, value:number):number; + function getParameterForValue(group:string, name:string, value:number):number; /** * Resets the control to its default value * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" */ - public reset(group:string, name:string):void; + function reset(group:string, name:string):void; /** * Returns the default value of a control @@ -55,7 +57,7 @@ declare class ControllerScriptInterfaceLegacy { * @param name Name of the control e.g. "play_indicator" * @returns Default value with the controls range according Mixxx Controls manual page */ - public getDefaultValue(group:string, name:string):number; + function getDefaultValue(group:string, name:string):number; /** * Returns the default value of a control, normalized to a range of 0..1 @@ -63,7 +65,7 @@ declare class ControllerScriptInterfaceLegacy { * @param name Name of the control e.g. "play_indicator" * @returns Default value of the specified control normalized to range of 0..1 */ - public getDefaultParameter(group:string, name:string):number; + function getDefaultParameter(group:string, name:string):number; /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * @details This connection has a FIFO buffer - all value change events are processed in serial order. @@ -71,7 +73,7 @@ declare class ControllerScriptInterfaceLegacy { * @param name Name of the control e.g. "play_indicator" * @param callback JS function, which will be called everytime, the value of the connected control changes. */ - public makeConnection(group:string, name:string, callback:(value:number, group:string, name:string)=>any):any; + function makeConnection(group:string, name:string, callback:(value:number, group:string, name:string)=>any):any; /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * @details This connection is unbuffered - when value change events occur faster, than the mapping can process them, @@ -80,10 +82,10 @@ declare class ControllerScriptInterfaceLegacy { * @param name Name of the control e.g. "VuMeter" * @param callback JS function, which will be called everytime, the value of the connected control changes. */ - public makeUnbufferedConnection(group:string, name:string, callback:(value:number, group:string, name:string)=>any):any; + function makeUnbufferedConnection(group:string, name:string, callback:(value:number, group:string, name:string)=>any):any; /** @deprecated Use makeConnection instead */ - public connectControl(group:string, name:string, passedCallback:(value:number, group:string, name:string)=>any, disconnect:boolean = false):any; + function connectControl(group:string, name:string, passedCallback:(value:number, group:string, name:string)=>any, disconnect:boolean = false):any; /** @@ -91,10 +93,10 @@ declare class ControllerScriptInterfaceLegacy { * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" */ - public trigger(group:string, name:string):void; + function trigger(group:string, name:string):void; /** @deprecated Use console.log instead */ - public log(message:string):void; + function log(message:string):void; /** * Starts a timer that will call the specified script function @@ -104,17 +106,17 @@ declare class ControllerScriptInterfaceLegacy { * you can also use closures as: * function() { print("Executed Timer") } * @param oneShot If true the function is only once, - * if false the function is executed repeatedly + * if false the function is executed repeatedly [default = false] * @returns timerId which is needed to stop a timer. * In case of an error, 0 is returned. */ - public beginTimer(interval:number, scriptCode:()=>any, oneShot:boolean = false):number; + function beginTimer(interval:number, scriptCode:()=>any, oneShot?:boolean):number; /** * Stops the specified timer * @param timerId ID of the timer */ - public stopTimer(timerId:number):void; + function stopTimer(timerId:number):void; /** * Jogwheel function to be called when scratching starts (usually when the wheel is touched) @@ -125,30 +127,30 @@ declare class ControllerScriptInterfaceLegacy { * @param rpm The speed of the imaginary record at 0% pitch (in revolutions per minute (RPM) typically 33+1/3, adjust for comfort) * @param alpha The alpha coefficient of the filter (start with 1/8 (0.125) and tune from there) * @param beta The beta coefficient of the filter (start with alpha/32 and tune from there) - * @param ramp Set true to ramp the deck speed down. Set false to stop instantly + * @param ramp Set true to ramp the deck speed down. Set false to stop instantly [default = true] */ - public scratchEnable(deck:number, intervalsPerRev:number, rpm:number, alpha:number, beta:number, ramp:boolean = true):void; + function scratchEnable(deck:number, intervalsPerRev:number, rpm:number, alpha:number, beta:number, ramp?:boolean):void; /** * Function to be called each time the jogwheel is moved during scratching * @param deck The deck number to use, e.g: 1 * @param interval The movement value (typically 1 for one "tick" forwards, -1 for one "tick" backwards) */ - public scratchTick(deck:number, interval:number):void; + function scratchTick(deck:number, interval:number):void; /** * Jogwheel function to be called when scratching ends (usually when the wheel is released) * @param deck The deck number to use, e.g: 1 - * @param ramp Set true to ramp the deck speed up. Set false to jump to normal play speed instantly + * @param ramp Set true to ramp the deck speed up. Set false to jump to normal play speed instantly [default = true] */ - public scratchDisable(deck:number, ramp:boolean = true):void; + function scratchDisable(deck:number, ramp?:boolean):void; /** * Returns true if scratching is enabled * @param deck The deck number to use, e.g: 1 * @returns True if scratching is enabled */ - public isScratching(deck:number):boolean; + function isScratching(deck:number):boolean; /** * If enabled, soft-takeover prevents sudden wide parameter changes, @@ -159,7 +161,7 @@ declare class ControllerScriptInterfaceLegacy { * @param name Name of the control e.g. "pregain" * @param enable Set true to enable soft-takeover for the specified control */ - public softTakeover(group:string, name:string, enable:boolean):void; + function softTakeover(group:string, name:string, enable:boolean):void; /** * Inhibits a suden value change from the hardware control. @@ -168,7 +170,7 @@ declare class ControllerScriptInterfaceLegacy { * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "pregain" */ - public softTakeoverIgnoreNextValue(group:string, name:string):void; + function softTakeoverIgnoreNextValue(group:string, name:string):void; /** * To achieve a brake effect of the playback speed @@ -178,11 +180,11 @@ declare class ControllerScriptInterfaceLegacy { * @param factor Defines how quickly the deck should come to a stop. * Start with a value of 1 and increase to increase the acceleration. * Be aware that brake called with low factors (about 0.5 and lower), - * would keep the deck running altough the resulting very low sounds are not audible anymore. + * would keep the deck running altough the resulting very low sounds are not audible anymore. [default = 1.0] * @param rate The initial speed of the deck when enabled. "1" (default) means 10x speed in forward. - * Negative values like "-1" also work, though then it's spinning reverse obviously. + * Negative values like "-1" also work, though then it's spinning reverse obviously. [default = 1.0] */ - public brake(deck:number, activate:boolean, factor:number = 1.0, rate:number = 1.0):void; + function brake(deck:number, activate:boolean, factor?:number, rate?:number):void; /** * To achieve a spinback effect of the playback speed @@ -192,11 +194,11 @@ declare class ControllerScriptInterfaceLegacy { * @param factor Defines how quickly the deck should come to normal playback rate. * Start with a value of 1 and increase to increase the acceleration. * Be aware that spinback called with low factors (about 0.5 and lower), - * would keep the deck running altough the resulting very low sounds are not audible anymore. + * would keep the deck running altough the resulting very low sounds are not audible anymore. [default = 1.8] * @param rate The initial speed of the deck when enabled. "-10" (default) means 10x speed in reverse. - * Positive values like "10" also work, though then it's spinning forward obviously. + * Positive values like "10" also work, though then it's spinning forward obviously. [default = -10.0] */ - public spinback(deck:number, activate:boolean, factor:number = 1.8, rate:number = -10.0):void; + function spinback(deck:number, activate:boolean, factor?:number, rate?:number):void; /** * To achieve a forward acceleration effect from standstill to normal speed. @@ -205,8 +207,7 @@ declare class ControllerScriptInterfaceLegacy { * @param activate Set true to activate, or false to disable * @param factor Defines how quickly the deck should come to normal playback rate. * Start with a value of 1 and increase to increase the acceleration. - * SoftStart with low factors would take a while until sound is audible. + * SoftStart with low factors would take a while until sound is audible. [default = 1.0] */ - public softStart(deck:number, activate:boolean, factor:number = 1.0):void; + function softStart(deck:number, activate:boolean, factor?:number):void; } -var engine = new ControllerScriptInterfaceLegacy; diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index 3963a791272..edc89221561 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -1,26 +1,28 @@ -declare class HidControllerJSProxy { +/** HidControllerJSProxy */ + +declare namespace controller { /** Sends HID OutputReport with hard coded ReportID 0 to HID device * This function only works with HID devices, which don't use ReportIDs * @param dataList Data to send as list of bytes - * @param length This optional argument is no longer evaluated, and only here for backwards compatibility + * @param length This optional argument is no longer evaluated, and only here for backwards compatibility [default = 0] */ - public send(dataList:number[], length:number=0):void; + function send(dataList:number[], length?:number):void; /** Sends HID OutputReport to HID device * @param dataList Data to send as list of bytes * @param length Unused but mandatory argument * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs - * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending + * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending [default = false] */ - public send(dataList:number[], length:number, reportID:number, resendUnchangedReport:boolean = false):void; + function send(dataList:number[], length:number, reportID:number, resendUnchangedReport?:boolean):void; /** Sends an OutputReport to HID device * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs * @param dataArray Data to send as byte array (Javascript type Uint8Array) - * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending + * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending [default = false] */ - public sendOutputReport(reportID:number, dataArray:ArrayBuffer, resendUnchangedReport:boolean = false):void; + function sendOutputReport(reportID:number, dataArray:ArrayBuffer, resendUnchangedReport?:boolean):void; /** getInputReport receives an InputReport from the HID device on request. * @details This can be used on startup to initialize the knob positions in Mixxx @@ -29,19 +31,18 @@ declare class HidControllerJSProxy { * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @return Returns report data with ReportID byte as prefix */ - public getInputReport(reportID:number):Uint8Array; + function getInputReport(reportID:number):Uint8Array; /** Sends a FeatureReport to HID device * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @param reportData Data to send as byte array */ - public sendFeatureReport(reportID:number, reportData:ArrayBuffer):void; + function sendFeatureReport(reportID:number, reportData:ArrayBuffer):void; /** getFeatureReport receives a FeatureReport from the HID device on request. * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @return The returned array matches the input format of sendFeatureReport, * allowing it to be read, modified and sent it back to the controller. */ - public getFeatureReport(reportID:number):Uint8Array; + function getFeatureReport(reportID:number):Uint8Array; } -var controller = new HidControllerJSProxy; diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts index 51e9ad576d9..fb66a47f929 100644 --- a/res/controllers/midi-controller-api.d.ts +++ b/res/controllers/midi-controller-api.d.ts @@ -1,5 +1,7 @@ -declare class MidiControllerJSProxy { +/** MidiControllerJSProxy */ + +declare namespace controller { /** * Sends a 3 byte MIDI short message @@ -7,22 +9,21 @@ declare class MidiControllerJSProxy { * @param byte1 Data byte 1 * @param byte2 Data byte 2 */ - public sendShortMsg(status:number, byte1:number, byte2:number):void; + function sendShortMsg(status:number, byte1:number, byte2:number):void; /** * Alias for {@link sendSysexMsg} * Sends a MIDI system-exclusive message of arbitrary number of bytes * @param dataList List of bytes to send - * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts + * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts [default = 0] */ - public send(dataList:number[], length:number=0):void; + function send(dataList:number[], length?:number):void; /** * Sends a MIDI system-exclusive message of arbitrary number of bytes * @param dataList List of bytes to send - * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts + * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts [default = 0] */ - public sendSysexMsg(dataList:number[], length:number=0):void; + function sendSysexMsg(dataList:number[], length?:number):void; } -var controller = new MidiControllerJSProxy; From 28b9e1a752adfc970b6187db7c42118642e2de7e Mon Sep 17 00:00:00 2001 From: Joerg Date: Sun, 22 Jan 2023 13:35:29 +0100 Subject: [PATCH 15/34] Added declaration for ColorMapper class --- res/controllers/color-mapper-api.d.ts | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 res/controllers/color-mapper-api.d.ts diff --git a/res/controllers/color-mapper-api.d.ts b/res/controllers/color-mapper-api.d.ts new file mode 100644 index 00000000000..b714ab10780 --- /dev/null +++ b/res/controllers/color-mapper-api.d.ts @@ -0,0 +1,20 @@ + +/** ColorMapperJSProxy */ + +class ColorMapper { +// Passing a QMap argument to the constructor as needed by + // the ColorMapper constructor segfaults. QJSEngine converts a JS object to + // a QVariantMap, so this constructor converts the QVariantMap to a + // QMap. + constructor (availableColors:{ [rgb: number]:number }):void; + + /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest + /// available color and returns a JS object with properties "red", "green", + /// "blue" (each with value range 0-255). + getNearestColor(ColorCode:number):{[rgb: number]:number}; + + /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest + /// available color, then returns the value associated with that color + /// (which could be a MIDI byte value for example). + getValueForNearestColor(ColorCode: number):number; +} From fb18a2c0b7e18a40726170dac87ae91a4b6e69da Mon Sep 17 00:00:00 2001 From: Joerg Date: Fri, 7 Apr 2023 11:15:41 +0200 Subject: [PATCH 16/34] Improved console-api.d.ts --- res/controllers/console-api.d.ts | 76 +++++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 22 deletions(-) diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index fe8b18c191a..bb05be4fd8a 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -1,6 +1,9 @@ /** Mixxx installs the QJSEngine::ConsoleExtension for the use in controller mapping scripts. - See also: https://doc.qt.io/qt-5/qtquick-debugging.html#console-api + See also: + https://doc.qt.io/qt-5/qtquick-debugging.html#console-api + https://developer.mozilla.org/en-US/docs/Web/API/console + https://console.spec.whatwg.org/ */ declare namespace console { @@ -9,97 +12,126 @@ declare namespace console { * QT_LOGGING_RULES="js.debug=true;" or * Mixxx is started with --controller-debug * This fuction is identical to console.debug + * + * @param data Message to print + * - Either a list of objects whose string representations get concatenated into the message string + * - Or a string containing zero or more substitution strings followed by a list of objects to replace them */ - function log(message?:any, ...args:any[]):void; + function log(...data: any[]): void; /** * Prints debugging information to the console, when * QT_LOGGING_RULES="js.debug=true;" or * Mixxx is started with --controller-debug * This function is identical to console.log + * + * @param data Message to print + * - Either a list of objects whose string representations get concatenated into the message string + * - Or a string containing zero or more substitution strings followed by a list of objects to replace them */ - function debug(message?:any, ...args:any[]):void; + function debug(...data: any[]): void; /** * Prints information to the console, when * QT_LOGGING_RULES="js.info=true;" or * Mixxx is started with --controller-debug + * + * @param data Message to print + * - Either a list of objects whose string representations get concatenated into the message string + * - Or a string containing zero or more substitution strings followed by a list of objects to replace them */ - function info(message?:any, ...args:any[]):void; + function info(...data: any[]): void; /** * Prints a warning message to the console, when * QT_LOGGING_RULES="js.warning=true;" or * Mixxx is started with --controller-debug + * + * @param data Message to print + * - Either a list of objects whose string representations get concatenated into the message string + * - Or a string containing zero or more substitution strings followed by a list of objects to replace them */ - function warn(message?:any, ...args:any[]):void; + function warn(...data: any[]): void; /** * Prints an error message to the console, when * QT_LOGGING_RULES="js.critical=true;" or * Mixxx is started with --controller-debug + * + * @param data Message to print + * - Either a list of objects whose string representations get concatenated into the message string + * - Or a string containing zero or more substitution strings followed by a list of objects to replace them */ - function error(message?:any, ...args:any[]):void; + function error(...data: any[]): void; /** - * Tests that an expression is true. + * Tests that a boolean expression is true, + * if not, it writes an (optional) message to the console and prints the stack trace. * - * @param expression If not true, it writes an optional message to the console and prints the stack trace. - * @param message - * @param args + * @param condition If the condition is false, it prints message and stack trace + * @param data Message to print + * - Either a list of objects whose string representations get concatenated into the message string + * - Or a string containing zero or more substitution strings followed by a list of objects to replace them */ - function assert(expression:boolean, message?:string, ...args: any[]):void; + function assert(condition: boolean, ...data: any[]): void; /** * Starts the time measurement, which will be printed by timeEnd * * @param label string argument that identifies the measurement. */ - function time(label?:string):void; + function time(label?: string): void; /** * Logs the time (in milliseconds) that was spent since the call of the time method. * * @param label string argument that identifies the measurement. */ - function timeEnd(label?:string):void; + function timeEnd(label?: string): void; /** * Prints the stack trace of the JavaScript execution at the point where it was called. * This stack trace information contains the function name, file name, line number, and column number. * The stack trace is limited to last 10 stack frames. * - * @param message - * @param args + * Unfortunately this function does use the wrong logging category "default" instead of "js", + * which is set when you start Mixxx with --controller-debug. Without setting logging category + * "default" manually, you will not see any output. + * [see QTBUG-108673]{@link https://bugreports.qt.io/browse/QTBUG-108673} + * + * @param data Message to print + * - Either a list of objects whose string representations get concatenated into the message string + * - Or a string containing zero or more substitution strings followed by a list of objects to replace them */ - function trace(message?:any, ...args:any[]):void; + function trace(...data: any[]): void; /** * Prints the current number of times a particular piece of code has run, along with a message. * * @param label */ - function count(label?:string):void; + function count(label?: string): void; /** * Turns on the JavaScript profiler. * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} * */ - function profile(label?:string):void; + function profile(label?: string): void; /** * Turns off the JavaScript profiler. * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} * */ - function profileEnd(label?:string):void; + function profileEnd(label?: string): void; /** * Prints an error message together with the stack trace of JavaScript execution at the point where it is called. * - * @param message - * @param args + * @param data Message to print + * - Either a list of objects whose string representations get concatenated into the message string + * - Or a string containing zero or more substitution strings followed by a list of objects to replace them */ - function exception(message?:any, ...args:any[]):void; + function exception(...data: any[]): void; } From 8deaaeab62838ea54ebd185512bbbe2ea2b8f5e2 Mon Sep 17 00:00:00 2001 From: Joerg Date: Fri, 7 Apr 2023 12:04:18 +0200 Subject: [PATCH 17/34] Adjusted spacing to the style used in the typescript docs Small syntax fixes --- res/controllers/color-mapper-api.d.ts | 8 ++-- res/controllers/engine-api.d.ts | 48 ++++++++++++------------ res/controllers/hid-controller-api.d.ts | 12 +++--- res/controllers/midi-controller-api.d.ts | 6 +-- 4 files changed, 37 insertions(+), 37 deletions(-) diff --git a/res/controllers/color-mapper-api.d.ts b/res/controllers/color-mapper-api.d.ts index b714ab10780..5c3897f1c7d 100644 --- a/res/controllers/color-mapper-api.d.ts +++ b/res/controllers/color-mapper-api.d.ts @@ -1,20 +1,20 @@ /** ColorMapperJSProxy */ -class ColorMapper { +declare class ColorMapper { // Passing a QMap argument to the constructor as needed by // the ColorMapper constructor segfaults. QJSEngine converts a JS object to // a QVariantMap, so this constructor converts the QVariantMap to a // QMap. - constructor (availableColors:{ [rgb: number]:number }):void; + constructor (availableColors: { [rgb: number]: number }); /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest /// available color and returns a JS object with properties "red", "green", /// "blue" (each with value range 0-255). - getNearestColor(ColorCode:number):{[rgb: number]:number}; + getNearestColor(ColorCode: number): {[rgb: number]: number}; /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest /// available color, then returns the value associated with that color /// (which could be a MIDI byte value for example). - getValueForNearestColor(ColorCode: number):number; + getValueForNearestColor(ColorCode: number): number; } diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index 166ae11f9ce..a0a17a5e4d0 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -8,7 +8,7 @@ declare namespace engine { * @param name Name of the control e.g. "play_indicator" * @returns Value of the control (within it's range according Mixxx Controls manual page) */ - function getValue(group:string, name:string):number; + function getValue(group: string, name: string): number; /** * Sets a control value @@ -16,7 +16,7 @@ declare namespace engine { * @param name Name of the control e.g. "play_indicator" * @param newValue Value to be set (within it's range according Mixxx Controls manual page) */ - function setValue(group:string, name:string, newValue: number):void; + function setValue(group: string, name: string, newValue: number): void; /** * Gets the control value normalized to a range of 0..1 @@ -24,7 +24,7 @@ declare namespace engine { * @param name Name of the control e.g. "play_indicator" * @returns Value of the control normalized to range of 0..1 */ - function getParameter(group:string, name:string):number; + function getParameter(group: string, name: string): number; /** * Sets the control value specified with normalized range of 0..1 @@ -32,7 +32,7 @@ declare namespace engine { * @param name Name of the control e.g. "play_indicator" * @param newValue Value to be set, normalized to a range of 0..1 */ - function setParameter(group:string, name:string, newValue:number):void; + function setParameter(group: string, name: string, newValue: number): void; /** * Normalizes a specified value using the range of the given control, @@ -42,14 +42,14 @@ declare namespace engine { * @param value Value with the controls range according Mixxx Controls manual page * @returns Value normalized to range of 0..1 */ - function getParameterForValue(group:string, name:string, value:number):number; + function getParameterForValue(group: string, name: string, value: number): number; /** * Resets the control to its default value * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" */ - function reset(group:string, name:string):void; + function reset(group: string, name: string): void; /** * Returns the default value of a control @@ -57,7 +57,7 @@ declare namespace engine { * @param name Name of the control e.g. "play_indicator" * @returns Default value with the controls range according Mixxx Controls manual page */ - function getDefaultValue(group:string, name:string):number; + function getDefaultValue(group: string, name: string): number; /** * Returns the default value of a control, normalized to a range of 0..1 @@ -65,7 +65,7 @@ declare namespace engine { * @param name Name of the control e.g. "play_indicator" * @returns Default value of the specified control normalized to range of 0..1 */ - function getDefaultParameter(group:string, name:string):number; + function getDefaultParameter(group: string, name: string): number; /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * @details This connection has a FIFO buffer - all value change events are processed in serial order. @@ -73,7 +73,7 @@ declare namespace engine { * @param name Name of the control e.g. "play_indicator" * @param callback JS function, which will be called everytime, the value of the connected control changes. */ - function makeConnection(group:string, name:string, callback:(value:number, group:string, name:string)=>any):any; + function makeConnection(group: string, name: string, callback: (value: number, group: string, name: string)=>any): any; /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * @details This connection is unbuffered - when value change events occur faster, than the mapping can process them, @@ -82,10 +82,10 @@ declare namespace engine { * @param name Name of the control e.g. "VuMeter" * @param callback JS function, which will be called everytime, the value of the connected control changes. */ - function makeUnbufferedConnection(group:string, name:string, callback:(value:number, group:string, name:string)=>any):any; + function makeUnbufferedConnection(group: string, name: string, callback: (value: number, group: string, name: string)=>any): any; /** @deprecated Use makeConnection instead */ - function connectControl(group:string, name:string, passedCallback:(value:number, group:string, name:string)=>any, disconnect:boolean = false):any; + function connectControl(group: string, name: string, passedCallback: (value: number, group: string, name: string)=>any, disconnect?:boolean): any; /** @@ -93,10 +93,10 @@ declare namespace engine { * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" */ - function trigger(group:string, name:string):void; + function trigger(group: string, name: string): void; /** @deprecated Use console.log instead */ - function log(message:string):void; + function log(message: string): void; /** * Starts a timer that will call the specified script function @@ -110,13 +110,13 @@ declare namespace engine { * @returns timerId which is needed to stop a timer. * In case of an error, 0 is returned. */ - function beginTimer(interval:number, scriptCode:()=>any, oneShot?:boolean):number; + function beginTimer(interval: number, scriptCode: ()=>any, oneShot?: boolean): number; /** * Stops the specified timer * @param timerId ID of the timer */ - function stopTimer(timerId:number):void; + function stopTimer(timerId: number): void; /** * Jogwheel function to be called when scratching starts (usually when the wheel is touched) @@ -129,28 +129,28 @@ declare namespace engine { * @param beta The beta coefficient of the filter (start with alpha/32 and tune from there) * @param ramp Set true to ramp the deck speed down. Set false to stop instantly [default = true] */ - function scratchEnable(deck:number, intervalsPerRev:number, rpm:number, alpha:number, beta:number, ramp?:boolean):void; + function scratchEnable(deck: number, intervalsPerRev: number, rpm: number, alpha: number, beta: number, ramp?: boolean): void; /** * Function to be called each time the jogwheel is moved during scratching * @param deck The deck number to use, e.g: 1 * @param interval The movement value (typically 1 for one "tick" forwards, -1 for one "tick" backwards) */ - function scratchTick(deck:number, interval:number):void; + function scratchTick(deck: number, interval: number): void; /** * Jogwheel function to be called when scratching ends (usually when the wheel is released) * @param deck The deck number to use, e.g: 1 * @param ramp Set true to ramp the deck speed up. Set false to jump to normal play speed instantly [default = true] */ - function scratchDisable(deck:number, ramp?:boolean):void; + function scratchDisable(deck: number, ramp?: boolean): void; /** * Returns true if scratching is enabled * @param deck The deck number to use, e.g: 1 * @returns True if scratching is enabled */ - function isScratching(deck:number):boolean; + function isScratching(deck: number): boolean; /** * If enabled, soft-takeover prevents sudden wide parameter changes, @@ -161,7 +161,7 @@ declare namespace engine { * @param name Name of the control e.g. "pregain" * @param enable Set true to enable soft-takeover for the specified control */ - function softTakeover(group:string, name:string, enable:boolean):void; + function softTakeover(group: string, name: string, enable: boolean): void; /** * Inhibits a suden value change from the hardware control. @@ -170,7 +170,7 @@ declare namespace engine { * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "pregain" */ - function softTakeoverIgnoreNextValue(group:string, name:string):void; + function softTakeoverIgnoreNextValue(group: string, name: string): void; /** * To achieve a brake effect of the playback speed @@ -184,7 +184,7 @@ declare namespace engine { * @param rate The initial speed of the deck when enabled. "1" (default) means 10x speed in forward. * Negative values like "-1" also work, though then it's spinning reverse obviously. [default = 1.0] */ - function brake(deck:number, activate:boolean, factor?:number, rate?:number):void; + function brake(deck: number, activate: boolean, factor?: number, rate?: number): void; /** * To achieve a spinback effect of the playback speed @@ -198,7 +198,7 @@ declare namespace engine { * @param rate The initial speed of the deck when enabled. "-10" (default) means 10x speed in reverse. * Positive values like "10" also work, though then it's spinning forward obviously. [default = -10.0] */ - function spinback(deck:number, activate:boolean, factor?:number, rate?:number):void; + function spinback(deck: number, activate: boolean, factor?: number, rate?: number): void; /** * To achieve a forward acceleration effect from standstill to normal speed. @@ -209,5 +209,5 @@ declare namespace engine { * Start with a value of 1 and increase to increase the acceleration. * SoftStart with low factors would take a while until sound is audible. [default = 1.0] */ - function softStart(deck:number, activate:boolean, factor?:number):void; + function softStart(deck: number, activate: boolean, factor?: number): void; } diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index edc89221561..0a1f01e86f8 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -7,7 +7,7 @@ declare namespace controller { * @param dataList Data to send as list of bytes * @param length This optional argument is no longer evaluated, and only here for backwards compatibility [default = 0] */ - function send(dataList:number[], length?:number):void; + function send(dataList: number[], length?: number): void; /** Sends HID OutputReport to HID device * @param dataList Data to send as list of bytes @@ -15,14 +15,14 @@ declare namespace controller { * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending [default = false] */ - function send(dataList:number[], length:number, reportID:number, resendUnchangedReport?:boolean):void; + function send(dataList: number[], length: number, reportID: number, resendUnchangedReport?: boolean): void; /** Sends an OutputReport to HID device * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs * @param dataArray Data to send as byte array (Javascript type Uint8Array) * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending [default = false] */ - function sendOutputReport(reportID:number, dataArray:ArrayBuffer, resendUnchangedReport?:boolean):void; + function sendOutputReport(reportID: number, dataArray: ArrayBuffer, resendUnchangedReport?: boolean): void; /** getInputReport receives an InputReport from the HID device on request. * @details This can be used on startup to initialize the knob positions in Mixxx @@ -31,18 +31,18 @@ declare namespace controller { * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @return Returns report data with ReportID byte as prefix */ - function getInputReport(reportID:number):Uint8Array; + function getInputReport(reportID: number): Uint8Array; /** Sends a FeatureReport to HID device * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @param reportData Data to send as byte array */ - function sendFeatureReport(reportID:number, reportData:ArrayBuffer):void; + function sendFeatureReport(reportID: number, reportData: ArrayBuffer): void; /** getFeatureReport receives a FeatureReport from the HID device on request. * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @return The returned array matches the input format of sendFeatureReport, * allowing it to be read, modified and sent it back to the controller. */ - function getFeatureReport(reportID:number):Uint8Array; + function getFeatureReport(reportID: number): Uint8Array; } diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts index fb66a47f929..89c1e364445 100644 --- a/res/controllers/midi-controller-api.d.ts +++ b/res/controllers/midi-controller-api.d.ts @@ -9,7 +9,7 @@ declare namespace controller { * @param byte1 Data byte 1 * @param byte2 Data byte 2 */ - function sendShortMsg(status:number, byte1:number, byte2:number):void; + function sendShortMsg(status: number, byte1: number, byte2: number): void; /** * Alias for {@link sendSysexMsg} @@ -17,13 +17,13 @@ declare namespace controller { * @param dataList List of bytes to send * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts [default = 0] */ - function send(dataList:number[], length?:number):void; + function send(dataList: number[], length?: number): void; /** * Sends a MIDI system-exclusive message of arbitrary number of bytes * @param dataList List of bytes to send * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts [default = 0] */ - function sendSysexMsg(dataList:number[], length?:number):void; + function sendSysexMsg(dataList: number[], length?: number): void; } From 989619b52b60b31c29e4df537246a09a78a2cd11 Mon Sep 17 00:00:00 2001 From: Joerg Date: Fri, 7 Apr 2023 16:31:32 +0200 Subject: [PATCH 18/34] Removed wrong text "Javascript type Uint8Array" --- res/controllers/hid-controller-api.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index 0a1f01e86f8..cc8c61914ac 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -19,7 +19,7 @@ declare namespace controller { /** Sends an OutputReport to HID device * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs - * @param dataArray Data to send as byte array (Javascript type Uint8Array) + * @param dataArray Data to send as byte array * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending [default = false] */ function sendOutputReport(reportID: number, dataArray: ArrayBuffer, resendUnchangedReport?: boolean): void; From a6fa34d059b00e9c1ac0ab1fb8a5884c83fdf529 Mon Sep 17 00:00:00 2001 From: Joerg Date: Fri, 7 Apr 2023 19:03:18 +0200 Subject: [PATCH 19/34] Added ScriptConnection class which is returned by makeConnection etc. ... --- res/controllers/engine-api.d.ts | 71 +++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 7 deletions(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index a0a17a5e4d0..52577186692 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -1,9 +1,32 @@ +/** ScriptConnectionJSProxy */ + +declare class ScriptConnection { + /** + * Disconnect the script connection, + * established by {@link engine.makeConnection} or {@link engine.makeUnbufferedConnection} + * + * @return Returns true if the connection is successful disconnected + */ + disconnect(): boolean; + + /** + * Triggers the execution of the callback function of the script connection, + * established by {@link engine.makeConnection} or {@link engine.makeUnbufferedConnection} + * with the actual value of a control. + * + * Note: To execute all callback functions connected to a ControlObject at once, use {@link engine.trigger} instead + */ + trigger(): void; +} + + /** ControllerScriptInterfaceLegacy */ declare namespace engine { /** * Gets the control value + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @returns Value of the control (within it's range according Mixxx Controls manual page) @@ -12,6 +35,7 @@ declare namespace engine { /** * Sets a control value + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @param newValue Value to be set (within it's range according Mixxx Controls manual page) @@ -20,6 +44,7 @@ declare namespace engine { /** * Gets the control value normalized to a range of 0..1 + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @returns Value of the control normalized to range of 0..1 @@ -28,6 +53,7 @@ declare namespace engine { /** * Sets the control value specified with normalized range of 0..1 + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @param newValue Value to be set, normalized to a range of 0..1 @@ -37,6 +63,7 @@ declare namespace engine { /** * Normalizes a specified value using the range of the given control, * to the range of 0..1 + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @param value Value with the controls range according Mixxx Controls manual page @@ -46,6 +73,7 @@ declare namespace engine { /** * Resets the control to its default value + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" */ @@ -53,6 +81,7 @@ declare namespace engine { /** * Returns the default value of a control + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @returns Default value with the controls range according Mixxx Controls manual page @@ -61,45 +90,66 @@ declare namespace engine { /** * Returns the default value of a control, normalized to a range of 0..1 + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @returns Default value of the specified control normalized to range of 0..1 */ function getDefaultParameter(group: string, name: string): number; + type CoCallback = (value: number, group: string, name: string) => void + /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes + * * @details This connection has a FIFO buffer - all value change events are processed in serial order. * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" - * @param callback JS function, which will be called everytime, the value of the connected control changes. + * @param callback JS function, which will be called everytime, the value of the connected control changes. + * @return Returns script connection object on success, otherwise 'undefined'' */ - function makeConnection(group: string, name: string, callback: (value: number, group: string, name: string)=>any): any; + function makeConnection(group: string, name: string, callback: CoCallback): ScriptConnection |undefined; /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes + * * @details This connection is unbuffered - when value change events occur faster, than the mapping can process them, * only the last value set for the control is processed. * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "VuMeter" * @param callback JS function, which will be called everytime, the value of the connected control changes. + * @return Returns script connection object on success, otherwise 'undefined'' */ - function makeUnbufferedConnection(group: string, name: string, callback: (value: number, group: string, name: string)=>any): any; + function makeUnbufferedConnection(group: string, name: string, callback: CoCallback): ScriptConnection | undefined; - /** @deprecated Use makeConnection instead */ - function connectControl(group: string, name: string, passedCallback: (value: number, group: string, name: string)=>any, disconnect?:boolean): any; + /** This function is a legacy version of makeConnection with several alternate + * ways of invoking it. The callback function can be passed either as a string of + * JavaScript code that evaluates to a function or an actual JavaScript function. + * + * @param group Group of the control e.g. "[Channel1]" + * @param name Name of the control e.g. "VuMeter" + * @param callback JS function, which will be called everytime, the value of the connected control changes. + * @param disconnect If "true", all connections to the ControlObject are removed. [default = false] + * @return Returns script connection object on success, otherwise 'undefined' or 'false' depending on the error cause. + * + * @deprecated Use {@link makeConnection} instead + */ + function connectControl(group: string, name: string, callback: CoCallback, disconnect?: boolean): ScriptConnection | boolean | undefined; /** - * Triggers the execution of the connected callback functions, with the actual value of a control + * Triggers the execution of all connected callback functions, with the actual value of a control. + * Note: To trigger a single connection, us {@link ScriptConnection.trigger} instead + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" */ function trigger(group: string, name: string): void; - /** @deprecated Use console.log instead */ + /** @deprecated Use {@link console.log} instead */ function log(message: string): void; /** * Starts a timer that will call the specified script function + * * @param interval Time in milliseconds until the function is executed. * Intervals below 20ms are not allowed. * @param scriptCode Function to be executed, @@ -114,6 +164,7 @@ declare namespace engine { /** * Stops the specified timer + * * @param timerId ID of the timer */ function stopTimer(timerId: number): void; @@ -122,6 +173,7 @@ declare namespace engine { * Jogwheel function to be called when scratching starts (usually when the wheel is touched) * This function contains an parametrizeable alpha-beta filter, which influences the * responsiveness and looseness of the imaginary slip mat + * * @param deck The deck number to use, e.g: 1 * @param intervalsPerRev The resolution of the MIDI control (in intervals per revolution, typically 128.) * @param rpm The speed of the imaginary record at 0% pitch (in revolutions per minute (RPM) typically 33+1/3, adjust for comfort) @@ -133,6 +185,7 @@ declare namespace engine { /** * Function to be called each time the jogwheel is moved during scratching + * * @param deck The deck number to use, e.g: 1 * @param interval The movement value (typically 1 for one "tick" forwards, -1 for one "tick" backwards) */ @@ -167,6 +220,7 @@ declare namespace engine { * Inhibits a suden value change from the hardware control. * Should be called when receiving input for the knob/fader, * that switches its behavior (e.g. Shift-Button pressed) + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "pregain" */ @@ -175,6 +229,7 @@ declare namespace engine { /** * To achieve a brake effect of the playback speed * Both engine.softStart() and engine.brake()/engine.spinback() can interrupt each other. + * * @param deck The deck number to use, e.g: 1 * @param activate Set true to activate, or false to disable * @param factor Defines how quickly the deck should come to a stop. @@ -189,6 +244,7 @@ declare namespace engine { /** * To achieve a spinback effect of the playback speed * Both engine.softStart() and engine.brake()/engine.spinback() can interrupt each other. + * * @param deck The deck number to use, e.g: 1 * @param activate Set true to activate, or false to disable * @param factor Defines how quickly the deck should come to normal playback rate. @@ -203,6 +259,7 @@ declare namespace engine { /** * To achieve a forward acceleration effect from standstill to normal speed. * Both engine.softStart() and engine.brake()/engine.spinback() can interrupt each other. + * * @param deck The deck number to use, e.g: 1 * @param activate Set true to activate, or false to disable * @param factor Defines how quickly the deck should come to normal playback rate. From ab94500b674c73bc692f93fb0822d59459b519d1 Mon Sep 17 00:00:00 2001 From: Joerg Date: Fri, 7 Apr 2023 21:37:22 +0200 Subject: [PATCH 20/34] Added @typescript-eslint to pre-commit --- .eslintrc.json | 14 ++++++++++++-- .pre-commit-config.yaml | 8 +++++--- res/controllers/engine-api.d.ts | 23 ++++++++++++++--------- 3 files changed, 31 insertions(+), 14 deletions(-) diff --git a/.eslintrc.json b/.eslintrc.json index 784a383b209..54ae380bd64 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -1,5 +1,9 @@ { - "extends": [ "eslint:recommended", "plugin:jsdoc/recommended" ], + "extends": [ "eslint:recommended", + "plugin:jsdoc/recommended", + "plugin:@typescript-eslint/recommended" ], + + "parser": "@typescript-eslint/parser", "parserOptions": { "ecmaVersion": 7, "sourceType": "script" @@ -7,7 +11,7 @@ "env": { "es6": true }, - "plugins": [ "jsdoc" ], + "plugins": [ "jsdoc", "@typescript-eslint" ], "settings": { "jsdoc": { "preferredTypes": { @@ -93,6 +97,12 @@ "console": "readonly" }, "overrides": [ + { + "files": [ "res/controllers/*.d.ts" ], + "rules": { + "no-unused-vars": "off" + } + }, { "files": [ "**/*.mjs" ], "parserOptions": { diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c459495d97e..ab1964d6fc6 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -45,7 +45,7 @@ repos: - id: end-of-file-fixer - id: mixed-line-ending - id: trailing-whitespace - exclude: \.(c|cc|cxx|cpp|frag|glsl|h|hpp|hxx|ih|ispc|ipp|java|js|m|mm|proto|vert)$ + exclude: \.(c|cc|cxx|cpp|d.ts|frag|glsl|h|hpp|hxx|ih|ispc|ipp|java|js|m|mm|proto|vert)$ - id: no-commit-to-branch # protect main and any branch that has a semver-like name args: [-b, main, -p, '^\d+\.\d+(?:\.\d+)?$'] @@ -62,13 +62,13 @@ repos: --ignore-regex, "\\W(?:m_p*(?=[A-Z])|m_(?=\\w)|pp*(?=[A-Z])|k(?=[A-Z])|s_(?=\\w))", ] - exclude: ^(packaging/wix/LICENSE.rtf|src/dialog/dlgabout\.cpp|.*\.(?:pot?|ts|wxl|svg))$ + exclude: ^(packaging/wix/LICENSE.rtf|src/dialog/dlgabout\.cpp|.*\.(?:pot?|(?!d.ts)|ts|wxl|svg))$ - repo: https://github.com/pre-commit/mirrors-eslint rev: v8.25.0 hooks: - id: eslint args: [--fix, --report-unused-disable-directives] - files: \.m?js$ + files: \.m?[jt]s$ types: [file] stages: - commit @@ -76,6 +76,8 @@ repos: additional_dependencies: - eslint@^v8.6.0 - eslint-plugin-jsdoc@^v37.5.0 + - "@typescript-eslint/eslint-plugin" + - "@typescript-eslint/parser" - repo: local hooks: - id: clang-format diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index 52577186692..ba29ca73710 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -6,7 +6,7 @@ declare class ScriptConnection { * Disconnect the script connection, * established by {@link engine.makeConnection} or {@link engine.makeUnbufferedConnection} * - * @return Returns true if the connection is successful disconnected + * @returns Returns true if the connection is successful disconnected */ disconnect(): boolean; @@ -16,7 +16,7 @@ declare class ScriptConnection { * with the actual value of a control. * * Note: To execute all callback functions connected to a ControlObject at once, use {@link engine.trigger} instead - */ + */ trigger(): void; } @@ -99,28 +99,31 @@ declare namespace engine { type CoCallback = (value: number, group: string, name: string) => void - /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes + /** + * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * * @details This connection has a FIFO buffer - all value change events are processed in serial order. * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @param callback JS function, which will be called everytime, the value of the connected control changes. - * @return Returns script connection object on success, otherwise 'undefined'' + * @returns Returns script connection object on success, otherwise 'undefined'' */ function makeConnection(group: string, name: string, callback: CoCallback): ScriptConnection |undefined; - /** Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes + /** + * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * * @details This connection is unbuffered - when value change events occur faster, than the mapping can process them, * only the last value set for the control is processed. * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "VuMeter" * @param callback JS function, which will be called everytime, the value of the connected control changes. - * @return Returns script connection object on success, otherwise 'undefined'' + * @returns Returns script connection object on success, otherwise 'undefined'' */ function makeUnbufferedConnection(group: string, name: string, callback: CoCallback): ScriptConnection | undefined; - /** This function is a legacy version of makeConnection with several alternate + /** + * This function is a legacy version of makeConnection with several alternate * ways of invoking it. The callback function can be passed either as a string of * JavaScript code that evaluates to a function or an actual JavaScript function. * @@ -128,8 +131,7 @@ declare namespace engine { * @param name Name of the control e.g. "VuMeter" * @param callback JS function, which will be called everytime, the value of the connected control changes. * @param disconnect If "true", all connections to the ControlObject are removed. [default = false] - * @return Returns script connection object on success, otherwise 'undefined' or 'false' depending on the error cause. - * + * @returns Returns script connection object on success, otherwise 'undefined' or 'false' depending on the error cause. * @deprecated Use {@link makeConnection} instead */ function connectControl(group: string, name: string, callback: CoCallback, disconnect?: boolean): ScriptConnection | boolean | undefined; @@ -193,6 +195,7 @@ declare namespace engine { /** * Jogwheel function to be called when scratching ends (usually when the wheel is released) + * * @param deck The deck number to use, e.g: 1 * @param ramp Set true to ramp the deck speed up. Set false to jump to normal play speed instantly [default = true] */ @@ -200,6 +203,7 @@ declare namespace engine { /** * Returns true if scratching is enabled + * * @param deck The deck number to use, e.g: 1 * @returns True if scratching is enabled */ @@ -210,6 +214,7 @@ declare namespace engine { * when on-screen control and hardware control divert. * With soft-takeover you need to turn a hardware knob, until it reaches * the position of the on-screen knob - than it takes over control. + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "pregain" * @param enable Set true to enable soft-takeover for the specified control From a04280b819411b2c25963fc3f137a0ae793f5214 Mon Sep 17 00:00:00 2001 From: Joerg Date: Fri, 7 Apr 2023 21:52:18 +0200 Subject: [PATCH 21/34] Fix pre-commit/eslint issues --- res/controllers/color-mapper-api.d.ts | 40 ++++++++++++------------ res/controllers/console-api.d.ts | 21 +++++++------ res/controllers/engine-api.d.ts | 6 ++-- res/controllers/hid-controller-api.d.ts | 35 ++++++++++++++------- res/controllers/midi-controller-api.d.ts | 5 ++- 5 files changed, 63 insertions(+), 44 deletions(-) diff --git a/res/controllers/color-mapper-api.d.ts b/res/controllers/color-mapper-api.d.ts index 5c3897f1c7d..03ea7b124c4 100644 --- a/res/controllers/color-mapper-api.d.ts +++ b/res/controllers/color-mapper-api.d.ts @@ -1,20 +1,20 @@ - -/** ColorMapperJSProxy */ - -declare class ColorMapper { -// Passing a QMap argument to the constructor as needed by - // the ColorMapper constructor segfaults. QJSEngine converts a JS object to - // a QVariantMap, so this constructor converts the QVariantMap to a - // QMap. - constructor (availableColors: { [rgb: number]: number }); - - /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest - /// available color and returns a JS object with properties "red", "green", - /// "blue" (each with value range 0-255). - getNearestColor(ColorCode: number): {[rgb: number]: number}; - - /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest - /// available color, then returns the value associated with that color - /// (which could be a MIDI byte value for example). - getValueForNearestColor(ColorCode: number): number; -} + +/** ColorMapperJSProxy */ + +declare class ColorMapper { +// Passing a QMap argument to the constructor as needed by + // the ColorMapper constructor segfaults. QJSEngine converts a JS object to + // a QVariantMap, so this constructor converts the QVariantMap to a + // QMap. + constructor (availableColors: { [rgb: number]: number }); + + /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest + /// available color and returns a JS object with properties "red", "green", + /// "blue" (each with value range 0-255). + getNearestColor(ColorCode: number): {[rgb: number]: number}; + + /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest + /// available color, then returns the value associated with that color + /// (which could be a MIDI byte value for example). + getValueForNearestColor(ColorCode: number): number; +} diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index bb05be4fd8a..bd175693061 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -1,10 +1,11 @@ -/** Mixxx installs the QJSEngine::ConsoleExtension for the use in controller mapping scripts. +/** + Mixxx installs the QJSEngine::ConsoleExtension for the use in controller mapping scripts. See also: https://doc.qt.io/qt-5/qtquick-debugging.html#console-api https://developer.mozilla.org/en-US/docs/Web/API/console https://console.spec.whatwg.org/ -*/ + */ declare namespace console { /** @@ -16,7 +17,7 @@ declare namespace console { * @param data Message to print * - Either a list of objects whose string representations get concatenated into the message string * - Or a string containing zero or more substitution strings followed by a list of objects to replace them - */ + */ function log(...data: any[]): void; /** @@ -28,7 +29,7 @@ declare namespace console { * @param data Message to print * - Either a list of objects whose string representations get concatenated into the message string * - Or a string containing zero or more substitution strings followed by a list of objects to replace them - */ + */ function debug(...data: any[]): void; /** @@ -39,7 +40,7 @@ declare namespace console { * @param data Message to print * - Either a list of objects whose string representations get concatenated into the message string * - Or a string containing zero or more substitution strings followed by a list of objects to replace them - */ + */ function info(...data: any[]): void; /** @@ -50,7 +51,7 @@ declare namespace console { * @param data Message to print * - Either a list of objects whose string representations get concatenated into the message string * - Or a string containing zero or more substitution strings followed by a list of objects to replace them - */ + */ function warn(...data: any[]): void; /** @@ -61,7 +62,7 @@ declare namespace console { * @param data Message to print * - Either a list of objects whose string representations get concatenated into the message string * - Or a string containing zero or more substitution strings followed by a list of objects to replace them - */ + */ function error(...data: any[]): void; /** @@ -72,7 +73,7 @@ declare namespace console { * @param data Message to print * - Either a list of objects whose string representations get concatenated into the message string * - Or a string containing zero or more substitution strings followed by a list of objects to replace them - */ + */ function assert(condition: boolean, ...data: any[]): void; /** @@ -113,15 +114,15 @@ declare namespace console { /** * Turns on the JavaScript profiler. - * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} * + * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} */ function profile(label?: string): void; /** * Turns off the JavaScript profiler. - * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} * + * @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419} */ function profileEnd(label?: string): void; diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index ba29ca73710..26d0eaa3245 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -102,7 +102,8 @@ declare namespace engine { /** * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * - * @details This connection has a FIFO buffer - all value change events are processed in serial order. + * This connection has a FIFO buffer - all value change events are processed in serial order. + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @param callback JS function, which will be called everytime, the value of the connected control changes. @@ -113,8 +114,9 @@ declare namespace engine { /** * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * - * @details This connection is unbuffered - when value change events occur faster, than the mapping can process them, + * This connection is unbuffered - when value change events occur faster, than the mapping can process them, * only the last value set for the control is processed. + * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "VuMeter" * @param callback JS function, which will be called everytime, the value of the connected control changes. diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index cc8c61914ac..f90fa654e7b 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -2,46 +2,59 @@ /** HidControllerJSProxy */ declare namespace controller { - /** Sends HID OutputReport with hard coded ReportID 0 to HID device + /** + * Sends HID OutputReport with hard coded ReportID 0 to HID device * This function only works with HID devices, which don't use ReportIDs + * * @param dataList Data to send as list of bytes * @param length This optional argument is no longer evaluated, and only here for backwards compatibility [default = 0] - */ + */ function send(dataList: number[], length?: number): void; - /** Sends HID OutputReport to HID device + /** + * Sends HID OutputReport to HID device + * * @param dataList Data to send as list of bytes * @param length Unused but mandatory argument * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending [default = false] - */ + */ function send(dataList: number[], length: number, reportID: number, resendUnchangedReport?: boolean): void; - /** Sends an OutputReport to HID device + /** + * Sends an OutputReport to HID device + * * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs * @param dataArray Data to send as byte array * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending [default = false] */ function sendOutputReport(reportID: number, dataArray: ArrayBuffer, resendUnchangedReport?: boolean): void; - /** getInputReport receives an InputReport from the HID device on request. - * @details This can be used on startup to initialize the knob positions in Mixxx + /** + * getInputReport receives an InputReport from the HID device on request. + * + * This can be used on startup to initialize the knob positions in Mixxx * to the physical position of the hardware knobs on the controller. * This is an optional command in the HID standard - not all devices support it. + * * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use - * @return Returns report data with ReportID byte as prefix + * @returns Returns report data with ReportID byte as prefix */ function getInputReport(reportID: number): Uint8Array; - /** Sends a FeatureReport to HID device + /** + * Sends a FeatureReport to HID device + * * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @param reportData Data to send as byte array */ function sendFeatureReport(reportID: number, reportData: ArrayBuffer): void; - /** getFeatureReport receives a FeatureReport from the HID device on request. + /** + * getFeatureReport receives a FeatureReport from the HID device on request. + * * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use - * @return The returned array matches the input format of sendFeatureReport, + * @returns The returned array matches the input format of sendFeatureReport, * allowing it to be read, modified and sent it back to the controller. */ function getFeatureReport(reportID: number): Uint8Array; diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts index 89c1e364445..edf1c2e45f8 100644 --- a/res/controllers/midi-controller-api.d.ts +++ b/res/controllers/midi-controller-api.d.ts @@ -5,6 +5,7 @@ declare namespace controller { /** * Sends a 3 byte MIDI short message + * * @param status Status byte * @param byte1 Data byte 1 * @param byte2 Data byte 2 @@ -14,13 +15,15 @@ declare namespace controller { /** * Alias for {@link sendSysexMsg} * Sends a MIDI system-exclusive message of arbitrary number of bytes + * * @param dataList List of bytes to send * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts [default = 0] - */ + */ function send(dataList: number[], length?: number): void; /** * Sends a MIDI system-exclusive message of arbitrary number of bytes + * * @param dataList List of bytes to send * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts [default = 0] */ From 8e9bb3b2e1797a28e7e57595d51d8c21bbf45cbc Mon Sep 17 00:00:00 2001 From: Joerg Date: Fri, 7 Apr 2023 22:37:11 +0200 Subject: [PATCH 22/34] Added type for timerId --- res/controllers/engine-api.d.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index 26d0eaa3245..604171dfe75 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -151,6 +151,8 @@ declare namespace engine { /** @deprecated Use {@link console.log} instead */ function log(message: string): void; + type TimerID = number; + /** * Starts a timer that will call the specified script function * @@ -164,14 +166,14 @@ declare namespace engine { * @returns timerId which is needed to stop a timer. * In case of an error, 0 is returned. */ - function beginTimer(interval: number, scriptCode: ()=>any, oneShot?: boolean): number; + function beginTimer(interval: number, scriptCode: () => any, oneShot?: boolean): TimerID; /** * Stops the specified timer * * @param timerId ID of the timer */ - function stopTimer(timerId: number): void; + function stopTimer(timerId: TimerID): void; /** * Jogwheel function to be called when scratching starts (usually when the wheel is touched) From 95f06c90f08d43c6a02fc20cdb5342c203f635d7 Mon Sep 17 00:00:00 2001 From: Joerg Date: Fri, 7 Apr 2023 22:51:13 +0200 Subject: [PATCH 23/34] Fixed codespell setup --- .pre-commit-config.yaml | 2 +- res/controllers/console-api.d.ts | 2 +- res/controllers/engine-api.d.ts | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ab1964d6fc6..379e51c2fed 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -62,7 +62,7 @@ repos: --ignore-regex, "\\W(?:m_p*(?=[A-Z])|m_(?=\\w)|pp*(?=[A-Z])|k(?=[A-Z])|s_(?=\\w))", ] - exclude: ^(packaging/wix/LICENSE.rtf|src/dialog/dlgabout\.cpp|.*\.(?:pot?|(?!d.ts)|ts|wxl|svg))$ + exclude: ^(packaging/wix/LICENSE.rtf|src/dialog/dlgabout\.cpp|.*\.(?:pot?|(!d.)ts|wxl|svg))$ - repo: https://github.com/pre-commit/mirrors-eslint rev: v8.25.0 hooks: diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index bd175693061..8d736909118 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -12,7 +12,7 @@ declare namespace console { * Prints debugging information to the console, when * QT_LOGGING_RULES="js.debug=true;" or * Mixxx is started with --controller-debug - * This fuction is identical to console.debug + * This function is identical to console.debug * * @param data Message to print * - Either a list of objects whose string representations get concatenated into the message string diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index 604171dfe75..b22bb1213f9 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -106,7 +106,7 @@ declare namespace engine { * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" - * @param callback JS function, which will be called everytime, the value of the connected control changes. + * @param callback JS function, which will be called every time, the value of the connected control changes. * @returns Returns script connection object on success, otherwise 'undefined'' */ function makeConnection(group: string, name: string, callback: CoCallback): ScriptConnection |undefined; @@ -119,7 +119,7 @@ declare namespace engine { * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "VuMeter" - * @param callback JS function, which will be called everytime, the value of the connected control changes. + * @param callback JS function, which will be called every time, the value of the connected control changes. * @returns Returns script connection object on success, otherwise 'undefined'' */ function makeUnbufferedConnection(group: string, name: string, callback: CoCallback): ScriptConnection | undefined; @@ -131,7 +131,7 @@ declare namespace engine { * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "VuMeter" - * @param callback JS function, which will be called everytime, the value of the connected control changes. + * @param callback JS function, which will be called every time, the value of the connected control changes. * @param disconnect If "true", all connections to the ControlObject are removed. [default = false] * @returns Returns script connection object on success, otherwise 'undefined' or 'false' depending on the error cause. * @deprecated Use {@link makeConnection} instead @@ -244,7 +244,7 @@ declare namespace engine { * @param factor Defines how quickly the deck should come to a stop. * Start with a value of 1 and increase to increase the acceleration. * Be aware that brake called with low factors (about 0.5 and lower), - * would keep the deck running altough the resulting very low sounds are not audible anymore. [default = 1.0] + * would keep the deck running although the resulting very low sounds are not audible anymore. [default = 1.0] * @param rate The initial speed of the deck when enabled. "1" (default) means 10x speed in forward. * Negative values like "-1" also work, though then it's spinning reverse obviously. [default = 1.0] */ @@ -259,7 +259,7 @@ declare namespace engine { * @param factor Defines how quickly the deck should come to normal playback rate. * Start with a value of 1 and increase to increase the acceleration. * Be aware that spinback called with low factors (about 0.5 and lower), - * would keep the deck running altough the resulting very low sounds are not audible anymore. [default = 1.8] + * would keep the deck running although the resulting very low sounds are not audible anymore. [default = 1.8] * @param rate The initial speed of the deck when enabled. "-10" (default) means 10x speed in reverse. * Positive values like "10" also work, though then it's spinning forward obviously. [default = -10.0] */ From 5f937fa9bc8cb4d26c144f1b61db6ede7f336f65 Mon Sep 17 00:00:00 2001 From: Joerg Date: Mon, 1 May 2023 23:36:34 +0200 Subject: [PATCH 24/34] Corrected return type of getInputReport and getFeatureReport --- res/controllers/hid-controller-api.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index f90fa654e7b..c4956402e24 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -40,7 +40,7 @@ declare namespace controller { * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @returns Returns report data with ReportID byte as prefix */ - function getInputReport(reportID: number): Uint8Array; + function getInputReport(reportID: number): ArrayBuffer; /** * Sends a FeatureReport to HID device @@ -57,5 +57,5 @@ declare namespace controller { * @returns The returned array matches the input format of sendFeatureReport, * allowing it to be read, modified and sent it back to the controller. */ - function getFeatureReport(reportID: number): Uint8Array; + function getFeatureReport(reportID: number): ArrayBuffer; } From 7ae4f68a8d6f20ecaa153290fbe8595b8ba921a4 Mon Sep 17 00:00:00 2001 From: Joerg Date: Tue, 2 May 2023 21:20:47 +0200 Subject: [PATCH 25/34] Fixed typos an other textual review suggestions --- res/controllers/console-api.d.ts | 2 +- res/controllers/engine-api.d.ts | 8 ++++---- res/controllers/hid-controller-api.d.ts | 6 +++--- res/controllers/midi-controller-api.d.ts | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/res/controllers/console-api.d.ts b/res/controllers/console-api.d.ts index 8d736909118..fe221958d7a 100644 --- a/res/controllers/console-api.d.ts +++ b/res/controllers/console-api.d.ts @@ -135,4 +135,4 @@ declare namespace console { */ function exception(...data: any[]): void; - } +} diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index b22bb1213f9..d935325511b 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -6,7 +6,7 @@ declare class ScriptConnection { * Disconnect the script connection, * established by {@link engine.makeConnection} or {@link engine.makeUnbufferedConnection} * - * @returns Returns true if the connection is successful disconnected + * @returns Returns true if the connection has been disconnected successfully */ disconnect(): boolean; @@ -141,7 +141,7 @@ declare namespace engine { /** * Triggers the execution of all connected callback functions, with the actual value of a control. - * Note: To trigger a single connection, us {@link ScriptConnection.trigger} instead + * Note: To trigger a single connection, use {@link ScriptConnection.trigger} instead * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" @@ -181,7 +181,7 @@ declare namespace engine { * responsiveness and looseness of the imaginary slip mat * * @param deck The deck number to use, e.g: 1 - * @param intervalsPerRev The resolution of the MIDI control (in intervals per revolution, typically 128.) + * @param intervalsPerRev The resolution of the MIDI control (in intervals per revolution) * @param rpm The speed of the imaginary record at 0% pitch (in revolutions per minute (RPM) typically 33+1/3, adjust for comfort) * @param alpha The alpha coefficient of the filter (start with 1/8 (0.125) and tune from there) * @param beta The beta coefficient of the filter (start with alpha/32 and tune from there) @@ -226,7 +226,7 @@ declare namespace engine { function softTakeover(group: string, name: string, enable: boolean): void; /** - * Inhibits a suden value change from the hardware control. + * Inhibits a sudden value change from the hardware control. * Should be called when receiving input for the knob/fader, * that switches its behavior (e.g. Shift-Button pressed) * diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index c4956402e24..358a23be4a8 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -7,7 +7,7 @@ declare namespace controller { * This function only works with HID devices, which don't use ReportIDs * * @param dataList Data to send as list of bytes - * @param length This optional argument is no longer evaluated, and only here for backwards compatibility [default = 0] + * @param length Unused but mandatory argument for backwards compatibility */ function send(dataList: number[], length?: number): void; @@ -15,7 +15,7 @@ declare namespace controller { * Sends HID OutputReport to HID device * * @param dataList Data to send as list of bytes - * @param length Unused but mandatory argument + * @param length Unused but mandatory argument for backwards compatibility * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use ReportIDs * @param resendUnchangedReport If set, the report will also be send, if the data are unchanged since last sending [default = false] */ @@ -58,4 +58,4 @@ declare namespace controller { * allowing it to be read, modified and sent it back to the controller. */ function getFeatureReport(reportID: number): ArrayBuffer; - } +} diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts index edf1c2e45f8..41ed608aa46 100644 --- a/res/controllers/midi-controller-api.d.ts +++ b/res/controllers/midi-controller-api.d.ts @@ -29,4 +29,4 @@ declare namespace controller { */ function sendSysexMsg(dataList: number[], length?: number): void; - } +} From f16c96461ef401ac00c0e74d0bf8ff7594d4bdc9 Mon Sep 17 00:00:00 2001 From: Joerg Date: Sat, 13 May 2023 12:47:58 +0200 Subject: [PATCH 26/34] Fixed regexp to distinguish translation files from TypeScript files --- .pre-commit-config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 379e51c2fed..b6a4a781384 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -62,7 +62,7 @@ repos: --ignore-regex, "\\W(?:m_p*(?=[A-Z])|m_(?=\\w)|pp*(?=[A-Z])|k(?=[A-Z])|s_(?=\\w))", ] - exclude: ^(packaging/wix/LICENSE.rtf|src/dialog/dlgabout\.cpp|.*\.(?:pot?|(!d.)ts|wxl|svg))$ + exclude: ^(packaging/wix/LICENSE.rtf|src/dialog/dlgabout\.cpp|.*\.(?:pot?|(? Date: Sat, 13 May 2023 13:13:35 +0200 Subject: [PATCH 27/34] Declare ScriptConnection as interface, instead as class, which prevents creating new ScriptConnection objects from JavaScript --- res/controllers/engine-api.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index d935325511b..1b7f6f0b787 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -1,7 +1,7 @@ /** ScriptConnectionJSProxy */ -declare class ScriptConnection { +declare interface ScriptConnection { /** * Disconnect the script connection, * established by {@link engine.makeConnection} or {@link engine.makeUnbufferedConnection} From 3b6b5b250bcc069daa094f1679f3b656a1e7c978 Mon Sep 17 00:00:00 2001 From: Joerg Date: Sat, 13 May 2023 13:21:27 +0200 Subject: [PATCH 28/34] Fixed wrong namespace from controller to midi --- res/controllers/midi-controller-api.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts index 41ed608aa46..bb455714b2b 100644 --- a/res/controllers/midi-controller-api.d.ts +++ b/res/controllers/midi-controller-api.d.ts @@ -1,7 +1,7 @@ /** MidiControllerJSProxy */ -declare namespace controller { +declare namespace midi { /** * Sends a 3 byte MIDI short message From 29305e9d62fa1f341654d0b95dbb10be0ab664f2 Mon Sep 17 00:00:00 2001 From: Joerg Date: Sat, 13 May 2023 13:37:04 +0200 Subject: [PATCH 29/34] Added hyperlinks to Mixxx Controls manual page --- res/controllers/engine-api.d.ts | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index 1b7f6f0b787..2c020f2961a 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -29,7 +29,8 @@ declare namespace engine { * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" - * @returns Value of the control (within it's range according Mixxx Controls manual page) + * @returns Value of the control (within it's range according Mixxx Controls manual page: + * https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html) */ function getValue(group: string, name: string): number; @@ -38,7 +39,8 @@ declare namespace engine { * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" - * @param newValue Value to be set (within it's range according Mixxx Controls manual page) + * @param newValue Value to be set (within it's range according Mixxx Controls manual page: + * https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html) */ function setValue(group: string, name: string, newValue: number): void; @@ -66,7 +68,8 @@ declare namespace engine { * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" - * @param value Value with the controls range according Mixxx Controls manual page + * @param value Value with the controls range according Mixxx Controls manual page: + * https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html * @returns Value normalized to range of 0..1 */ function getParameterForValue(group: string, name: string, value: number): number; @@ -84,7 +87,8 @@ declare namespace engine { * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" - * @returns Default value with the controls range according Mixxx Controls manual page + * @returns Default value with the controls range according Mixxx Controls manual page: + * https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html */ function getDefaultValue(group: string, name: string): number; From 992a7f9e8758b702898c433787c6680c7dda342f Mon Sep 17 00:00:00 2001 From: Joerg Date: Sat, 13 May 2023 13:57:35 +0200 Subject: [PATCH 30/34] Rewrote documentation for ColorMapper class --- res/controllers/color-mapper-api.d.ts | 35 +++++++++++++++++---------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/res/controllers/color-mapper-api.d.ts b/res/controllers/color-mapper-api.d.ts index 03ea7b124c4..6188d9c4772 100644 --- a/res/controllers/color-mapper-api.d.ts +++ b/res/controllers/color-mapper-api.d.ts @@ -2,19 +2,28 @@ /** ColorMapperJSProxy */ declare class ColorMapper { -// Passing a QMap argument to the constructor as needed by - // the ColorMapper constructor segfaults. QJSEngine converts a JS object to - // a QVariantMap, so this constructor converts the QVariantMap to a - // QMap. - constructor (availableColors: { [rgb: number]: number }); + /** + * Constructs a ColorMapper object which maps RGB colors to device specific color codes + * + * @param availableColors List of number pairs (e.g. {0xFF0000: 1, 0x00FF00: 2} ) + */ + constructor (availableColors: { [rgbColor: number]: number }); - /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest - /// available color and returns a JS object with properties "red", "green", - /// "blue" (each with value range 0-255). - getNearestColor(ColorCode: number): {[rgb: number]: number}; + /** + * For a given RGB color code (e.g. 0xFF0000), this finds the nearest + * available color and returns a JS object with properties "red", "green", + * "blue" (each with value range 0-255). + * + * @param colorCode Device specific color code + */ + getNearestColor(colorCode: number): {[rgb: number]: number}; - /// For a given RGB color code (e.g. 0xFF0000), this finds the nearest - /// available color, then returns the value associated with that color - /// (which could be a MIDI byte value for example). - getValueForNearestColor(ColorCode: number): number; + /** + * For a given RGB color code (e.g. 0xFF0000), this finds the nearest + * available color, then returns the value associated with that color + * (which could be a MIDI byte value for example). + * + * @param rgbColor RGB color (e.g. 0xFF00CC) + */ + getValueForNearestColor(rgbColor: number): number; } From 7c5130fe39bad894400ce9ebca459882c2814654 Mon Sep 17 00:00:00 2001 From: Joerg Date: Sat, 13 May 2023 17:07:12 +0200 Subject: [PATCH 31/34] Adjusted indentation --- res/controllers/engine-api.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index 2c020f2961a..ab9d8cd9aae 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -30,7 +30,7 @@ declare namespace engine { * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @returns Value of the control (within it's range according Mixxx Controls manual page: - * https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html) + * https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html) */ function getValue(group: string, name: string): number; @@ -40,7 +40,7 @@ declare namespace engine { * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" * @param newValue Value to be set (within it's range according Mixxx Controls manual page: - * https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html) + * https://manual.mixxx.org/latest/chapters/appendix/mixxx_controls.html) */ function setValue(group: string, name: string, newValue: number): void; From 3e28b7581c577bec19f19ceddf904149f069ffc9 Mon Sep 17 00:00:00 2001 From: Joerg Date: Sat, 13 May 2023 17:09:11 +0200 Subject: [PATCH 32/34] Corrected English --- res/controllers/midi-controller-api.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/res/controllers/midi-controller-api.d.ts b/res/controllers/midi-controller-api.d.ts index bb455714b2b..fece7e7bcea 100644 --- a/res/controllers/midi-controller-api.d.ts +++ b/res/controllers/midi-controller-api.d.ts @@ -17,7 +17,7 @@ declare namespace midi { * Sends a MIDI system-exclusive message of arbitrary number of bytes * * @param dataList List of bytes to send - * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts [default = 0] + * @param length This is no longer evaluated, and only here for backwards compatibility with old scripts [default = 0] */ function send(dataList: number[], length?: number): void; @@ -25,7 +25,7 @@ declare namespace midi { * Sends a MIDI system-exclusive message of arbitrary number of bytes * * @param dataList List of bytes to send - * @param length This is no longer evaluated, and only here for backwards compatibility to old scripts [default = 0] + * @param length This is no longer evaluated, and only here for backwards compatibility with old scripts [default = 0] */ function sendSysexMsg(dataList: number[], length?: number): void; From e18c99257b1da4771c193013946240cfcac9f8bc Mon Sep 17 00:00:00 2001 From: Joerg Date: Sat, 13 May 2023 17:23:03 +0200 Subject: [PATCH 33/34] Adjusted indentation for GetInputReport --- res/controllers/hid-controller-api.d.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index 358a23be4a8..a5f2ea3129e 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -33,9 +33,9 @@ declare namespace controller { /** * getInputReport receives an InputReport from the HID device on request. * - * This can be used on startup to initialize the knob positions in Mixxx - * to the physical position of the hardware knobs on the controller. - * This is an optional command in the HID standard - not all devices support it. + * This can be used on startup to initialize the knob positions in Mixxx + * to the physical position of the hardware knobs on the controller. + * This is an optional command in the HID standard - not all devices support it. * * @param reportID 1...255 for HID devices that uses ReportIDs - or 0 for devices, which don't use * @returns Returns report data with ReportID byte as prefix From bda69bc6e171539b72ddd6ced8b087eec8667d3c Mon Sep 17 00:00:00 2001 From: Joerg Date: Sat, 13 May 2023 18:45:52 +0200 Subject: [PATCH 34/34] Adjusted indentation --- res/controllers/engine-api.d.ts | 6 +++--- res/controllers/hid-controller-api.d.ts | 3 ++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/res/controllers/engine-api.d.ts b/res/controllers/engine-api.d.ts index ab9d8cd9aae..f74096e480a 100644 --- a/res/controllers/engine-api.d.ts +++ b/res/controllers/engine-api.d.ts @@ -106,7 +106,7 @@ declare namespace engine { /** * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * - * This connection has a FIFO buffer - all value change events are processed in serial order. + * This connection has a FIFO buffer - all value change events are processed in serial order. * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "play_indicator" @@ -118,8 +118,8 @@ declare namespace engine { /** * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes * - * This connection is unbuffered - when value change events occur faster, than the mapping can process them, - * only the last value set for the control is processed. + * This connection is unbuffered - when value change events occur faster, than the mapping can process them, + * only the last value set for the control is processed. * * @param group Group of the control e.g. "[Channel1]" * @param name Name of the control e.g. "VuMeter" diff --git a/res/controllers/hid-controller-api.d.ts b/res/controllers/hid-controller-api.d.ts index a5f2ea3129e..dbe4ca70d95 100644 --- a/res/controllers/hid-controller-api.d.ts +++ b/res/controllers/hid-controller-api.d.ts @@ -4,7 +4,8 @@ declare namespace controller { /** * Sends HID OutputReport with hard coded ReportID 0 to HID device - * This function only works with HID devices, which don't use ReportIDs + * + * This function only works with HID devices, which don't use ReportIDs * * @param dataList Data to send as list of bytes * @param length Unused but mandatory argument for backwards compatibility