WebBrowser Reference

Reference for the web browser control (CTRL_WB / CTRL_SW) embedded in the main window of Tablacus Explorer and in its sub-windows (the options screen and dialogs).

• Related: te Reference (te.Ctrl / te.CreateCtrl(CTRL_SW, ...) / te.Arguments), api Reference, FolderView (ShellBrowser) Reference
• Source: the implementation of methodWB[] and CteWebBrowser (constructor, Invoke, Close) in TE/TE.cpp, and of the sub-window window procedure WndProc2

Notation: P = property, M = method. Member names are matched case-insensitively.

Table of Contents

1. Overview
2. How to Obtain
3. Methods
4. Properties
5. Event (OnClose) and Close Handling
6. Differences Between the Main Window and Sub-Windows
7. Constants
8. Examples

1. Overview

The WebBrowser object represents a window that displays an HTML page. Internally, one of the following is used.

In either case, you can access the DOM and the window object of the page being displayed through the Document and Window of this object. From a loaded page, you can call TE's features through external (= the te object).

2. How to Obtain

In asynchronous scripts (the WebView2 side, such as ui.js), await is needed, as in await te.Ctrl(CTRL_WB).

3. Methods

4. Properties

5. Event (OnClose) and Close Handling

If you set WebBrowser.OnClose = function (WB) { ... }, then when the user tries to close the window with the window's Close button (×) or the like, the window is not closed immediately; instead, this function is called. Inside the function, do one of the following.

• If a close operation occurs in a sub-window where OnClose is not set, it is simply closed.
• OnClose is called only in the window (sub-window) where the close request was issued. If the window is closed from a script with WB.Close(), OnClose is not called.
• An asynchronous function that can use await can also be passed as OnClose (options.js uses async function (WB)). However, unless you call Close() / PreventClose() once the work is finished (once the asynchronous confirmation is finished), the window remains in a state where it cannot be closed.
• After the close processing, it is a two-stage process: the window moves to a blank page on DocumentComplete and then is destroyed.
• Actual use: InitOptions in options.js shows a "Do you want to save?" confirmation when there are changes, calls WebBrowser.PreventClose() in ContinueOptions to cancel closing, and closes with CloseWB(WebBrowser, true). Dialog-type windows set ReturnDialogResult (which returns the result and calls WB.Close()) as OnClose.

6. Differences Between the Main Window and Sub-Windows

7. Constants

8. Examples

// 1. Open a sub-window (close to the options screen example)
const WB = te.CreateCtrl(CTRL_SW, "file:///C:/path/page.html", { name: "value" }, te.hwnd, 600, 400);   // returns a WebBrowser
WB.OnClose = function (WB) {
    // close without confirmation
    WB.Close();
};

// 2. Confirm before closing, and cancel
WB.OnClose = function (WB) {
    // IDNO = 7 (the return value of api.MessageBox)
    if (api.MessageBox(te.hwnd, "Close this window?", TITLE, MB_YESNO) == IDNO) {
        WB.PreventClose();   // cancel
        return;
    }
    WB.Close();
};

// 3. Read the DOM of the page
const doc = WB.Document;
const title = doc.title;
const win = WB.Window;
win.alert("hello");

// 4. On the opened page side (inside the sub-window)
//    te.Arguments receives this value only once, and then clears it
const args = te.Arguments;
const WebBrowser = te.Ctrl(CTRL_WB);   // its own WebBrowser
WebBrowser.Close();                    // close itself

// 5. The main WebBrowser (detecting the drop target)
te.OnDrop = function (Ctrl, dataObj, pgrfKeyState, pt, pdwEffect) {
    if (Ctrl.Type == CTRL_WB) {
        // dropped onto the address bar or the like
    }
};

For how to specify the arguments of te.CreateCtrl(CTRL_SW, ...) above, see the CreateCtrl entry in the te Reference. The arguments of OnDrop follow the order in the sync1.js implementation (Ctrl, dataObj, pgrfKeyState, pt, pdwEffect). TITLE, MB_YESNO, and IDNO are assumed to be the ones defined in consts.js and elsewhere (needs verification).

Related

• te Reference
• api Reference
• FolderView (ShellBrowser) Reference