With this PR I wish to propose changing the API and improving error handling throughout the library in a way that is intended to be backward-compatible for current users of the C API.

This work allows both C API and C++ API users to handle errors or at the very least detect that an error has occurred and then respond accordingly to minimize crashes due to invalid state.

Although this work is not finished, it is a good time to begin discussions.

Specific changes

• Change void return types to an error code type for all of the functions of the C API that could benefit from returning an error code.
  • This is a binary compatible change for the C API. Existing programs can use a new version of the library with no recompilation required.
• C++ API now throws exceptions. This is the sane way to report errors in C++. Most users will likely recompile the library anyway (it is header-only) so we do not have to worry too much about binary incompatibilities.
  • Should we allow library users to disable C++ exceptions, i.e. optionally not compile them? I think they should be enabled by default because the result will in many cases be the same: crash
• C API returns error codes by catching C++ exceptions and extracting error codes from them.
• The library should have the ability to report its own version. For now there is no distinction between the product version and API version. Let me know what you think about that.
• The library should have a version compatibility check, i.e. check whether the caller's version is supported by the library.
• Add a new function to the C API named webview_create_with_options that takes a struct as a parameter.
  • Allows us to expand the options that can be passed to the library, such as initial window size, whether to center the window, initial visibility, etc. We cannot keep changing webview_create when we need more options.
  • The minimum_required_version option is checked for compatibility and allows us to change behavior based on the version set by the caller.
  • I added an option to control initial visibility of the window along with a webview_show function to show the window on-demand. This demonstrates how we can change some behavior while providing backward-compatibility. The new behavior is to hide the window initially which requires users to call webview_show when they are ready.
  • Windows: When the window should be made visible initially:
    • Since 0.11.0: Use new behavior and show the window after embedding the underlying webview.
    • Before 0.11.0: Use old behavior and show the window before embedding the underlying webview.
• Deprecate webview_create and webview::webview(bool debug, void *wnd).
• I added @since 0.11 to the new C API functions so that we can track in which version a feature was added, but there is nothing in this project that uses this style of commenting. Later I think we should adapt the documentation comments for a documentation generator.

Tasks

• Initial C/C++ implementation (draft).
• Implement visibility option:
  • Windows
  • Linux
  • macOS
• Update tests.
• Update examples.
• Update documentation.
• Gather feedback.
• Implement changes based on feedback.

Won't Do

• Go implementation, tests and examples will not be updated in this PR both to reduce the scope of this PR and because I am not comfortable enough with Go. The core library must however not break compatibility.