{
  "name": "Browser",
  "component": "gui",
  "header": "nativeui/browser.h",
  "type": "Class",
  "namespace": "nu",
  "inherit": {
    "name": "View",
    "id": "view"
  },
  "description": "Native webview using system browser.",
  "detail": "Using `Browser` requires relatively new operating systems, for macOS the\nminimum version required is 10.10, for Linux it is required to install the\n`webkit2gtk` library with at least version 2.8.\n\nOn Windows the latest version of IE installed would be used by default.\n\nOn Linux due to poor support of hardware acceleration, the browser may fail to\nshow anything, in that case you may want to disable hardware acceleration.\n\n## WebView2 support\n\nOn Windows there is support for using\n[WebView2](https://docs.microsoft.com/en-us/microsoft-edge/webview2/) as\nbrowser backend, to enable it, you need to:\n\n1. Set the `<!name>webview2_support` option to `true`.\n2. Ship the `WebView2Loader.dll` file together with your program.\n3. Have users install Edge Beta/Dev/Canary or\n[WebView2 Runtime](https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution)\non their machines.\n\nThere are also a few things to notice:\n1. When WebView2 failed to initialize for any reason, the browser will\nfallback to use IE as backend quietly.\n2. If you don't use WebView2, it is safe to remove the `WebView2Loader.dll`\nfile.\n3. WebView2 can not use stable channels of Edge, it will search channels in\nthe order of WebView2 Runtime, Beta, Dev, and Canary.\n4. Some `Browser` APIs are not implemented with WebView2 backend, due to lack\nof APIs in WebView2.\n",
  "class_methods": [
    {
      "signature": {
        "returnType": {
          "name": "Browser",
          "id": "browser"
        },
        "name": "create",
        "parameters": [
          {
            "type": {
              "name": "Browser::Options",
              "id": "browser_options"
            },
            "name": "options"
          }
        ],
        "shortStr": "create(options)",
        "str": "create(options)"
      },
      "description": "Create a new browser view.",
      "id": "create-options"
    },
    {
      "signature": {
        "returnType": {
          "name": "boolean"
        },
        "name": "registerprotocol",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "scheme"
          },
          {
            "type": {
              "name": "function"
            },
            "name": "handler"
          }
        ],
        "shortStr": "registerprotocol(scheme, handler)",
        "str": "registerprotocol(scheme, handler)"
      },
      "description": "Register a custom protocol with `scheme` and `handler`.",
      "detail": "When the browser sends a request with `scheme`, the `handler` will be\ncalled with `handler(url)`, and the `handler` must return an instance of\nclass that inherits from `<!type>ProtocolJob`.\n\nThe `handler` is guaranteed to be called in the main thread.\n\nThis API is not supported on Windows with WebView2 backend.\n",
      "id": "registerprotocol-scheme-handler"
    },
    {
      "signature": {
        "name": "unregisterprotocol",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "scheme"
          }
        ],
        "shortStr": "unregisterprotocol(scheme)",
        "str": "unregisterprotocol(scheme)"
      },
      "description": "Unregister the custom protocol with `scheme`.",
      "detail": "This API is not supported on Windows with WebView2 backend.",
      "id": "unregisterprotocol-scheme"
    }
  ],
  "methods": [
    {
      "signature": {
        "name": "loadurl",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "url"
          }
        ],
        "shortStr": "loadurl(url)",
        "str": "loadurl(url)"
      },
      "description": "Load the URL.",
      "id": "loadurl-url"
    },
    {
      "signature": {
        "name": "loadhtml",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "html",
            "description": "The string to use as the contents of the webpage."
          },
          {
            "type": {
              "name": "string"
            },
            "name": "baseurl",
            "description": "A URL used to resolve relative URLs within the document."
          }
        ],
        "shortStr": "loadhtml(html, baseurl)",
        "str": "loadhtml(html, baseurl)"
      },
      "description": "Set the webpage contents and base URL.",
      "detail": "On Windows with WebView2 backend, `baseurl` is not respected.",
      "id": "loadhtml-html-baseurl"
    },
    {
      "signature": {
        "returnType": {
          "name": "string"
        },
        "name": "geturl",
        "parameters": [],
        "shortStr": "geturl()",
        "str": "geturl()"
      },
      "description": "Return current URL.",
      "id": "geturl"
    },
    {
      "signature": {
        "returnType": {
          "name": "string"
        },
        "name": "gettitle",
        "parameters": [],
        "shortStr": "gettitle()",
        "str": "gettitle()"
      },
      "description": "Return the title of document.",
      "id": "gettitle"
    },
    {
      "signature": {
        "name": "setuseragent",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "useragent"
          }
        ],
        "shortStr": "setuseragent(useragent)",
        "str": "setuseragent(useragent)"
      },
      "description": "Change browser's user agent.",
      "detail": "On Windows, due to Internet Explorer's limitations, calling `SetUserAgent`\nwould change all web pages' user agents in current process.\n\nThis API is not supported on Windows with WebView2 backend.\n",
      "id": "setuseragent-useragent"
    },
    {
      "signature": {
        "returnType": {
          "name": "boolean"
        },
        "name": "ismagnifiable",
        "parameters": [],
        "shortStr": "ismagnifiable()",
        "str": "ismagnifiable()"
      },
      "platform": [
        "macOS"
      ],
      "description": "Return whether page's magnification can be changed with gestures.",
      "id": "ismagnifiable"
    },
    {
      "signature": {
        "name": "setmagnifiable",
        "parameters": [
          {
            "type": {
              "name": "boolean"
            },
            "name": "magnifiable"
          }
        ],
        "shortStr": "setmagnifiable(magnifiable)",
        "str": "setmagnifiable(magnifiable)"
      },
      "platform": [
        "macOS"
      ],
      "description": "Set whether page's magnification can be changed with gestures.",
      "id": "setmagnifiable-magnifiable"
    },
    {
      "signature": {
        "name": "executejavascript",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "code"
          },
          {
            "type": {
              "name": "function"
            },
            "name": "callback"
          }
        ],
        "shortStr": "executejavascript(code, callback)",
        "str": "executejavascript(code, callback)"
      },
      "description": "Evaluate `code` in browser and get the evaluated result.",
      "detail": "The `callback` will be called with `callback(success, result)`, the\n`result` argument is a generic value that created from the result of\n`code`.\n\nNote that due to limitations of system toolkits, the execution may fail if\nthe result of `code` can not be fully converted to JSON.\n\nOn Windows with WebView2 backend, the `success` may be true even when\nexception is threw in the executed code.\n",
      "id": "executejavascript-code-callback"
    },
    {
      "signature": {
        "name": "goback",
        "parameters": [],
        "shortStr": "goback()",
        "str": "goback()"
      },
      "description": "Navigate to the back item in the back-forward list.",
      "id": "goback"
    },
    {
      "signature": {
        "returnType": {
          "name": "boolean"
        },
        "name": "cangoback",
        "parameters": [],
        "shortStr": "cangoback()",
        "str": "cangoback()"
      },
      "description": "Return whether there is a back item in the back-forward list that can be\nnavigated to.\n",
      "id": "cangoback"
    },
    {
      "signature": {
        "name": "goforward",
        "parameters": [],
        "shortStr": "goforward()",
        "str": "goforward()"
      },
      "description": "Navigate to the forward item in the back-forward list.",
      "id": "goforward"
    },
    {
      "signature": {
        "returnType": {
          "name": "boolean"
        },
        "name": "cangoforward",
        "parameters": [],
        "shortStr": "cangoforward()",
        "str": "cangoforward()"
      },
      "description": "Return whether there is a forward item in the back-forward list that can\nbe navigated to.\n",
      "id": "cangoforward"
    },
    {
      "signature": {
        "name": "reload",
        "parameters": [],
        "shortStr": "reload()",
        "str": "reload()"
      },
      "description": "Reload current page.",
      "id": "reload"
    },
    {
      "signature": {
        "name": "stop",
        "parameters": [],
        "shortStr": "stop()",
        "str": "stop()"
      },
      "description": "Stop loading all resources on the current page.",
      "id": "stop"
    },
    {
      "signature": {
        "returnType": {
          "name": "boolean"
        },
        "name": "isloading",
        "parameters": [],
        "shortStr": "isloading()",
        "str": "isloading()"
      },
      "description": "Return whether current page is loading content.",
      "id": "isloading"
    },
    {
      "signature": {
        "name": "setbindingname",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "name"
          }
        ],
        "shortStr": "setbindingname(name)",
        "str": "setbindingname(name)"
      },
      "description": "Set the `name` of object which would have the native bindings.",
      "detail": "By default native bindings are added to the `window` object, by calling\nthis API, native bindings will be added to the `window[name]` object.\n",
      "id": "setbindingname-name"
    },
    {
      "signature": {
        "name": "addbinding",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "name"
          },
          {
            "type": {
              "name": "function"
            },
            "name": "func"
          }
        ],
        "shortStr": "addbinding(name, func)",
        "str": "addbinding(name, func)"
      },
      "description": "Add a native binding to web page with `name`.",
      "detail": "The `func` will be called with automatically converted arguments.\n",
      "id": "addbinding-name-func"
    },
    {
      "signature": {
        "name": "addrawbinding",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "name"
          },
          {
            "type": {
              "name": "function"
            },
            "name": "func"
          }
        ],
        "shortStr": "addrawbinding(name, func)",
        "str": "addrawbinding(name, func)"
      },
      "description": "Add a raw handler to web page with `name`.",
      "detail": "The `func` will be called with a list of arguments passed from JavaScript.\n",
      "id": "addrawbinding-name-func"
    },
    {
      "signature": {
        "name": "removebinding",
        "parameters": [
          {
            "type": {
              "name": "string"
            },
            "name": "name"
          }
        ],
        "shortStr": "removebinding(name)",
        "str": "removebinding(name)"
      },
      "description": "Remove the native binding with `name`.",
      "id": "removebinding-name"
    }
  ],
  "events": [
    {
      "signature": {
        "name": "onclose",
        "parameters": [
          {
            "type": {
              "name": "Browser",
              "id": "browser"
            },
            "name": "self"
          }
        ],
        "shortStr": "onclose(self)",
        "str": "onclose(self)"
      },
      "description": "Emitted when the web page requests to close.",
      "id": "onclose-self"
    },
    {
      "signature": {
        "name": "onupdatecommand",
        "parameters": [
          {
            "type": {
              "name": "Browser",
              "id": "browser"
            },
            "name": "self"
          }
        ],
        "shortStr": "onupdatecommand(self)",
        "str": "onupdatecommand(self)"
      },
      "description": "Emitted when the back-forward list has changed.",
      "id": "onupdatecommand-self"
    },
    {
      "signature": {
        "name": "onchangeloading",
        "parameters": [
          {
            "type": {
              "name": "Browser",
              "id": "browser"
            },
            "name": "self"
          }
        ],
        "shortStr": "onchangeloading(self)",
        "str": "onchangeloading(self)"
      },
      "description": "Emitted when the browser starts or stops loading content.",
      "id": "onchangeloading-self"
    },
    {
      "signature": {
        "name": "onupdatetitle",
        "parameters": [
          {
            "type": {
              "name": "Browser",
              "id": "browser"
            },
            "name": "self"
          },
          {
            "type": {
              "name": "string"
            },
            "name": "title"
          }
        ],
        "shortStr": "onupdatetitle(self, title)",
        "str": "onupdatetitle(self, title)"
      },
      "description": "Emitted when document's title is changed.",
      "id": "onupdatetitle-self-title"
    },
    {
      "signature": {
        "name": "onstartnavigation",
        "parameters": [
          {
            "type": {
              "name": "Browser",
              "id": "browser"
            },
            "name": "self"
          },
          {
            "type": {
              "name": "string"
            },
            "name": "url"
          }
        ],
        "shortStr": "onstartnavigation(self, url)",
        "str": "onstartnavigation(self, url)"
      },
      "description": "Emitted when the browser begins provisional navigation.",
      "id": "onstartnavigation-self-url"
    },
    {
      "signature": {
        "name": "oncommitnavigation",
        "parameters": [
          {
            "type": {
              "name": "Browser",
              "id": "browser"
            },
            "name": "self"
          },
          {
            "type": {
              "name": "string"
            },
            "name": "url"
          }
        ],
        "shortStr": "oncommitnavigation(self, url)",
        "str": "oncommitnavigation(self, url)"
      },
      "description": "Emitted when the browser begins to receive web content.",
      "id": "oncommitnavigation-self-url"
    },
    {
      "signature": {
        "name": "onfinishnavigation",
        "parameters": [
          {
            "type": {
              "name": "Browser",
              "id": "browser"
            },
            "name": "self"
          },
          {
            "type": {
              "name": "string"
            },
            "name": "url"
          }
        ],
        "shortStr": "onfinishnavigation(self, url)",
        "str": "onfinishnavigation(self, url)"
      },
      "description": "Emitted when the navigation is complete.",
      "id": "onfinishnavigation-self-url"
    },
    {
      "signature": {
        "name": "onfailnavigation",
        "parameters": [
          {
            "type": {
              "name": "Browser",
              "id": "browser"
            },
            "name": "self"
          },
          {
            "type": {
              "name": "string"
            },
            "name": "url"
          },
          {
            "type": {
              "name": "integer"
            },
            "name": "code"
          }
        ],
        "shortStr": "onfailnavigation(self, url, code)",
        "str": "onfailnavigation(self, url, code)"
      },
      "description": "Emitted when the navigation fails.",
      "id": "onfailnavigation-self-url-code"
    }
  ],
  "module": "yue.gui",
  "id": "browser"
}