diff --git a/README.md b/README.md index 342cf544a..33adc6a1d 100644 --- a/README.md +++ b/README.md @@ -593,7 +593,10 @@ thing.setEnabled(false); The actions namespace allows interactions with openHAB actions. The following are a list of standard actions. -Note that most of the actions currently do **not** provide type definitions and therefore auto-completion does not work. +**Warning:** Please be aware, that (unless not explicitly noted) there is **no** type conversion from Java to JavaScript types for the return values of actions. +Read the JavaDoc linked from the JSDoc to learn about the returned Java types. + +Please note that most of the actions currently do **not** provide type definitions and therefore auto-completion does not work. See [openhab-js : actions](https://openhab.github.io/openhab-js/actions.html) for full API documentation and additional actions. @@ -601,10 +604,17 @@ See [openhab-js : actions](https://openhab.github.io/openhab-js/actions.html) fo See [openhab-js : actions.Audio](https://openhab.github.io/openhab-js/actions.html#.Audio) for complete documentation. -#### BusEvent +#### BusEvent Actions See [openhab-js : actions.BusEvent](https://openhab.github.io/openhab-js/actions.html#.BusEvent) for complete documentation. +#### CoreUtil Actions + +See [openhab-js : actions.CoreUtil](https://openhab.github.io/openhab-js/actions.html#.CoreUtil) for complete documentation. + +The `CoreUtil` actions provide access to parts of the utilities included in openHAB core, see [org.openhab.core.util](https://www.openhab.org/javadoc/latest/org/openhab/core/util/package-summary). +These include several methods to convert between color types like HSB, RGB, sRGB, RGBW and XY. + #### Ephemeris Actions See [openhab-js : actions.Ephemeris](https://openhab.github.io/openhab-js/actions.html#.Ephemeris) for complete documentation. diff --git a/actions.js b/actions.js index bf3dde894..c70bcaed1 100644 --- a/actions.js +++ b/actions.js @@ -3,15 +3,22 @@ /** * Actions namespace. * - * This namespace provides access to openHAB actions. {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/package-summary.html All available actions} can be accessed as direct properties of this - * object (via their simple class name). + * This namespace provides access to openHAB actions. + * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/package-summary.html All available actions} can be accessed as direct properties of this object (via their simple class name). + * + * WARNING: Please be aware that there is, unless otherwise noted, NO type conversion from Java to JavaScript types for the return values of actions. + * Read the linked JavaDoc to learn about the returned Java types. * * Additional actions provided by user installed addons can be accessed using their common name on the actions name space if the addon exports them in a proper way. * + * @example + * const { actions, time } = require('openhab'); + * Send a broadcast notification + * actions.NotificationAction.sendBroadcastNotification('Hello World!'); + * Schedule a function for later execution/Create a timer (advanced) + * actions.ScriptExecution.createTimer('myTimer', time.toZDT().plusMinutes(10), () => { console.log('Hello timer!'); }); + * * @namespace actions - * @example Sends a broadcast notification - * const { actions } = require('openhab'); - * actions.NotificationAction.sendBroadcastNotification("Hello World!") */ /** * @typedef {import('@js-joda/core').ZonedDateTime} time.ZonedDateTime @@ -20,12 +27,12 @@ const osgi = require('./osgi'); // See https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/internal/defaultscope/ScriptThingActionsImpl.java -const { actions } = require('@runtime/Defaults'); const log = require('./log')('actions'); const Things = Java.type('org.openhab.core.model.script.actions.Things'); const actionServices = osgi.findServices('org.openhab.core.model.script.engine.action.ActionService', null) || []; +const JavaCoreUtil = Java.type('org.openhab.core.model.script.actions.CoreUtil'); const JavaScriptExecution = Java.type('org.openhab.core.model.script.actions.ScriptExecution'); const JavaTransformation = Java.type('org.openhab.core.transform.actions.Transformation'); @@ -86,6 +93,26 @@ const Audio = Java.type('org.openhab.core.model.script.actions.Audio'); */ const BusEvent = Java.type('org.openhab.core.model.script.actions.BusEvent'); +/** + * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/coreutil CoreUtil} Actions + * + * This class provides static methods mapping methods from package {@link https://www.openhab.org/javadoc/latest/org/openhab/core/util/package-summary org.openhab.core.util}. + * + * Its functionality includes: + * @example + * CoreUtil.hsbToRgb(HSBType hsb) -> int[] + * CoreUtil.hsbToRgbPercent(HSBType hsb) -> PercentType[] + * CoreUtil.hsbTosRGB(HSBType hsb) -> int + * CoreUtil.hsbToRgbw(HSBType hsb) -> int[] + * CoreUtil.hsbToRgbwPercent(HSBType hsb) -> PercentType[] + * CoreUtil.rgbToHsb(int[] rgb) -> HSBType + * CoreUtil.rgbToHsb(PercentType[] rgb) -> HSBType + * + * @name CoreUtil + * @memberof actions + */ +const CoreUtil = JavaCoreUtil; + /** * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/ephemeris Ephemeris} Actions * @@ -228,7 +255,7 @@ class ScriptExecution { * console.log(foo + bar); * }, 'Hello', 'openHAB'); * - * @param {string} identifier an optional identifier, e.g. user for logging + * @param {string} identifier an optional identifier, e.g. used for logging * @param {time.ZonedDateTime} zdt the point in time when the callback function should be executed * @param {function} functionRef callback function to execute when the timer expires * @param {...*} params additional arguments which are passed through to the function specified by `functionRef` @@ -259,7 +286,7 @@ class ScriptExecution { * Schedules a function (with argument) for later execution * * @deprecated - * @param {string} identifier an optional identifier + * @param {string} identifier an optional identifier, e.g. used for logging * @param {time.ZonedDateTime} instant the point in time when the code should be executed * @param {*} arg1 the argument to pass to the code block * @param {function} closure the code block to execute @@ -281,7 +308,7 @@ class ScriptExecution { * * The static methods of this class are made available as functions in the scripts. This allows a script to use Semantics features. * - * Instead of using the Semantics actions, it is recommended to use the the {@link items.ItemSemantics} available through the `semantics` property of an {@link items.Item}. + * Instead of using the Semantics actions, it is recommended to use the {@link items.ItemSemantics} available through the `semantics` property of an {@link items.Item}. * * @example * Semantics.getEquipment(Item item) @@ -405,6 +432,7 @@ try { module.exports = Object.assign(dynamicExports, { Audio, BusEvent, + CoreUtil, Ephemeris, Exec, HTTP, @@ -425,7 +453,7 @@ module.exports = Object.assign(dynamicExports, { * @param {string} thingUid Thing UID * @returns {*} Native Java {@link https://www.openhab.org/javadoc/latest/org/openhab/core/thing/binding/thingactions ThingActions} */ - get: (bindingId, thingUid) => actions.get(bindingId, thingUid), + get: (bindingId, thingUid) => Things.getActions(bindingId, thingUid), /** * Get the ThingActions of a given Thing. * Duplicate of {@link actions.get actions.get()} and {@link actions.Things actions.Things.getActions()}. diff --git a/types/actions.d.ts b/types/actions.d.ts index 1dac01d80..a216327bb 100644 --- a/types/actions.d.ts +++ b/types/actions.d.ts @@ -41,6 +41,25 @@ export const Audio: any; * @memberof actions */ export const BusEvent: any; +/** + * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/coreutil CoreUtil} Actions + * + * This class provides static methods mapping methods from package {@link https://www.openhab.org/javadoc/latest/org/openhab/core/util/package-summary org.openhab.core.util}. + * + * Its functionality includes: + * @example + * CoreUtil.hsbToRgb(HSBType hsb) -> int[] + * CoreUtil.hsbToRgbPercent(HSBType hsb) -> PercentType[] + * CoreUtil.hsbTosRGB(HSBType hsb) -> int + * CoreUtil.hsbToRgbw(HSBType hsb) -> int[] + * CoreUtil.hsbToRgbwPercent(HSBType hsb) -> PercentType[] + * CoreUtil.rgbToHsb(int[] rgb) -> HSBType + * CoreUtil.rgbToHsb(PercentType[] rgb) -> HSBType + * + * @name CoreUtil + * @memberof actions + */ +export const CoreUtil: any; /** * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/ephemeris Ephemeris} Actions * @@ -175,7 +194,7 @@ export class ScriptExecution { * console.log(foo + bar); * }, 'Hello', 'openHAB'); * - * @param {string} identifier an optional identifier, e.g. user for logging + * @param {string} identifier an optional identifier, e.g. used for logging * @param {time.ZonedDateTime} zdt the point in time when the callback function should be executed * @param {function} functionRef callback function to execute when the timer expires * @param {...*} params additional arguments which are passed through to the function specified by `functionRef` @@ -186,7 +205,7 @@ export class ScriptExecution { * Schedules a function (with argument) for later execution * * @deprecated - * @param {string} identifier an optional identifier + * @param {string} identifier an optional identifier, e.g. used for logging * @param {time.ZonedDateTime} instant the point in time when the code should be executed * @param {*} arg1 the argument to pass to the code block * @param {function} closure the code block to execute @@ -199,7 +218,7 @@ export class ScriptExecution { * * The static methods of this class are made available as functions in the scripts. This allows a script to use Semantics features. * - * Instead of using the Semantics actions, it is recommended to use the the {@link items.ItemSemantics} available through the `semantics` property of an {@link items.Item}. + * Instead of using the Semantics actions, it is recommended to use the {@link items.ItemSemantics} available through the `semantics` property of an {@link items.Item}. * * @example * Semantics.getEquipment(Item item) diff --git a/types/actions.d.ts.map b/types/actions.d.ts.map index 2e2652e43..2a409afb8 100644 --- a/types/actions.d.ts.map +++ b/types/actions.d.ts.map @@ -1 +1 @@ -{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../actions.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAuE;AAEvE;;;;;;;;;;;;;;;;;;GAkBG;AACH,2BAA6E;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,4BAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,uBAAqE;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uBAAqE;AAErE;;;;;;;;;;;;;GAaG;AACH,6BAAyE;AAEzE;;;;;;;;;;GAUG;AACH,uBAAqE;AAErE;;;;;;;;;;;;GAYG;AACH;IACE;;;;OAIG;IACH,8BAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;;OAaG;IACH,+BANW,MAAM,OACN,KAAK,aAAa,gDAwB5B;IAED;;;;;;;;;OASG;IACH,2CANW,MAAM,WACN,KAAK,aAAa,qCAa5B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4BAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,gCAA+E;AAE/E;;;;;;;;;;;GAWG;AACH;IACE;;;;;;;OAOG;IACH,uBALW,MAAM,MACN,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,0BANW,MAAM,MACN,MAAM,SACN,MAAM,GACJ,MAAM,CAUlB;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAuE;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,mCAAuB;;yBA7XV,OAAO,eAAe,EAAE,aAAa;;AA2Z3C,sEAAyD;AAUhD,+EAA+D"} \ No newline at end of file +{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../actions.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAuE;AAEvE;;;;;;;;;;;;;;;;;;GAkBG;AACH,2BAA6E;AAE7E;;;;;;;;;;;;;;;;;GAiBG;AACH,2BAA8B;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,4BAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,uBAAqE;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uBAAqE;AAErE;;;;;;;;;;;;;GAaG;AACH,6BAAyE;AAEzE;;;;;;;;;;GAUG;AACH,uBAAqE;AAErE;;;;;;;;;;;;GAYG;AACH;IACE;;;;OAIG;IACH,8BAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;;OAaG;IACH,+BANW,MAAM,OACN,KAAK,aAAa,gDAwB5B;IAED;;;;;;;;;OASG;IACH,2CANW,MAAM,WACN,KAAK,aAAa,qCAa5B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4BAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,gCAA+E;AAE/E;;;;;;;;;;;GAWG;AACH;IACE;;;;;;;OAOG;IACH,uBALW,MAAM,MACN,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,0BANW,MAAM,MACN,MAAM,SACN,MAAM,GACJ,MAAM,CAUlB;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAuE;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,mCAAuB;;yBAjZV,OAAO,eAAe,EAAE,aAAa;;AAgb3C,sEAA+D;AAUtD,+EAA+D"} \ No newline at end of file