From 369970f1204aa45113599e5f276eff4525b452da Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 15 Mar 2018 15:23:02 +1300 Subject: [PATCH 1/3] Messages API JSDoc --- libraries/networking/src/MessagesClient.h | 147 ++++++++++++++++++++++ 1 file changed, 147 insertions(+) diff --git a/libraries/networking/src/MessagesClient.h b/libraries/networking/src/MessagesClient.h index 6d0483fe9d..6ef3777d8c 100644 --- a/libraries/networking/src/MessagesClient.h +++ b/libraries/networking/src/MessagesClient.h @@ -23,6 +23,21 @@ #include "Node.h" #include "ReceivedMessage.h" +/**jsdoc + *

The Messages API enables text and data to be sent between scripts over named "channels". A channel can have an arbitrary + * name to help separate messaging between different sets of scripts.

+ * + *

Note: If you want to call a function in another script, you should use one of the following rather than + * sending a message:

+ * + * + * @namespace Messages + */ class MessagesClient : public QObject, public Dependency { Q_OBJECT public: @@ -30,10 +45,115 @@ public: void startThread(); + /**jsdoc + * Send a text message on a channel. + * @function Messages.sendMessage + * @param {string} channel - The channel to send the message on. + * @param {string} message - The message to send. + * @param {boolean} [localOnly=false] - If false then the message is sent to all Interface, client entity, + * server entity, and assignment client scripts in the domain.
+ * If true then: if sent from an Interface or client entity script it is received by all Interface and + * client entity scripts; if sent from a server entity script it is received by all entity server scripts; and if sent + * from an assignment client script it is received only by that same assignment client script. + * @example Send and receive a message. + * // Receiving script. + * var channelName = "com.highfidelity.example.messages-example"; + * + * function onMessageReceived(channel, message, sender, localOnly) { + * print("Message received:"); + * print("- channel: " + channel); + * print("- message: " + message); + * print("- sender: " + sender); + * print("- localOnly: " + localOnly); + * } + * + * Messages.subscribe(channelName); + * Messages.messageReceived.connect(onMessageReceived); + * + * Script.scriptEnding.connect(function () { + * Messages.messageReceived.disconnect(onMessageReceived); + * Messages.unsubscribe(channelName); + * }); + * + * + * // Sending script. + * var channelName = "com.highfidelity.example.messages-example"; + * var message = "Hello"; + * Messages.sendMessage(channelName, message); + */ Q_INVOKABLE void sendMessage(QString channel, QString message, bool localOnly = false); + + /**jsdoc + * Send a text message locally on a channel. + * This is the same as calling {@link Messages.sendMessage|sendMessage} with localOnly set to + * true. + * @function Messages.sendLocalMessage + * @param {string} channel - The channel to send the message on. + * @param {string} message - The message to send. + */ Q_INVOKABLE void sendLocalMessage(QString channel, QString message); + + /**jsdoc + * Send a data message on a channel. + * @function Messages.sendData + * @param {string} channel - The channel to send the data on. + * @param {object} data - The data to send. The data is handled as a byte stream, for example as may be provided via a + * JavaScript Int8Array object. + * @param {boolean} [localOnly=false] - If false then the message is sent to all Interface, client entity, + * server entity, and assignment client scripts in the domain.
+ * If true then: if sent from an Interface or client entity script it is received by all Interface and + * client entity scripts; if sent from a server entity script it is received by all entity server scripts; and if sent + * from an assignment client script it is received only by that same assignment client script. + * @example Send and receive data. + * // Receiving script. + * var channelName = "com.highfidelity.example.messages-example"; + * + * function onDataReceived(channel, data, sender, localOnly) { + * var int8data = new Int8Array(data); + * var dataAsString = ""; + * for (var i = 0; i < int8data.length; i++) { + * if (i > 0) { + * dataAsString += ", "; + * } + * dataAsString += int8data[i]; + * } + * print("Data received:"); + * print("- channel: " + channel); + * print("- data: " + dataAsString); + * print("- sender: " + sender); + * print("- localOnly: " + localOnly); + * } + * + * Messages.subscribe(channelName); + * Messages.dataReceived.connect(onDataReceived); + * + * Script.scriptEnding.connect(function () { + * Messages.dataReceived.disconnect(onDataReceived); + * Messages.unsubscribe(channelName); + * }); + * + * + * // Sending script. + * var channelName = "com.highfidelity.example.messages-example"; + * var int8data = new Int8Array([1, 1, 2, 3, 5, 8, 13]); + * Messages.sendData(channelName, int8data.buffer); + */ Q_INVOKABLE void sendData(QString channel, QByteArray data, bool localOnly = false); + + /**jsdoc + * Subscribe the scripting environment — Interface, the entity script server, or assignment client instance — + * to receive messages on a specific channel. Note that, for example, if there are two Interface scripts that subscribe to + * different channels, both scripts will receive messages on both channels. + * @function Messages.subscribe + * @param {string} channel - The channel to subscribe to. + */ Q_INVOKABLE void subscribe(QString channel); + + /**jsdoc + * Unsubscribe the scripting environment from receiving messages on a specific channel. + * @function Messages.unsubscribe + * @param {string} channel - The channel to unsubscribe from. + */ Q_INVOKABLE void unsubscribe(QString channel); static void decodeMessagesPacket(QSharedPointer receivedMessage, QString& channel, @@ -43,7 +163,34 @@ public: static std::unique_ptr encodeMessagesDataPacket(QString channel, QByteArray data, QUuid senderID); signals: + /**jsdoc + * Triggered when the a text message is received. + * @function Messages.messageReceived + * @param {string} channel - The channel that the message was sent on. You can use this to filter out messages not relevant + * to your script. + * @param {string} message - The message received. + * @param {Uuid} senderID - The UUID of the sender: the user's session UUID if sent by an Interface or client entity + * script, the UUID of the entity script server if sent by a server entity script, or the UUID of the assignment client + * instance if sent by an assignment client script. + * @param {boolean} localOnly - true if the message was sent with localOnly = true. + * @returns {Signal} + */ void messageReceived(QString channel, QString message, QUuid senderUUID, bool localOnly); + + /**jsdoc + * Triggered when a data message is received. + * @function Messages.dataReceived + * @param {string} channel - The channel that the message was sent on. You can use this to filter out messages not relevant + * to your script. + * @param {object} data - The data received. The data is handled as a byte stream, for example as may be used by a + * JavaScript Int8Array object. + * @param {Uuid} senderID - The UUID of the sender: the user's session UUID if sent by an Interface or client entity + * script, the UUID of the entity script server if sent by a server entity script, or the UUID of the assignment client + * script, the UUID of the entity script server if sent by a server entity script, or the UUID of the assignment client + * instance if sent by an assignment client script. + * @param {boolean} localOnly - true if the message was sent with localOnly = true. + * @returns {Signal} + */ void dataReceived(QString channel, QByteArray data, QUuid senderUUID, bool localOnly); private slots: From 63e07f1a7f25699813785a222a0713c12fce1142 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 15 Mar 2018 15:23:46 +1300 Subject: [PATCH 2/3] Fix typo in developer Messages test script --- scripts/developer/tests/messagesTests.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/developer/tests/messagesTests.js b/scripts/developer/tests/messagesTests.js index 18beafa4cc..094ad6f1c0 100644 --- a/scripts/developer/tests/messagesTests.js +++ b/scripts/developer/tests/messagesTests.js @@ -5,7 +5,7 @@ Messages.subscribe(channelName); //messageReceived(QString channel, QString message, QUuid senderUUID, bool localOnly); Messages.messageReceived.connect(function(channel, message, sender, local) { - print("message recieved on ", channel, " message:", message, " from:", sender, " local:", local); + print("message received on ", channel, " message:", message, " from:", sender, " local:", local); }); Messages.dataReceived.connect(function(channel, data, sender, local) { @@ -17,7 +17,7 @@ Messages.dataReceived.connect(function(channel, data, sender, local) { } dataAsString += int8data[i]; } - print("data recieved on ", channel, " from:", sender, " local:", local, "length of data:", int8data.length, " data:", dataAsString); + print("data received on ", channel, " from:", sender, " local:", local, "length of data:", int8data.length, " data:", dataAsString); }); var counter = 0; From a7cd5a240aa431a4e4c7bbe5fba171bb42de6e2e Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 15 Mar 2018 17:31:02 +1300 Subject: [PATCH 3/3] Fix "text" overlay not clipping to right and bottom margins --- interface/resources/qml/hifi/overlays/TextOverlay.qml | 1 + interface/src/ui/overlays/TextOverlay.cpp | 6 ++++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/interface/resources/qml/hifi/overlays/TextOverlay.qml b/interface/resources/qml/hifi/overlays/TextOverlay.qml index 301a2aa0bf..2fdc9c7cbb 100644 --- a/interface/resources/qml/hifi/overlays/TextOverlay.qml +++ b/interface/resources/qml/hifi/overlays/TextOverlay.qml @@ -20,6 +20,7 @@ Overlay { font.family: "Helvetica" font.pixelSize: 18 lineHeight: 18 + clip: true } } diff --git a/interface/src/ui/overlays/TextOverlay.cpp b/interface/src/ui/overlays/TextOverlay.cpp index fba36f0c77..e7641ab2c2 100644 --- a/interface/src/ui/overlays/TextOverlay.cpp +++ b/interface/src/ui/overlays/TextOverlay.cpp @@ -40,8 +40,10 @@ QUrl const TextOverlay::URL(QString("hifi/overlays/TextOverlay.qml")); * * @property {number} margin=0 - Sets the leftMargin and topMargin values, in pixels. * Write-only. - * @property {number} leftMargin=0 - The left margin's size, in pixels. Write-only. - * @property {number} topMargin=0 - The top margin's size, in pixels. Write-only. + * @property {number} leftMargin=0 - The left margin's size, in pixels. This value is also used for the right margin. + * Write-only. + * @property {number} topMargin=0 - The top margin's size, in pixels. This value is also used for the bottom margin. + * Write-only. * @property {string} text="" - The text to display. Text does not automatically wrap; use \n for a line break. Text * is clipped to the bounds. Write-only. * @property {number} font.size=18 - The size of the text, in pixels. Write-only.