History

console JSDoc

David Rowe committed 6 years ago

Commit 7d2e8181 parent 6312a7c1 file · +165 −0Browse files

Showing the changes to libraries/script-engine/src/ConsoleScriptingInterface.h (1 of 1 file). Show all

Unified · Split

libraries/script-engine/src/ConsoleScriptingInterface.h+165−0
@@ -26,25 +26,190 @@ · 25 unmodified lines
26#include <QtCore/QHash>26#include <QtCore/QHash>
27#include <QtScript/QScriptable>27#include <QtScript/QScriptable>
28 28
29/**jsdoc
30 * The <code>console</code> API provides program logging facilities.
31 *
32 * @namespace console
33 *
34 * @hifi-interface
35 * @hifi-client-entity
36 * @hifi-avatar
37 * @hifi-server-entity
38 * @hifi-assignment-client
39 */
29// Scriptable interface of "console" object. Used exclusively in the JavaScript API40// Scriptable interface of "console" object. Used exclusively in the JavaScript API
30class ConsoleScriptingInterface : public QObject, protected QScriptable {41class ConsoleScriptingInterface : public QObject, protected QScriptable {
31 Q_OBJECT42 Q_OBJECT
32public:43public:
44
45 /**jsdoc
46 * Logs an "INFO" message to the program log and triggers {@link Script.infoMessage}.
47 * The message logged is "INFO -" followed by the message values separated by spaces.
48 * @function console.info
49 * @param {...*} [message] - The message values to log.
50 */
33 static QScriptValue info(QScriptContext* context, QScriptEngine* engine);51 static QScriptValue info(QScriptContext* context, QScriptEngine* engine);
52
53 /**jsdoc
54 * Logs a message to the program log and triggers {@link Script.printedMessage}.
55 * The message logged is the message values separated by spaces.
56 * <p>If a {@link console.group} is in effect, the message is indented by an amount proportional to the group level.</p>
57 * @function console.log
58 * @param {...*} [message] - The message values to log.
59 * @example <caption>Log some values.</caption>
60 * Script.printedMessage.connect(function (message, scriptName) {
61 * console.info("Console.log message:", "\"" + message + "\"", "in", "[" + scriptName + "]");
62 * });
63 *
64 * console.log("string", 7, true);
65 *
66 * // string 7 true
67 * // INFO - Console.log message: "string 7 true" in [console.js]
68 */
34 static QScriptValue log(QScriptContext* context, QScriptEngine* engine);69 static QScriptValue log(QScriptContext* context, QScriptEngine* engine);
70
71 /**jsdoc
72 * Logs a message to the program log and triggers {@link Script.printedMessage}.
73 * The message logged is the message values separated by spaces.
74 * @function console.debug
75 * @param {...*} [message] - The message values to log.
76 */
35 static QScriptValue debug(QScriptContext* context, QScriptEngine* engine);77 static QScriptValue debug(QScriptContext* context, QScriptEngine* engine);
78
79 /**jsdoc
80 * Logs a "WARNING" message to the program log and triggers {@link Script.warningMessage}.
81 * The message logged is "WARNING - " followed by the message values separated by spaces.
82 * @function console.warn
83 * @param {...*} [message] - The message values to log.
84 */
36 static QScriptValue warn(QScriptContext* context, QScriptEngine* engine);85 static QScriptValue warn(QScriptContext* context, QScriptEngine* engine);
86
87 /**jsdoc
88 * Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}.
89 * The message logged is "ERROR - " followed by the message values separated by spaces.
90 * @function console.error
91 * @param {...*} [message] - The message values to log.
92 */
37 static QScriptValue error(QScriptContext* context, QScriptEngine* engine);93 static QScriptValue error(QScriptContext* context, QScriptEngine* engine);
94
95 /**jsdoc
96 * A synonym of {@link console.error}.
97 * Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}.
98 * The message logged is "ERROR - " followed by the message values separated by spaces.
99 * @function console.exception
100 * @param {...*} [message] - The message values to log.
101 */
38 static QScriptValue exception(QScriptContext* context, QScriptEngine* engine);102 static QScriptValue exception(QScriptContext* context, QScriptEngine* engine);
103
104 /**jsdoc
105 * Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}, if a test condition fails.
106 * The message logged is "ERROR - Assertion failed : " followed by the message values separated by spaces.
107 * <p>Note: Script execution continues whether or not the test condition fails.</p>
108 * @function console.assert
109 * @param {boolean} assertion - The test condition value.
110 * @param {...*} [message] - The message values to log if the assertion evaluates to <code>false</code>.
111 * @example <caption>Demonstrate assertion behavior.</caption>
112 * Script.errorMessage.connect(function (message, scriptName) {
113 * console.info("Error message logged:", "\"" + message + "\"", "in", "[" + scriptName + "]");
114 * });
115 *
116 * console.assert(5 === 5, "5 equals 5.", "This assertion will succeed."); // No log output.
117 * console.assert(5 > 6, "5 is not greater than 6.", "This assertion will fail."); // Log output is generated.
118 * console.info("Script continues running.");
119 *
120 * // ERROR - Assertion failed : 5 is not greater than 6. This assertion will fail.
121 * // INFO - Error message logged: "Assertion failed : 5 is not greater than 6. This assertion will fail." in [console.js]
122 * // INFO - Script continues running.
123 */
124 // Note: Is registered in the script engine as "assert"
39 static QScriptValue assertion(QScriptContext* context, QScriptEngine* engine);125 static QScriptValue assertion(QScriptContext* context, QScriptEngine* engine);
126
127 /**jsdoc
128 * Logs a message to the program log and triggers {@link Script.printedMessage}, then starts indenting subsequent
129 * {@link console.log} messages until a {@link console.groupEnd}. Groups may be nested.
130 * @function console.group
131 * @param {*} message - The message value to log.
132 * @example <caption>Nested groups.</caption>
133 * console.group("Group 1");
134 * console.log("Sentence 1");
135 * console.log("Sentence 2");
136 * console.group("Group 2");
137 * console.log("Sentence 3");
138 * console.log("Sentence 4");
139 * console.groupEnd();
140 * console.log("Sentence 5");
141 * console.groupEnd();
142 * console.log("Sentence 6");
143 *
144 * //Group 1
145 * // Sentence 1
146 * // Sentence 2
147 * // Group 2
148 * // Sentence 3
149 * // Sentence 4
150 * // Sentence 5
151 * //Sentence 6
152 */
40 static QScriptValue group(QScriptContext* context, QScriptEngine* engine);153 static QScriptValue group(QScriptContext* context, QScriptEngine* engine);
154
155 /**jsdoc
156 * Has the same behavior as {@link console.group}.
157 * Logs a message to the program log and triggers {@link Script.printedMessage}, then starts indenting subsequent
158 * {@link console.log} messages until a {@link console.groupEnd}. Groups may be nested.
159 * @function console.groupCollapsed
160 * @param {*} message - The message value to log.
161 */
41 static QScriptValue groupCollapsed(QScriptContext* context, QScriptEngine* engine);162 static QScriptValue groupCollapsed(QScriptContext* context, QScriptEngine* engine);
163
164 /**jsdoc
165 * Finishes a group of indented {@link console.log} messages.
166 * @function console.groupEnd
167 */
42 static QScriptValue groupEnd(QScriptContext* context, QScriptEngine* engine);168 static QScriptValue groupEnd(QScriptContext* context, QScriptEngine* engine);
43 169
44public slots:170public slots:
171
172 /**jsdoc
173 * Starts a timer, logs a message to the program log, and triggers {@link Script.printedMessage}. The message logged has
174 * the timer name and "Timer started".
175 * @function console.time
176 * @param {string} name - The name of the timer.
177 * @example <caption>Time some processing.</caption>
178 * function sleep(milliseconds) {
179 * var start = new Date().getTime();
180 * for (var i = 0; i < 1e7; i++) {
181 * if ((new Date().getTime() - start) > milliseconds) {
182 * break;
183 * }
184 * }
185 * }
186 *
187 * console.time("MyTimer");
188 * sleep(1000); // Do some processing.
189 * console.timeEnd("MyTimer");
190 *
191 * // MyTimer: Timer started
192 * // MyTimer: 1001ms */
45 void time(QString labelName);193 void time(QString labelName);
194
195 /**jsdoc
196 * Finishes a timer, logs a message to the program log, and triggers {@link Script.printedMessage}. The message logged has
197 * the timer name and the number of milliseconds since the timer was started.
198 * @function console.timeEnd
199 * @param {string} name - The name of the timer.
200 */
46 void timeEnd(QString labelName);201 void timeEnd(QString labelName);
202
203 /**jsdoc
204 * Logs the JavaScript call stack at the point of call to the program log.
205 * @function console.trace
206 */
47 void trace();207 void trace();
208
209 /**jsdoc
210 * Clears the Developer &gt; Scripting &gt; Script Log debug window.
211 * @function console.clear
212 */
48 void clear();213 void clear();
49 214
50private: 215private: