Merge pull request #12961 from eska014/platform-doc

Facilitate documenting platform-exclusive classes

12 files changed, 211 insertions, 35 deletions

diff --git a/SConstruct b/SConstruct
index 10982211ac..c3ecdafd45 100644
--- a/SConstruct
+++ b/SConstruct
@@ -22,6 +22,7 @@ platform_flags = {}  # flags for each platform
 active_platforms = []
 active_platform_ids = []
 platform_exporters = []
+platform_apis = []
 global_defaults = []
 
 for x in glob.glob("platform/*"):
@@ -34,6 +35,8 @@ for x in glob.glob("platform/*"):
 
     if (os.path.exists(x + "/export/export.cpp")):
         platform_exporters.append(x[9:])
+    if (os.path.exists(x + "/api/api.cpp")):
+        platform_apis.append(x[9:])
     if (os.path.exists(x + "/globals/global_defaults.cpp")):
         global_defaults.append(x[9:])
     if (detect.is_active()):
@@ -215,6 +218,7 @@ env_base.Append(CPPPATH=['#core', '#core/math', '#editor', '#drivers', '#'])
 
 # configure ENV for platform
 env_base.platform_exporters = platform_exporters
+env_base.platform_apis = platform_apis
 
 """
 sys.path.append("./platform/"+env_base["platform"])
@@ -438,6 +442,7 @@ if selected_platform in platform_list:
     SConscript("editor/SCsub")
     SConscript("drivers/SCsub")
 
+    SConscript("platform/SCsub")
     SConscript("modules/SCsub")
     SConscript("main/SCsub")
 
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
index 31a0d3ccef..d9bdf0e3cf 100644
--- a/doc/classes/@GlobalScope.xml
+++ b/doc/classes/@GlobalScope.xml
@@ -44,6 +44,8 @@
 		<member name="JSON" type="JSON" setter="" getter="">
 			[JSON] singleton
 		</member>
+		<member name="JavaScript" type="JavaScript" setter="" getter="">
+		</member>
 		<member name="Marshalls" type="Reference" setter="" getter="">
 			[Marshalls] singleton
 		</member>
diff --git a/doc/classes/JavaScript.xml b/doc/classes/JavaScript.xml
new file mode 100644
index 0000000000..9dd386f08e
--- /dev/null
+++ b/doc/classes/JavaScript.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="JavaScript" inherits="Object" category="Core" version="3.0-alpha">
+	<brief_description>
+		Singleton that connects the engine with the browser's JavaScript context in HTML5 export.
+	</brief_description>
+	<description>
+		The JavaScript singleton is implemented only in HTML5 export. It's used to access the browser's JavaScript context. This allows interaction with embedding pages or calling third-party JavaScript APIs.
+	</description>
+	<tutorials>
+		http://docs.godotengine.org/en/stable/learning/workflow/export/exporting_for_web.html#calling-javascript-from-script
+	</tutorials>
+	<demos>
+	</demos>
+	<methods>
+		<method name="eval">
+			<return type="Variant">
+			</return>
+			<argument index="0" name="code" type="String">
+			</argument>
+			<argument index="1" name="use_global_execution_context" type="bool" default="false">
+			</argument>
+			<description>
+				Execute the string [code]code[/code] as JavaScript code within the browser window. This is a call to the actual global JavaScript function [code]eval()[/code].
+				If [code]use_global_execution_context[/code] is [code]true[/code], the code will be evaluated in the global execution context. Otherwise, it is evaluated in the execution context of a function within the engine's runtime environment.
+			</description>
+		</method>
+	</methods>
+	<constants>
+	</constants>
+</class>
diff --git a/main/main.cpp b/main/main.cpp
index 3a87742528..023520017b 100644
--- a/main/main.cpp
+++ b/main/main.cpp
@@ -35,6 +35,7 @@
 #include "message_queue.h"
 #include "modules/register_module_types.h"
 #include "os/os.h"
+#include "platform/register_platform_apis.h"
 #include "project_settings.h"
 #include "scene/register_scene_types.h"
 #include "script_debugger_local.h"
@@ -1108,6 +1109,7 @@ Error Main::setup2(Thread::ID p_main_tid_override) {
 
 	MAIN_PRINT("Main: Load Modules, Physics, Drivers, Scripts");
 
+	register_platform_apis();
 	register_module_types();
 
 	initialize_physics();
@@ -1826,6 +1828,7 @@ void Main::cleanup() {
 
 	unregister_driver_types();
 	unregister_module_types();
+	unregister_platform_apis();
 	unregister_scene_types();
 	unregister_server_types();
 
diff --git a/platform/SCsub b/platform/SCsub
new file mode 100644
index 0000000000..4ef23ab053
--- /dev/null
+++ b/platform/SCsub
@@ -0,0 +1,30 @@
+#!/usr/bin/env python
+
+from compat import open_utf8
+
+Import('env')
+platform_sources = []
+
+# Register platform-exclusive APIs
+reg_apis_inc = '#include "register_platform_apis.h"\n'
+reg_apis = 'void register_platform_apis() {\n'
+unreg_apis = 'void unregister_platform_apis() {\n'
+for platform in env.platform_apis:
+    platform_dir = env.Dir(platform)
+    platform_sources.append(platform_dir.File('api/api.cpp'))
+    reg_apis += '\tregister_' + platform + '_api();\n'
+    unreg_apis += '\tunregister_' + platform + '_api();\n'
+    reg_apis_inc += '#include "' + platform + '/api/api.h"\n'
+reg_apis_inc += '\n'
+reg_apis += '}\n\n'
+unreg_apis += '}\n'
+f = open_utf8('register_platform_apis.gen.cpp', 'w')
+f.write(reg_apis_inc)
+f.write(reg_apis)
+f.write(unreg_apis)
+f.close()
+platform_sources.append('register_platform_apis.gen.cpp')
+
+env.Prepend(LIBS=env.Library('platform', platform_sources))
+
+Export('env')
diff --git a/platform/javascript/api/api.cpp b/platform/javascript/api/api.cpp
new file mode 100644
index 0000000000..f2b2ca40bf
--- /dev/null
+++ b/platform/javascript/api/api.cpp
@@ -0,0 +1,73 @@
+/*************************************************************************/
+/*  api.cpp                                                              */
+/*************************************************************************/
+/*                       This file is part of:                           */
+/*                           GODOT ENGINE                                */
+/*                      https://godotengine.org                          */
+/*************************************************************************/
+/* Copyright (c) 2007-2017 Juan Linietsky, Ariel Manzur.                 */
+/* Copyright (c) 2014-2017 Godot Engine contributors (cf. AUTHORS.md)    */
+/*                                                                       */
+/* Permission is hereby granted, free of charge, to any person obtaining */
+/* a copy of this software and associated documentation files (the       */
+/* "Software"), to deal in the Software without restriction, including   */
+/* without limitation the rights to use, copy, modify, merge, publish,   */
+/* distribute, sublicense, and/or sell copies of the Software, and to    */
+/* permit persons to whom the Software is furnished to do so, subject to */
+/* the following conditions:                                             */
+/*                                                                       */
+/* The above copyright notice and this permission notice shall be        */
+/* included in all copies or substantial portions of the Software.       */
+/*                                                                       */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,       */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF    */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*/
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY  */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,  */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE     */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
+/*************************************************************************/
+#include "api.h"
+#include "engine.h"
+#include "javascript_eval.h"
+
+static JavaScript *javascript_eval;
+
+void register_javascript_api() {
+
+	ClassDB::register_virtual_class<JavaScript>();
+	javascript_eval = memnew(JavaScript);
+	Engine::get_singleton()->add_singleton(Engine::Singleton("JavaScript", javascript_eval));
+}
+
+void unregister_javascript_api() {
+
+	memdelete(javascript_eval);
+}
+
+JavaScript *JavaScript::singleton = NULL;
+
+JavaScript *JavaScript::get_singleton() {
+
+	return singleton;
+}
+
+JavaScript::JavaScript() {
+
+	ERR_FAIL_COND(singleton != NULL);
+	singleton = this;
+}
+
+JavaScript::~JavaScript() {}
+
+void JavaScript::_bind_methods() {
+
+	ClassDB::bind_method(D_METHOD("eval", "code", "use_global_execution_context"), &JavaScript::eval, DEFVAL(false));
+}
+
+#if !defined(JAVASCRIPT_ENABLED) || !defined(JAVASCRIPT_EVAL_ENABLED)
+Variant JavaScript::eval(const String &p_code, bool p_use_global_exec_context) {
+
+	return Variant();
+}
+#endif
diff --git a/platform/javascript/api/api.h b/platform/javascript/api/api.h
new file mode 100644
index 0000000000..53cd9239fc
--- /dev/null
+++ b/platform/javascript/api/api.h
@@ -0,0 +1,31 @@
+/*************************************************************************/
+/*  api.h                                                                */
+/*************************************************************************/
+/*                       This file is part of:                           */
+/*                           GODOT ENGINE                                */
+/*                      https://godotengine.org                          */
+/*************************************************************************/
+/* Copyright (c) 2007-2017 Juan Linietsky, Ariel Manzur.                 */
+/* Copyright (c) 2014-2017 Godot Engine contributors (cf. AUTHORS.md)    */
+/*                                                                       */
+/* Permission is hereby granted, free of charge, to any person obtaining */
+/* a copy of this software and associated documentation files (the       */
+/* "Software"), to deal in the Software without restriction, including   */
+/* without limitation the rights to use, copy, modify, merge, publish,   */
+/* distribute, sublicense, and/or sell copies of the Software, and to    */
+/* permit persons to whom the Software is furnished to do so, subject to */
+/* the following conditions:                                             */
+/*                                                                       */
+/* The above copyright notice and this permission notice shall be        */
+/* included in all copies or substantial portions of the Software.       */
+/*                                                                       */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,       */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF    */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*/
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY  */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,  */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE     */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
+/*************************************************************************/
+void register_javascript_api();
+void unregister_javascript_api();
diff --git a/platform/javascript/javascript_eval.h b/platform/javascript/api/javascript_eval.h
index ed7cf383da..4d0b0b21ff 100644
--- a/platform/javascript/javascript_eval.h
+++ b/platform/javascript/api/javascript_eval.h
@@ -27,8 +27,6 @@
 /* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE     */
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
 /*************************************************************************/
-#ifdef JAVASCRIPT_EVAL_ENABLED
-
 #ifndef JAVASCRIPT_EVAL_H
 #define JAVASCRIPT_EVAL_H
 
@@ -52,4 +50,3 @@ public:
 };
 
 #endif // JAVASCRIPT_EVAL_H
-#endif // JAVASCRIPT_EVAL_ENABLED
diff --git a/platform/javascript/javascript_eval.cpp b/platform/javascript/javascript_eval.cpp
index 1d737879f6..a755dcb5c4 100644
--- a/platform/javascript/javascript_eval.cpp
+++ b/platform/javascript/javascript_eval.cpp
@@ -29,16 +29,9 @@
 /*************************************************************************/
 #ifdef JAVASCRIPT_EVAL_ENABLED
 
-#include "javascript_eval.h"
+#include "api/javascript_eval.h"
 #include "emscripten.h"
 
-JavaScript *JavaScript::singleton = NULL;
-
-JavaScript *JavaScript::get_singleton() {
-
-	return singleton;
-}
-
 extern "C" EMSCRIPTEN_KEEPALIVE uint8_t *resize_poolbytearray_and_open_write(PoolByteArray *p_arr, PoolByteArray::Write *r_write, int p_len) {
 
 	p_arr->resize(p_len);
@@ -182,18 +175,4 @@ Variant JavaScript::eval(const String &p_code, bool p_use_global_exec_context) {
 	return Variant();
 }
 
-void JavaScript::_bind_methods() {
-
-	ClassDB::bind_method(D_METHOD("eval", "code", "use_global_execution_context"), &JavaScript::eval, false);
-}
-
-JavaScript::JavaScript() {
-
-	ERR_FAIL_COND(singleton != NULL);
-	singleton = this;
-}
-
-JavaScript::~JavaScript() {
-}
-
 #endif // JAVASCRIPT_EVAL_ENABLED
diff --git a/platform/javascript/os_javascript.cpp b/platform/javascript/os_javascript.cpp
index 77d81aec5d..c416baf0c9 100644
--- a/platform/javascript/os_javascript.cpp
+++ b/platform/javascript/os_javascript.cpp
@@ -512,11 +512,6 @@ void OS_JavaScript::initialize(const VideoMode &p_desired, int p_video_driver, i
 #undef SET_EM_CALLBACK
 #undef EM_CHECK
 
-#ifdef JAVASCRIPT_EVAL_ENABLED
-	javascript_eval = memnew(JavaScript);
-	Engine::get_singleton()->add_singleton(Engine::Singleton("JavaScript", javascript_eval));
-#endif
-
 	visual_server->init();
 }
 
diff --git a/platform/javascript/os_javascript.h b/platform/javascript/os_javascript.h
index f478f95dd2..85c185c10f 100644
--- a/platform/javascript/os_javascript.h
+++ b/platform/javascript/os_javascript.h
@@ -32,7 +32,6 @@
 
 #include "audio_driver_javascript.h"
 #include "drivers/unix/os_unix.h"
-#include "javascript_eval.h"
 #include "main/input_default.h"
 #include "os/input.h"
 #include "os/main_loop.h"
@@ -67,10 +66,6 @@ class OS_JavaScript : public OS_Unix {
 
 	PowerJavascript *power_manager;
 
-#ifdef JAVASCRIPT_EVAL_ENABLED
-	JavaScript *javascript_eval;
-#endif
-
 	static void _close_notification_funcs(const String &p_file, int p_flags);
 
 	void process_joypads();
diff --git a/platform/register_platform_apis.h b/platform/register_platform_apis.h
new file mode 100644
index 0000000000..37f98f6cd3
--- /dev/null
+++ b/platform/register_platform_apis.h
@@ -0,0 +1,36 @@
+/*************************************************************************/
+/*  register_platform_apis.h                                             */
+/*************************************************************************/
+/*                       This file is part of:                           */
+/*                           GODOT ENGINE                                */
+/*                      https://godotengine.org                          */
+/*************************************************************************/
+/* Copyright (c) 2007-2017 Juan Linietsky, Ariel Manzur.                 */
+/* Copyright (c) 2014-2017 Godot Engine contributors (cf. AUTHORS.md)    */
+/*                                                                       */
+/* Permission is hereby granted, free of charge, to any person obtaining */
+/* a copy of this software and associated documentation files (the       */
+/* "Software"), to deal in the Software without restriction, including   */
+/* without limitation the rights to use, copy, modify, merge, publish,   */
+/* distribute, sublicense, and/or sell copies of the Software, and to    */
+/* permit persons to whom the Software is furnished to do so, subject to */
+/* the following conditions:                                             */
+/*                                                                       */
+/* The above copyright notice and this permission notice shall be        */
+/* included in all copies or substantial portions of the Software.       */
+/*                                                                       */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,       */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF    */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*/
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY  */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,  */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE     */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
+/*************************************************************************/
+#ifndef REGISTER_APIS_H
+#define REGISTER_APIS_H
+
+void register_platform_apis();
+void unregister_platform_apis();
+
+#endif