Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve RunScript() and MSWSetModernEmulationLevel() documentation

Browse Source 
Try to explain things better and add a couple of examples.
This commit is contained in:
Vadim Zeitlin
2017-10-22 18:17:56 +02:00
parent 6644a489e8
commit b82af43361
1 changed files with 82 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
interface/wx/webview.h
View File

@@ -460,47 +460,95 @@ public:
virtual void Reload(wxWebViewReloadFlags flags = wxWEBVIEW_RELOAD_DEFAULT) = 0; virtual void Reload(wxWebViewReloadFlags flags = wxWEBVIEW_RELOAD_DEFAULT) = 0;
/** /**
Sets IE emulation level to a modern one, changing MSW registry. It is used to enable Sets emulation level to more modern level.
JSON object on Runscript(), because it wouldn't work with default emulation level.
@see RunScript() for further details. This function is useful to enable some minimally modern emulation level
@param modernLevel @true to set level to IE8, @false to set level to old mode. of the system browser control used for wxWebView implementation under
@return @true if level can be set, @false if it is not. MSW, rather than using the currently default, IE7-compatible,
emulation level. Currently the modern emulation level is only IE8, but
this could change in the future and shouldn't be relied on.
Please notice that this function works by modifying the per-user part
of MSW registry, which has several implications: first, it is
sufficient to call it only once (per user) as the changes done by it
are persistent and, second, if you do not want them to be persistent,
you need to call it with @false argument explicitly.
In particular, this function should be called to allow RunScript() to
work for JavaScript code returning arbitrary objects, which is not
supported at the default emulation level.
This function is MSW-specific and doesn't exist under other platforms.
See https://msdn.microsoft.com/en-us/library/ee330730#browser_emulation
for more information about browser control emulation levels.
@param modernLevel @true to set level to a level modern enough to allow
all wxWebView features to work (currently IE8), @false to reset the
emulation level to its default, compatible value.
@return @true on success, @false on failure (a warning message is also
logged in the latter case).
@since 3.1.1 @since 3.1.1
*/ */
bool MSWSetModernEmulationLevel(bool modernLevel = true) = 0; bool MSWSetModernEmulationLevel(bool modernLevel = true);
/** /**
Runs the given JavaScript. It returns true if the script was run successfully and Runs the given JavaScript code.
additionally returns the script return value in output.
It returns strings, integers, floating point numbers, booleans and objects (as JSON).
@note When using wxWEBVIEW_WEBKIT (GTK), it returns true always unless you pass
an output param to the method. In that case, it would return false. RunScript
outputs are supported on wxWEBVIEW_WEBKIT2 (GTK3).
When using wxWEBVIEW_WEBKIT (OSX), there are two limits: JavaScript code is executed inside the browser control and has full
1) JavaScript allocations greater than 10MB. access to DOM and other browser-provided functionality. For example,
2) JavaScript that takes longer than 10 seconds to execute. this code
@code
webview->RunScript("document.write('Hello from wxWidgets!')");
@endcode
will replace the current page contents with the provided string.
When using wxWEBVIEW_BACKEND_IE you must wait for the current If @a output is non-null, it is filled with the result of executing
page to finish loading before calling RunScript(). this code on success, e.g. a JavaScript value such as a string, a
It is compulsory to have a script tag inside HTML to run JavaScript, on MSW. number (integer or floating point), a boolean or JSON representation
for non-primitive types such as arrays and objects. For example:
@code
wxString result;
if ( webview->RunScript
(
"document.getElementById('some_id').innderHTML",
&result
) )
{
... result contains the contents of the given element ...
}
//else: the element with this ID probably doesn't exist.
@endcode
When using wxWEBVIEW_BACKEND_IE, JSON is not available in Quirks or This function has a few platform-specific limitations:
IE6/7 standards mode, which is unfortunately the default one for the embedded browser control, see
https://docs.microsoft.com/en-us/scripting/javascript/reference/json-object-javascript#requirements - When using WebKit v1 in wxGTK2, retrieving the result of JavaScript
and see here how to make a program run use "modern" modes execution is unsupported and this function will always return false
https://msdn.microsoft.com/en-us/library/ee330730(v=vs.85)#browser_emulation if @a output is non-null to indicate this. This functionality is
There are two ways to get JSON working: fully supported when using WebKit v2 or later in wxGTK3.
1) You can use MSWModernEmulationLevel to change emulation level (recommended), for example:
@code - When using WebKit under macOS, code execution is limited to at most
MSWModernEmulationLevel(); 10MiB of memory and 10 seconds of execution time.
wxString result;
browser->RunScript("some JS code that uses JSON", &result); - When using IE backend under MSW, scripts can only be executed when
@endcode the current page is fully loaded (i.e. @c wxEVT_WEBVIEW_LOADED event
2) There is an implementation of JSON.stringify on RunScript that helps to return objects. was received). A script tag inside the page HTML is required in order
You don't need to change IE emulation level but it could not work for some cases. to run JavaScript.
@param javascript A wxString containing the JavaScript.
@param output wxString result pointer. It can be NULL and it is new in wxWidgets 3.1.1. Also notice that under MSW converting JavaScript objects to JSON is not
supported in the default emulation mode. wxWebView implements its own
object-to-JSON conversion as a fallback for this case, however it is
not as full-featured, well-tested or performing as the implementation
of this functionality in the browser control itself, so it is
recommended to use MSWSetModernEmulationLevel() to change emulation
level to a more modern one in which JSON conversion is done by the
control itself.
@param javascript JavaScript code to execute.
@param output Pointer to a string to be filled with the result value or
@NULL if it is not needed. This parameter is new since wxWidgets
version 3.1.1.
@return @true if there is a result, @false if there is an error. @return @true if there is a result, @false if there is an error.
*/ */
virtual bool RunScript(const wxString& javascript, wxString* output = NULL) = 0; virtual bool RunScript(const wxString& javascript, wxString* output = NULL) = 0;