-- xtra Chromium -- v0.14 (c) 2023 Valentin Schmidt -- BROWSER FUNCTIONS (INSTANCE) new object me, string url, object rect, *movieNum, callbackTarget browserClose object me -- destroys the browser browserLoadURL object me, string url browserLoadString object me, string html, string url browserStartDownload object me, string url, *localPath browserExecuteJavaScript object me, string code, string url browserShowDevTools object me browserSetRect object me, object rect browserSetVisible object me, integer flag browserResizeToWindow object me browserSetAutoResize object me, integer flag browserReload object me, *ignoreCacheFlag browserGoBack object me browserGoForward object me browserPrint object me browserPrintToPDF object me, string pdfFile browserSetZoomLevel object me, float level browserSendMouseClickEvent object me, integer x, integer y, integer modifiers, integer mouseButtonType, integer mouseUp, integer clickCount browserSendMouseMoveEvent object me, integer x, integer y, integer modifiers, integer mouseLeave browserSendMouseWheelEvent object me, integer x, integer y, integer modifiers, integer deltaX, integer deltaY browserSendKeyEvent object me, integer keyCode, integer modifiers browserSendTouchEvent object me, float x, float y, integer modifiers, float pressure, float rotationAngle browserSetHostFilterList object me, object hosts, *isWhiteList -- CEF FUNCTIONS (GLOBAL) *cefInit *settingsPropList, argsPropList CALLBACKS ========= OnAddressChange (aUrl) OnBeforeBrowse (aUrl) -> return TRUE to stop request OnBeforePopup (aUrl) -> return TRUE to stop request OnConsoleMessage (aLevel, aMsg) -> Return TRUE to stop the message from being output to the console OnDownloadUpdated (aReceivedBytes, aTotalBytes, aUrl, aPath) OnFaviconURLChange (aFaviconURL) OnKeyEvent (event_type, key_code, modifiers) -> Return TRUE to stop windows event bubbling OnLoadEnd (aHttpStatusCode) OnLoadError (aErrorCode, aErrorText, aFailedUrl) OnLoadingProgressChange (aProg) OnLoadStart (aTranistionType) OnPreKeyEvent (event_type, key_code, modifiers) -> Return TRUE to prevent that browser receives the event OnStatusMessage (aMsg) OnTitleChange (aTitle) OnBeforeContextMenu () -> Return TRUE to prevent any context menu to be shown -> Return list of strings to show a custom context menu. If the first element in the list is "", the default menu is replaced with the custom menu, otherwise custom menu entries are appended to the default menu. Use "-" to add menu separators. OnContextMenuCommand (aCommandID) -> Return TRUE to prevent that browser receives the menu command -> For custom context menus (see above) the aCommandID is 26500 + Some hints ========== - Supported props for optional cefInit() parameter 'settingsPropList' are: String values: "cache_path", "user_data_path", "user_agent", "javascript_flags", "log_file" Integer values: "ignore_certificate_errors", "log_severity", "remote_debugging_port", "background_color" (as ARGB) The properties have to be specified as strings, not symbols. - For supported props of optional 'argsPropList' see enclosed "ChromiumCommandLineSwitches.htm" (Note: not all switches in this list are supported, many are Chrome specific and don't work in Chromium) Both properties and values have to be strings. Note: for switches without value, pass an empty string as value in the propList. - The optional 'movienum' parameter that can be passed to new() determines into which window the browser is embedded, and defaults to 1 (=stage window). The number is the position of a window in _player.windowList, i.e. movienum = _player.windowList.getPos(myWinRef). Passing 0 as movienum creates an independant (or popup) browser in its own window. Passing -1 as movienum creates a windowless (or headless) browser. Such windowless browsers can e.g. be used for automation tasks like downloading files, exporting webpages to PDF etc. You can also remotely debug them by passing a "remote_debugging_port" (e.g. 8080) to cefInit(), and then open e.g. http://localhost:8080 in another Chrome/Chromium browser. Example code: settings = [:] settings["remote_debugging_port"] = 8080 args = [:] args["remote-allow-origins"] = "http://localhost:8080" cefInit(settings, args) ============================================================ IMPORTANT NOTES ON CALLBACKS AND THE BROWSER-LINGO-BINDING ============================================================ Both the available CEF callbacks and calling into Lingo from JS via window.cefQuery(...) are NOT "thread-safe". Basically, Director doesn't support multi-threading at all, so usually the only real safe way to implement callbacks in xtras is to use 'idle' events - i.e. you make the call into Director only when Director announced that it's currently idle. Since this means that the actual call is postponed, such calls can't return anything. Chromium xtra instead uses "raw" or direct callbacks, which make the call immediately, and thereby allows to return data back from Lingo to the xtra (which is e.g. needed for the 'OnBeforeBrowse' callback, since its return value determines if Chromium continues to load the passed URL or not). Such direct callbacks are fine as long as you don't mess with Director and its state at all, but e.g. only use simple Lingo (or other xtra based) processing of the received data. For anything else, you first *HAVE TO* "detach" from this direct callback. A simple technique for "detaching" is to use 1-ms (single-shot) timeout object. The enclosed demos include an optimized "detacher" lib that only uses a single overall timeout-object and an internal queue for handling all such "detach" tasks. Another reason for detaching such callbacks is that any code in their execution thread will fail silently (i.e. no scripting error alert shown) and therefor also can't be debugged. But code called after detaching behaves normally and can fully be debugged.