Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[actions] Export CoreUtil actions #319

Merged
merged 1 commit into from
Jan 15, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -593,18 +593,28 @@ 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.

#### Audio Actions

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.
Expand Down
48 changes: 38 additions & 10 deletions actions.js
Original file line number Diff line number Diff line change
Expand Up @@ -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');
* <caption>Send a broadcast notification</caption>
* actions.NotificationAction.sendBroadcastNotification('Hello World!');
* <caption>Schedule a function for later execution/Create a timer (advanced)</caption>
* actions.ScriptExecution.createTimer('myTimer', time.toZDT().plusMinutes(10), () => { console.log('Hello timer!'); });
*
* @namespace actions
* @example <caption>Sends a broadcast notification</caption>
* const { actions } = require('openhab');
* actions.NotificationAction.sendBroadcastNotification("Hello World!")
*/
/**
* @typedef {import('@js-joda/core').ZonedDateTime} time.ZonedDateTime
Expand All @@ -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');

Expand Down Expand Up @@ -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
*
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -405,6 +432,7 @@ try {
module.exports = Object.assign(dynamicExports, {
Audio,
BusEvent,
CoreUtil,
Ephemeris,
Exec,
HTTP,
Expand All @@ -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()}.
Expand Down
25 changes: 22 additions & 3 deletions types/actions.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand Down Expand Up @@ -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`
Expand All @@ -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
Expand All @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion types/actions.d.ts.map

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading