WebView

https://github.com/ysdragon/webview
Admin
WebView is a powerful Ring library that enables the creation of cross-platform desktop applications...
Tokens:20,718
Snippets:98
Trust Score:8.6
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### Basic WebView Application Setup in Ring

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Demonstrates the fundamental structure of a Ring WebView application. It initializes the WebView, sets window properties, loads HTML content, and runs the application. Dependencies include the 'webview.ring' library.

```ring
load "webview.ring"

# Create and configure the webview
oWebView = new WebView()
oWebView {
    setTitle("My Application")
    setSize(800, 600, WEBVIEW_HINT_NONE)
    setHtml(`
        <!DOCTYPE html>
        <html>
        <head><title>My App</title></head>
        <body>
            <h1>Hello, Ring WebView!</h1>
            <button onclick="alert('Hello from JavaScript!')">Click Me</button>
        </body>
        </html>
    `)
    run()
}
```

--------------------------------

### Ring Language "Hello, World!" Example

Source: https://github.com/ysdragon/webview/blob/main/examples/assets/index.html

A basic "Hello, World!" program written in the Ring programming language. This example demonstrates the simple and natural syntax of Ring for outputting text to the console, utilizing the `see` function and the `nl` (newline) operator.

```ring
see "Hello, World!" + nl
```

--------------------------------

### Install Ring WebView via RingPM

Source: https://github.com/ysdragon/webview/blob/main/README.md

This command installs the Ring WebView library from the ysdragon repository using the Ring Package Manager (RingPM). Ensure RingPM is set up and configured correctly before running this command.

```sh
ringpm install webview from ysdragon
```

--------------------------------

### Initialize and Configure WebView with HTML Form - Ring

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Initializes a WebView instance, sets its title and size, binds a form submission handler, and loads an HTML page containing a form with JavaScript for submission. The `run()` method starts the WebView event loop.

```Ring
oWebView = NULL

func main()
    oWebView = new WebView()
    oWebView {
        setTitle("Form Example")
        setSize(500, 400, WEBVIEW_HINT_NONE)
        
        bind("submitForm", :handleForm)
        
        setHtml(`
            <!DOCTYPE html>
            <html>
            <head><title>Contact Form</title></head>
            <body>
                <h1>Contact Us</h1>
                <form name="contactForm">
                    <input type="text" name="name" placeholder="Your Name" required>
                    <input type="email" name="email" placeholder="Your Email" required>
                    <button type="button" onclick="submitFormData()">Submit</button>
                </form>
                <div id="response"></div>
                
                <script>
                async function submitFormData() {
                    const form = document.forms.contactForm;
                    const formData = [
                        form.name.value,
                        form.email.value
                    ];
                    
                    try {
                        const result = await window.submitForm(formData);
                        document.getElementById('response').innerText = result;
                    } catch (error) {
                        document.getElementById('response').innerText = 'Error: ' + error;
                    }
                }
                </script>
            </body>
            </html>
        `)
        
        run()
    }

func handleForm(id, req)
    # Parse form data from JSON
    aData = json_decode(req)
    ? aData
    name = aData[1][1]
    email = aData[1][2]
    
    see "Form submitted - Name: " + name + ", Email: " + email + nl
    
    # Process form (save to database, send email, etc.)
    
    oWebView.wreturn(id, WEBVIEW_ERROR_OK, '"Form submitted successfully!"')

```

--------------------------------

### Install ring_webview Library

Source: https://github.com/ysdragon/webview/blob/main/CMakeLists.txt

This CMake command installs the 'ring_webview' target as a library. It specifies the destination directory within the installation prefix, typically '${RING_ROOT}/lib'. This is a standard procedure for making libraries available after installation.

```cmake
install(TARGETS ring_webview
    LIBRARY DESTINATION "${RING_ROOT}/lib"
)
```

--------------------------------

### Clone WebView Repository

Source: https://github.com/ysdragon/webview/blob/main/README.md

Clones the WebView repository from GitHub. Ensure the --recursive flag is used for submodules. This step can be skipped if the library is already installed via RingPM.

```sh
git clone https://github.com/ysdragon/webview.git --recursive
```

--------------------------------

### Complete Counter Application Example

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

A full Ring application demonstrating a counter that can be incremented via a button in the WebView. It binds a Counter class, sets HTML content with a button, and updates the displayed count using evalJS. Requires webview.ring and uses a Counter class.

```Ring
load "webview.ring"

oWebView = NULL

func main()
    oWebView = new WebView()
    oWebView {
        setTitle("Counter Example")
        setSize(400, 300, WEBVIEW_HINT_NONE)
        
        # Bind counter methods
        bind(new Counter, [
            ["increment", :increment]
        ])
        
        setHtml(`
            <!DOCTYPE html>
            <html>
            <head><title>Counter</title></head>
            <body>
                <h1>Counter: <span id="counter">0</span></h1>
                <button onclick="window.increment()">Increment</button>
            </body>
            </html>
        `)
        
        run()
    }

class Counter
    value = 0
    
    func increment(id, req)
        self.value++
        # Update UI and send response
        oWebView.evalJS("document.getElementById('counter').innerText = " + string(self.value))
        oWebView.wreturn(id, WEBVIEW_ERROR_OK, "")

```

--------------------------------

### Inject JavaScript on Initialization with Ring

Source: https://context7.com/ysdragon/webview/llms.txt

This example demonstrates injecting custom JavaScript code into a WebView before the page content loads using Ring. It sets up global variables and functions that are available when the page renders. It requires the 'webview.ring' library.

```ring
load "webview.ring"

oWebView = new WebView()

oWebView {
    setTitle("JavaScript Injection Demo")
    setSize(600, 400, WEBVIEW_HINT_NONE)

    # Inject JavaScript before page loads
    injectJS(`
        // Set up global configuration
        window.APP_CONFIG = {
            version: '1.0.0',
            theme: 'dark',
            apiUrl: 'https://api.example.com'
        };

        // Add utility functions
        window.formatCurrency = function(amount) {
            return '$' + amount.toFixed(2);
        };

        window.log = function(message) {
            console.log('[APP]', message);
        };

        // Initialize on page load
        window.addEventListener('DOMContentLoaded', function() {
            window.log('Application initialized');
            console.log('Config:', window.APP_CONFIG);
        });
    `)

    setHtml(`
        <!DOCTYPE html>
        <html>
        <body>
            <h1>Injected JavaScript Demo</h1>
            <p>Open browser console to see injected code in action</p>
            <button onclick="testInjected()">Test Injected Functions</button>
            <div id="output"></div>
            <script>
                function testInjected() {
                    const price = 42.5;
                    const formatted = window.formatCurrency(price);
                    window.log('Formatting price: ' + formatted);
                    document.getElementById('output').innerText =
                        'Version: ' + window.APP_CONFIG.version +
                        ', Price: ' + formatted;
                }
            </script>
        </body>
        </html>
    `)

    run()
}
```

--------------------------------

### Basic Ring WebView Application

Source: https://github.com/ysdragon/webview/blob/main/README.md

A fundamental example of creating a WebView application using the Ring programming language. It demonstrates initializing the WebView, setting window properties like title and size, loading HTML content, and running the application's event loop. The application closes after the window is dismissed.

```ring
# Load the webview library
load "webview.ring"

# Create a new WebView instance.
oWebView = new WebView()

oWebView {
    # Set the title of the native window.
    setTitle("My First WebView App")

    # Set the size of the window (width, height, hint).
    # WEBVIEW_HINT_NONE allows the window to be resized.
    setSize(800, 600, WEBVIEW_HINT_NONE)

    # Load HTML content into the webview.
    setHtml(`<h1>Welcome to Ring WebView!</h1>`)

    # Run the main event loop. This will block until the window is closed.
    run()
}

# This message will be displayed after the webview window is closed.
see "Application Closed." + nl

```

--------------------------------

### Ring WebView Window Management

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Illustrates managing window properties such as title and size using the WebView object. It also shows how to retrieve the native window handle for platform-specific integrations. Requires an initialized WebView object.

```ring
oWebView = new WebView()

# Window properties
oWebView.setTitle("My Application")
oWebView.setSize(800, 600, WEBVIEW_HINT_NONE)  # width, height, hints

# Get native window handle (for platform integration)
nativeWindow = oWebView.getWindow()
```

--------------------------------

### Configure WebView Window Size and Hints with Ring

Source: https://context7.com/ysdragon/webview/llms.txt

This example demonstrates how to set the window size and behavior for a Ring WebView. It covers different size hints like NONE (resizable), FIXED (non-resizable), MIN (minimum size), and MAX (maximum size). It uses the 'webview.ring' library.

```ring
load "webview.ring"

# Example 1: Resizable window
oWebView1 = new WebView()
oWebView1.setTitle("Resizable Window")
oWebView1.setSize(800, 600, WEBVIEW_HINT_NONE)

# Example 2: Fixed size window (cannot be resized)
oWebView2 = new WebView()
oWebView2.setTitle("Fixed Size Window")
oWebView2.setSize(400, 300, WEBVIEW_HINT_FIXED)

# Example 3: Minimum size (can be enlarged)
oWebView3 = new WebView()
oWebView3.setTitle("Minimum Size Window")
oWebView3.setSize(600, 400, WEBVIEW_HINT_MIN)

# Example 4: Maximum size (can be made smaller)
oWebView4 = new WebView()
oWebView4.setTitle("Maximum Size Window")
oWebView4.setSize(1024, 768, WEBVIEW_HINT_MAX)

# Use one of the configurations
oWebView1 {
    setHtml(`
        <!DOCTYPE html>
        <html>
        <body>
            <h1>Window Configuration Demo</h1>
            <p>This window can be freely resized (WEBVIEW_HINT_NONE)</p>
            <ul>
                <li>WEBVIEW_HINT_NONE: Freely resizable</li>
                <li>WEBVIEW_HINT_FIXED: Fixed size, no resizing</li>
                <li>WEBVIEW_HINT_MIN: Minimum size, can enlarge</li>
                <li>WEBVIEW_HINT_MAX: Maximum size, can shrink</li>
            </ul>
        </body>
        </html>
    `)
    run()
}
```

--------------------------------

### Execute JavaScript from Ring

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Provides examples of executing JavaScript code within the WebView directly from Ring. This includes simple alerts, updating DOM elements by ID, and calling existing JavaScript functions. Requires the WebView object and valid JavaScript syntax.

```Ring
# Simple JavaScript execution
oWebView.evalJS("alert('Hello from Ring!');")

# Update DOM elements
oWebView.evalJS("document.getElementById('status').innerText = 'Updated!';")

# Call JavaScript functions
oWebView.evalJS("myJavaScriptFunction('argument');")
```

--------------------------------

### Send Responses from Ring to JavaScript

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Details the usage of the wreturn method to send responses back to JavaScript. Examples cover sending string, number, and JSON responses, all correctly formatted as strings. Requires the callback 'id', an error code (e.g., WEBVIEW_ERROR_OK), and the response payload.

```Ring
# String response
oWebView.wreturn(id, WEBVIEW_ERROR_OK, '"Hello from Ring!"')

# Number response
oWebView.wreturn(id, WEBVIEW_ERROR_OK, string(42))

# JSON response
oWebView.wreturn(id, WEBVIEW_ERROR_OK, '{"success": true, "data": "value"}')
```

--------------------------------

### Inject JavaScript to run before page load

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Demonstrates injecting JavaScript code that will execute before the main page content is loaded. This is useful for setting up global variables or initial configurations. Requires the WebView object and valid JavaScript code.

```Ring
# Inject JavaScript that runs before the main content
oWebView.injectJS("
    window.myGlobalVar = 'Hello from injected JS!';
    console.log('Injected JS executed');
")
```

--------------------------------

### Ring WebView Global Configuration

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Shows how to customize global configuration settings for the WebView library before creating instances. This includes options for debug mode and parent window handles. It modifies a global configuration array.

```ring
# Customize global configuration before creating instances
aWebViewConfig = [
    :debug = false,    # Enable/disable debug mode (default: true)
    :window = NULL    # Parent window handle (default: NULL for new window)
]
```

--------------------------------

### Navigating to Local Files and Remote URLs in Ring WebView

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Shows how to navigate the WebView to specific local HTML files or remote URLs. This involves using the `navigate()` method with file paths or web addresses. Requires an initialized WebView object.

```ring
# Navigate to a local file URL
oWebView.navigate("file:///path/to/your/file.html")
```

```ring
# Navigate to a URL
oWebView.navigate("https://www.example.com")
```

--------------------------------

### Ring to JavaScript Communication via Binding in Ring

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Enables calling Ring functions from JavaScript by exposing them using the `bind()` method. This example demonstrates exposing 'sayHello' and 'calculate' functions, including handling requests and returning responses using JSON. Dependencies: 'webview.ring', 'simplejson.ring'.

```ring
load "webview.ring"
load "simplejson.ring"

# Global variables
oWebView = NULL
# Define functions to expose to JavaScript
aBindList = [
    ["sayHello", :handleGreeting],
    ["calculate", :doMath]
]

func main()
    oWebView = new WebView()
    
    oWebView {
        setTitle("Ring-JavaScript Communication")
        setSize(600, 400, WEBVIEW_HINT_NONE)
        
        setHtml(`
            <!DOCTYPE html>
            <html>
            <head><title>Communication Demo</title></head>
            <body>
                <h1>Ring-JavaScript Communication</h1>
                <button onclick="callRingHello()">Say Hello</button>
                <button onclick="callRingCalc()">Calculate</button>
                <div id="result"></div>
                
                <script>
                async function callRingHello() {
                    try {
                        const response = await window.sayHello('World');
                        document.getElementById('result').innerText = response;
                    } catch (error) {
                        console.error('Error:', error);
                    }
                }
                
                async function callRingCalc() {
                    try {
                        const result = await window.calculate(5, 3, 'add');
                        document.getElementById('result').innerText = 'Result: ' + result;
                    } catch (error) {
                        console.error('Error:', error);
                    }
                }
                </script>
            </body>
            </html>
        `)
        
        run()
    }

# Ring functions called from JavaScript
func handleGreeting(id, req)
    # req is a JSON string: ["World"]
    see "Greeting requested: " + req + nl
    
    # Send response back to JavaScript
    oWebView.wreturn(id, WEBVIEW_ERROR_OK, '"Hello from Ring!"')

func doMath(id, req)
    # Parse arguments from JSON
    aArgs = json_decode(req)  # Expected format: [5, 3, "add"]
    n1 = number(aArgs[1])
    n2 = number(aArgs[2])
    operation = aArgs[3]
    
    switch operation
    on "add"
        result = n1 + n2
    on "subtract"
        result = n1 - n2
    on "multiply"
        result = n1 * n2
    on "divide"
        result = n1 / n2
    off
    
    oWebView.wreturn(id, WEBVIEW_ERROR_OK, string(result))
```

--------------------------------

### Bind Multiple Functions using bindMany

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Shows how to use the bindMany method to bind multiple functions or methods at once. This can be done using a global binding list or by manually providing the list. It simplifies the binding process for multiple callbacks.

```Ring
# Global binding list (automatically used if it exists)
aBindList = [
    ["simpleFunc", :simpleFunction],
    [oMyObject, [
        ["objMethod1", :method1],
        ["objMethod2", :method2]
    ]]
]

# Or bind manually
oWebView.bindMany(aBindList)
```

--------------------------------

### Loading HTML Content in Ring WebView

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Demonstrates setting HTML content directly within the Ring code for the WebView. It also covers loading HTML from local files by reading the file content first. Requires an initialized WebView object.

```ring
oWebView.setHtml(`
    <!DOCTYPE html>
    <html>
    <head><title>My App</title></head>
    <body>
        <h1>Welcome to Ring WebView</h1>
        <p>This content is generated by Ring!</p>
    </body>
    </html>
`)
```

```ring
# Load HTML content from file
htmlContent = read("assets/index.html")
oWebView.setHtml(htmlContent)
```

--------------------------------

### Thread-Safe UI Updates in Ring

Source: https://context7.com/ysdragon/webview/llms.txt

Illustrates how to perform thread-safe UI updates from background threads using the Ring programming language. It uses the `dispatch` function to queue UI operations onto the main thread, preventing race conditions and ensuring stability. The example includes a progress bar updated by a background task.

```ring
load "webview.ring"
load "ringthreads.ring"

oWebView = NULL
nProgress = 0

func main()
    oWebView = new WebView()

    oWebView {
        setTitle("Thread Dispatch Demo")
        setSize(600, 400, WEBVIEW_HINT_NONE)

        bind("startBackgroundTask", :startTask)

        setHtml(`
            <!DOCTYPE html>
            <html>
            <body>
                <h1>Background Task Demo</h1>
                <button onclick="window.startBackgroundTask()">Start Task</button>
                <div id="progress">0%</div>
                <div id="status">Ready</div>
                <script>
                    function updateProgress(percent) {
                        document.getElementById('progress').innerText = percent + '%';
                    }

                    function setStatus(message) {
                        document.getElementById('status').innerText = message;
                    }
                </script>
            </body>
            </html>
        `)

        run()
    }

func startTask(id, req)
    oWebView.wreturn(id, WEBVIEW_ERROR_OK, '{}')

    # Start background task
    new Thread() {
        for i = 1 to 100
            nProgress = i
            # Use dispatch to safely update UI from thread
            oWebView.dispatch("updateUIFromThread()")
            sleep(0.05)
        next
        oWebView.dispatch("taskCompleted()")
    }.start()

func updateUIFromThread()
    # This runs on the main thread
    oWebView.evalJS("updateProgress(" + nProgress + ");")

func taskCompleted()
    oWebView.evalJS("setStatus('Task completed!');")

```

--------------------------------

### Load Users into WebView

Source: https://context7.com/ysdragon/webview/llms.txt

This JavaScript function fetches the list of users from the backend and updates the HTML to display them. It makes a request to get the user list, parses the JSON response, generates HTML for the user list, and updates the 'userList' element in the DOM. It includes error handling for fetching users.

```javascript
function loadUsers() {
    fetch('/getUserList')
        .then(response => response.json())
        .then(data => {
            let html = '';
            if (data.length > 0) {
                html = '<ul>';
                data.forEach(user => {
                    html += `<li>${user.name} (${user.age}) - ${user.country}</li>`;
                });
                html += '</ul>';
            }
            document.getElementById('userList').innerHTML = html || '<p>No users registered yet</p>';
        })
        .catch(error => {
            console.error('Error loading users:', error);
        });
}

window.onload = loadUsers;

```

--------------------------------

### Display Native Window Handles

Source: https://context7.com/ysdragon/webview/llms.txt

This Ring code demonstrates how to get and display various native window handles using the WebView library. It binds a JavaScript function to a Ring callback, and within the callback, retrieves handles for the main window, UI window, UI widget, and browser controller, then displays them in the WebView.

```ring
oWebView = new WebView()

oWebView {
    setTitle("Native Handle Demo")
    setSize(500, 300, WEBVIEW_HINT_NONE)

    bind("showHandles", :displayHandles)

    setHtml(`
        <!DOCTYPE html>
        <html>
        <body>
            <h1>Native Handles Demo</h1>
            <button onclick="window.showHandles()">Show Native Handles</button>
            <pre id="output"></pre>
        </body>
        </html>
    `)

    run()
}

func displayHandles(id, req)
    # Get native window handle
    windowHandle = oWebView.getWindow()

    # Get specific native handles by kind
    uiWindow = oWebView.getNativeHandle(WEBVIEW_NATIVE_HANDLE_KIND_UI_WINDOW)
    uiWidget = oWebView.getNativeHandle(WEBVIEW_NATIVE_HANDLE_KIND_UI_WIDGET)
    browserCtrl = oWebView.getNativeHandle(WEBVIEW_NATIVE_HANDLE_KIND_BROWSER_CONTROLLER)

    output = "Window Handle: " + windowHandle + "\n"
    output += "UI Window Handle: " + uiWindow + "\n"
    output += "UI Widget Handle: " + uiWidget + "\n"
    output += "Browser Controller Handle: " + browserCtrl + "\n"

    see output

    # Display in webview
    jsCode = "document.getElementById('output').innerText = `" + output + "`;"
    oWebView.evalJS(jsCode)

    oWebView.wreturn(id, WEBVIEW_ERROR_OK, '{}')

```

--------------------------------

### WebView Class Initialization

Source: https://github.com/ysdragon/webview/blob/main/docs/REFERENCE.md

Describes how to initialize a WebView instance using global configuration.

```APIDOC
## WebView Class Initialization

### Description
Initializes a new `WebView` instance. Configuration is managed through a global list `aWebViewConfig` before instantiation.

### Method
`new WebView()`

### Endpoint
N/A (Class Constructor)

### Parameters
#### Global Configuration (before calling `new WebView()`)
- **`aWebViewConfig[:debug]`** (Boolean) - Optional - Set to `true` to enable debug mode. Defaults to `true`.
- **`aWebViewConfig[:window]`** (Pointer) - Optional - A native window handle to use as the parent. Defaults to `NULL`.

### Request Example
```lua
-- Example of setting global configuration before creating a WebView instance
aWebViewConfig = {
    debug = true,
    window = NULL
}

-- Create a new WebView instance
local wv = WebView()
```

### Response
#### Success Response
- **`wv`** (WebView Instance) - A newly created and initialized WebView object.

#### Response Example
```lua
-- Assuming wv is a valid WebView instance
print(type(wv))
-- Expected output: userdata
```

### Notes
- The `init()` method is called automatically upon instantiation.
- If `aBindList` exists and is a valid list, its bindings are automatically registered during initialization.
```

--------------------------------

### Configure and Build WebView with CMake

Source: https://github.com/ysdragon/webview/blob/main/README.md

Configures and builds the WebView project using CMake. This involves creating a build directory, navigating into it, running CMake to configure the build, and then executing the build command.

```sh
mkdir build
cd build
cmake ..
cmake --build .
```

--------------------------------

### WebView Event Loop and Lifecycle

Source: https://github.com/ysdragon/webview/blob/main/docs/REFERENCE.md

Covers the methods for running the event loop, terminating the loop, and destroying the webview instance.

```APIDOC
## WebView Event Loop and Lifecycle

### Description
Manages the operational lifecycle of the WebView, including running the event loop, programmatically terminating it, and releasing resources.

### Methods
#### `run()`
- **Description**: Starts the main event loop for the webview. This is a blocking call that executes until the webview window is closed. It automatically calls `destroy()` upon completion.
- **Endpoint**: N/A (Instance Method)

#### `destroy()`
- **Description**: Cleans up and releases all resources associated with the WebView instance. The instance becomes unusable after this call.
- **Endpoint**: N/A (Instance Method)

#### `terminate()`
- **Description**: Gracefully stops the webview event loop and closes the associated window. Allows for programmatic closing of the webview.
- **Endpoint**: N/A (Instance Method)

### Request Example
```lua
-- Assuming wv is a valid WebView instance

-- To run the event loop (blocking)
wv:run()

-- To programmatically terminate the loop and close the window
wv:terminate()

-- To explicitly destroy the instance (usually called automatically by run() or upon script end)
wv:destroy()
```

### Response
- **`run()`**: Returns when the webview is closed.
- **`destroy()`**: No direct return value; invalidates the instance.
- **`terminate()`**: No direct return value; initiates closure.
```

--------------------------------

### WebView Instance Methods

Source: https://github.com/ysdragon/webview/blob/main/docs/REFERENCE.md

Methods available on a WebView instance for interacting with the underlying webview components and managing state.

```APIDOC
## `getNativeHandle(kind)`

### Description
Returns a native handle of a specific kind, providing more granular access to the underlying webview components.

### Method
GET (Conceptual)

### Endpoint
N/A (Method on an instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const windowHandle = webview.getNativeHandle(WEBVIEW_NATIVE_HANDLE_KIND_UI_WINDOW);
```

### Response
#### Success Response (200)
- **handle** (any) - A native handle object or pointer specific to the kind requested.

#### Response Example
(Depends on the 'kind' requested, will be a platform-specific handle)
```

```APIDOC
## `wreturn(id, result, json)`

### Description
Returns a result back to a JavaScript function that initiated a `bind()` call. This allows Ring to send data or acknowledge completion to the JavaScript frontend.

### Method
POST (Conceptual)

### Endpoint
N/A (Method on an instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **id** (Number) - Required - The callback ID received from the `bind()` call (first argument to the Ring function).
- **result** (Number) - Required - The status code for the operation. Use `WEBVIEW_ERROR_OK` for success. Other `WEBVIEW_ERROR_` constants can indicate specific issues.
- **json** (String) - Required - A JSON string containing the data to return to JavaScript. This will be the resolved value of the JavaScript `Promise`.

### Request Example
```javascript
webview.wreturn(callbackId, WEBVIEW_ERROR_OK, JSON.stringify({ message: 'Operation successful' }));
```

### Response
#### Success Response (200)
- **status** (String) - 'ok' or 'error' indicating if the return operation was processed.

#### Response Example
```json
{
  "status": "ok"
}
```
```

```APIDOC
## `isDestroyed()`

### Description
Checks if the webview instance has already been destroyed and its resources released.

### Method
GET (Conceptual)

### Endpoint
N/A (Method on an instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const destroyed = webview.isDestroyed();
console.log('Webview destroyed:', destroyed);
```

### Response
#### Success Response (200)
- **isDestroyed** (Boolean) - `true` if the webview has been destroyed, `false` otherwise.

#### Response Example
```json
{
  "isDestroyed": false
}
```
```

--------------------------------

### Enable WebView Debug Mode - Ring

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Sets a global configuration variable to enable debug mode for the WebView. This is useful for troubleshooting and obtaining detailed logging information.

```Ring
aWebViewConfig[:debug] = true

```

--------------------------------

### Initialize WebView Instance with Ring

Source: https://context7.com/ysdragon/webview/llms.txt

Initializes a webview window using the Ring programming language. It allows for custom configuration settings and defines the window's title, size, and initial HTML content. The application then enters a run loop until the window is closed.

```ring
load "webview.ring"

# Optional: Configure global settings before creating instance
aWebViewConfig = [
    :debug = true,      # Enable debug mode for development
    :window = NULL      # Use NULL to create a new window
]

# Create webview instance
oWebView = new WebView()

oWebView {
    setTitle("My Application")
    setSize(800, 600, WEBVIEW_HINT_NONE)
    setHtml(`
        <!DOCTYPE html>
        <html>
        <head>
            <meta charset="UTF-8">
            <title>Ring WebView App</title>
        </head>
        <body>
            <h1>Hello from Ring WebView!</h1>
            <button onclick="alert('Button clicked!')">Click Me</button>
        </body>
        </html>
    `)
    run()
}

see "Application closed." + nl

```

--------------------------------

### Set RING Environment Variable

Source: https://github.com/ysdragon/webview/blob/main/README.md

Sets the RING environment variable, which is necessary for CMake configuration. This variable should point to the root directory of the Ring language source code. Examples are provided for Windows (Command Prompt and PowerShell) and Unix-like systems.

```cmd
set RING=X:\path\to\ring
```

```powershell
$env:RING = "X:\path\to\ring"
```

```sh
export RING=/path/to/ring
```

--------------------------------

### Bind Anonymous Function to WebView

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Demonstrates binding an anonymous function directly to the WebView with the name 'showAlert'. This function logs a message and returns a string response to the caller. It requires the WebView object and uses the 'req' parameter for input.

```Ring
# Bind an anonymous function
oWebView.bind("showAlert", func (id, req) {
    see "Anonymous function called: " + req + nl
    oWebView.wreturn(id, WEBVIEW_ERROR_OK, '"Message received!"')
})
```

--------------------------------

### Ring Programming Language Introduction

Source: https://github.com/ysdragon/webview/blob/main/examples/assets/index.html

This section provides an overview of the Ring programming language, highlighting its design goals of simplicity and flexibility. It details key features such as its natural syntax, cross-platform compatibility, support for multiple programming paradigms, and ease of integration with other languages.

```markdown
Ring Programming Language
=========================

Simple, flexible, and natural programming for everyone

What is Ring?
-------------

**Ring** is a dynamic and innovative programming language designed for simplicity, productivity, and natural coding. It is ideal for beginners and professionals alike, supporting a wide range of applications from desktop and web to mobile and embedded systems.

Key Features
------------

*   Simple and expressive syntax
*   Natural language programming style
*   Powerful standard library
*   Cross-platform: Windows, Linux, macOS, Android, WebAssembly
*   Supports procedural, object-oriented, functional, and declarative programming
*   Easy integration with C/C++ and other languages
*   Great for rapid application development
```

--------------------------------

### WebView UI Manipulation

Source: https://github.com/ysdragon/webview/blob/main/docs/REFERENCE.md

Methods for setting the window title, size, and navigating to specific URLs or HTML content.

```APIDOC
## WebView UI Manipulation

### Description
Provides methods to control the appearance and content of the WebView window, including its title, dimensions, and loaded content.

### Methods
#### `setTitle(title)`
- **Description**: Sets the text displayed in the title bar of the webview window.
- **Parameters**:
    - **`title`** (String) - Required - The desired title for the window.
- **Endpoint**: N/A (Instance Method)

#### `setSize(width, height, hint)`
- **Description**: Adjusts the dimensions of the webview window.
- **Parameters**:
    - **`width`** (Number) - Required - The desired width of the window.
    - **`height`** (Number) - Required - The desired height of the window.
    - **`hint`** (Constant) - Required - A hint value controlling resizing behavior (refer to 'Size Hints' documentation).
- **Endpoint**: N/A (Instance Method)

#### `navigate(url)`
- **Description**: Loads and displays the web content from a specified URL.
- **Parameters**:
    - **`url`** (String) - Required - The complete URL of the resource to load.
- **Endpoint**: N/A (Instance Method)

#### `setHtml(html)`
- **Description**: Sets the content of the webview directly using an HTML string.
- **Parameters**:
    - **`html`** (String) - Required - The HTML markup to render within the webview.
- **Endpoint**: N/A (Instance Method)

### Request Example
```lua
-- Assuming wv is a valid WebView instance

-- Set the window title
wv:setTitle("My Ring App")

-- Set the window size
wv:setSize(800, 600, 1) -- Assuming 1 is a valid hint constant

-- Navigate to a URL
wv:navigate("https://www.example.com")

-- Set HTML content directly
wv:setHtml("<h1>Hello from Ring WebView!</h1>")
```

### Response
These methods typically do not return specific values but modify the state of the WebView instance.
```

--------------------------------

### Get WebView Library Version Information

Source: https://context7.com/ysdragon/webview/llms.txt

This code snippet demonstrates how to retrieve and display the version information of the Ring WebView library. It calls functions like webview_version() and accesses constants like WEBVIEW_VERSION_MAJOR to show the major, minor, and patch versions.

```ring
load "webview.ring"

# Get WebView library version
see "WebView Library Version: " + webview_version() + nl
see "Version Major: " + WEBVIEW_VERSION_MAJOR + nl
see "Version Minor: " + WEBVIEW_VERSION_MINOR + nl
see "Version Patch: " + WEBVIEW_VERSION_PATCH + nl

```

--------------------------------

### CMake: Post-Build Command for Library Relocation

Source: https://github.com/ysdragon/webview/blob/main/CMakeLists.txt

Configures a post-build command for the `ring_webview` target. This command ensures the compiled library is moved to a platform-specific output directory (e.g., `lib/macos/amd64`). It creates the destination directory if it doesn't exist and then renames the built library file to its final location.

```cmake
# Set the destination directory for the built library
set(LIB_DEST_DIR "${CMAKE_CURRENT_SOURCE_DIR}/lib/${OS_DIR}/${ARCH_DIR}")

# Move built library to lib directory
add_custom_command(
	TARGET ring_webview
	POST_BUILD
	COMMAND ${CMAKE_COMMAND} -E make_directory ${LIB_DEST_DIR}
	COMMAND ${CMAKE_COMMAND} -E rename $<TARGET_FILE:ring_webview> ${LIB_DEST_DIR}/$<TARGET_FILE_NAME:ring_webview>
	COMMENT "Moving built library to ${LIB_DEST_DIR}"
	VERBATIM
)

```

--------------------------------

### Bind Counter Methods to WebView

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Binds increment, decrement, and getValue methods of a Counter class to the WebView. The Counter class manages an internal value and communicates updates back to the WebView using wreturn. Dependencies include the Counter class and the WebView object.

```Ring
oCounter = new Counter()
oWebView.bind(oCounter, [
    ["increment", :increment],
    ["decrement", :decrement],
    ["getValue", :getValue]
])

class Counter
    value = 0
    
    func increment(id, req)
        self.value++
        oWebView.wreturn(id, WEBVIEW_ERROR_OK, string(self.value))
    
    func decrement(id, req)
        self.value--
        oWebView.wreturn(id, WEBVIEW_ERROR_OK, string(self.value))
    
    func getValue(id, req)
        oWebView.wreturn(id, WEBVIEW_ERROR_OK, string(self.value))

```

--------------------------------

### CMake: Configure Ring Project and Dependencies

Source: https://github.com/ysdragon/webview/blob/main/CMakeLists.txt

Sets up the CMake project, finds the Ring language dependency, and fetches the webview library if not found locally. It determines the Ring project root and includes necessary header files. The script handles platform differences for linking the Ring library (e.g., ringstatic on Windows).

```cmake
cmake_minimum_required(VERSION 3.16)
project(RingWebView)

include(FetchContent)

set(RING_ROOT_DEFAULT "${CMAKE_CURRENT_SOURCE_DIR}/../..")
if(DEFINED ENV{RING})
    set(RING_ROOT_DEFAULT "$ENV{RING}")
endif()
set(RING_ROOT "${RING_ROOT_DEFAULT}" CACHE PATH "Path to the Ring project root directory.")
message(STATUS "Using Ring from: ${RING_ROOT}")

if(NOT TARGET Ring::Ring)
    add_library(Ring::Ring UNKNOWN IMPORTED)
    find_path(RING_INCLUDE_DIR ring.h PATHS "${RING_ROOT}/language/include")

    # Check if RING_STATE_VERSION is "1.23" to use ringstatic for Windows
    if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
        file(STRINGS "${RING_INCLUDE_DIR}/state.h" RING_STATE_VERSION_LINE REGEX "RING_STATE_VERSION")
        if(RING_STATE_VERSION_LINE MATCHES \"1\.23\")
            find_library(RING_LIBRARY_PATH NAMES ringstatic PATHS "${RING_ROOT}/lib")
        else()
            find_library(RING_LIBRARY_PATH NAMES ring PATHS "${RING_ROOT}/lib")
        endif()
    else()
        find_library(RING_LIBRARY_PATH NAMES ring PATHS "${RING_ROOT}/lib")
    endif()

    if(NOT RING_INCLUDE_DIR OR NOT RING_LIBRARY_PATH)
        message(FATAL_ERROR "Could not find Ring headers or library in ${RING_ROOT}. "
                            "Please set the RING_ROOT cache variable correctly.")
    endif()

    set_target_properties(Ring::Ring PROPERTIES
        IMPORTED_LOCATION "${RING_LIBRARY_PATH}"
        INTERFACE_INCLUDE_DIRECTORIES "${RING_INCLUDE_DIR}"
    )
endif()

# Set paths
set(RING_INCLUDE "${RING_ROOT}/language/include")
set(RING_LIB "${RING_ROOT}/lib")
set(RING_BIN "${RING_ROOT}/bin")

set(RING_WEBVIEW_C_SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/src/ring_webview.c")

# Determine OS and Architecture specific paths
string(TOLOWER "${CMAKE_SYSTEM_NAME}" OS_DIR)
if(OS_DIR STREQUAL "darwin")
    set(OS_DIR "macos")
endif()

string(TOLOWER "${CMAKE_SYSTEM_PROCESSOR}" ARCH_DIR_RAW)

if(CMAKE_SYSTEM_NAME STREQUAL "Windows" AND DEFINED CMAKE_GENERATOR_PLATFORM)
    if(CMAKE_GENERATOR_PLATFORM STREQUAL "Win32")
        set(ARCH_DIR_RAW "i386")
    elseif(CMAKE_GENERATOR_PLATFORM STREQUAL "x64")
        set(ARCH_DIR_RAW "amd64")
    elseif(CMAKE_GENERATOR_PLATFORM STREQUAL "ARM64")
        set(ARCH_DIR_RAW "arm64")
    else()
        message(WARNING "Unsupported CMAKE_GENERATOR_PLATFORM: ${CMAKE_GENERATOR_PLATFORM}, falling back to CMAKE_SYSTEM_PROCESSOR")
    endif()
endif()

if(NOT DEFINED ARCH_DIR)
    if(ARCH_DIR_RAW MATCHES "x86_64|amd64")
        set(ARCH_DIR "amd64")
    elseif(ARCH_DIR_RAW MATCHES "aarch64|arm64")
        set(ARCH_DIR "arm64")
    elseif(ARCH_DIR_RAW MATCHES "riscv64")
        set(ARCH_DIR "riscv64")
    elseif(ARCH_DIR_RAW MATCHES "i386|i686|x8x")
        set(ARCH_DIR "i386")
    else()
        set(ARCH_DIR "${ARCH_DIR_RAW}")
        message(WARNING "Unsupported architecture: ${ARCH_DIR_RAW}. Using as directory name.")
    endif()
endif()

# Set the destination directory for the built library
set(LIB_DEST_DIR "${CMAKE_CURRENT_SOURCE_DIR}/lib/${OS_DIR}/${ARCH_DIR}")

# Configure webview build options
set(WEBVIEW_BUILD_SHARED_LIBRARY OFF)
set(BUILD_TESTING OFF CACHE BOOL "Disable building tests for webview")

# Add webview as a subdirectory to build it
if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/src/webview/CMakeLists.txt")
    message(STATUS "webview source not found, fetching from GitHub...")
    FetchContent_Declare(
        webview
        GIT_REPOSITORY https://github.com/webview/webview.git
        GIT_TAG        master
    )
    FetchContent_MakeAvailable(webview)
else()
    message(STATUS "webview found locally, adding as subdirectory.")
    add_subdirectory(src/webview)
endif()

```

--------------------------------

### Global WebView Functions

Source: https://github.com/ysdragon/webview/blob/main/docs/REFERENCE.md

Functions available globally that do not require a specific WebView instance.

```APIDOC
## `webview_version()`

### Description
Returns a string representing the version of the underlying WebView library.

### Method
GET (Conceptual)

### Endpoint
N/A (Global function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const version = webview_version();
console.log('WebView Version:', version);
```

### Response
#### Success Response (200)
- **version** (String) - The version string of the WebView library (e.g., "0.12.0").

#### Response Example
```json
{
  "version": "0.12.0"
}
```
```

--------------------------------

### Handle JavaScript Calls with Parameters and Return Values

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Explains how Ring functions called from JavaScript receive 'id' and 'req' parameters. 'id' is used for responding, and 'req' contains JSON-encoded arguments. It shows parsing arguments with json_decode and sending responses using wreturn.

```Ring
func myFunction(id, req)
    # Parse JSON arguments
    aArgs = json_decode(req)  # Converts JSON string to Ring list
    
    # Access arguments
    arg1 = aArgs[1]
    arg2 = aArgs[2]
    
    # Process the request...
    
    # Send response back to JavaScript
    oWebView.wreturn(id, WEBVIEW_ERROR_OK, '"Response from Ring"')
```

--------------------------------

### Dispatch Ring Code to Main Thread

Source: https://github.com/ysdragon/webview/blob/main/docs/USAGE.md

Illustrates how to dispatch Ring code execution to the main UI thread using the 'dispatch' method. This is crucial for operations that must occur on the main thread, such as updating UI elements. It involves calling evalJS from a function executed on the main thread.

```Ring
# Dispatch code to main thread
oWebView.dispatch("updateUI()")

func updateUI()
    # This runs on the main thread
    oWebView.evalJS("document.getElementById('counter').innerText = 'Updated';")
```

--------------------------------

### Load HTML Content in WebView using Ring

Source: https://context7.com/ysdragon/webview/llms.txt

Demonstrates various methods for loading HTML content into a webview instance using the Ring programming language. This includes setting HTML directly from a string, navigating to a URL, loading a local HTML file, and reading HTML content from a file before setting it.

```ring
load "webview.ring"

oWebView = new WebView()

# Method 1: Set HTML content directly
oWebView.setHtml(
    "<!DOCTYPE html>\n<html>\n<head><title>Direct HTML</title></head>\n<body>\n    <h1>Content loaded from string</h1>\n    <p>This HTML is embedded in Ring code</p>\n</body>\n</html>"
)

# Method 2: Navigate to a URL
oWebView.navigate("https://www.example.com")

# Method 3: Load local HTML file
oWebView.navigate("file:///path/to/local/index.html")

# Method 4: Read HTML from file and set content
htmlContent = read("assets/index.html")
oWebView.setHtml(htmlContent)

oWebView.run()

```

--------------------------------

### Windows Custom Build Command for ring_webview

Source: https://github.com/ysdragon/webview/blob/main/CMakeLists.txt

This CMake command copies the built 'ring_webview' library to the bin directory when the system is Windows. It ensures the 'bin' directory exists and then performs the copy operation. This is useful for deployment or testing on Windows environments.

```cmake
if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
	add_custom_command(
		TARGET ring_webview
		POST_BUILD
		COMMAND ${CMAKE_COMMAND} -E make_directory ${RING_BIN}
		COMMAND ${CMAKE_COMMAND} -E copy ${LIB_DEST_DIR}/$<TARGET_FILE_NAME:ring_webview> ${RING_BIN}/$<TARGET_FILE_NAME:ring_webview>
		COMMENT "Copying built library to bin directory"
		VERBATIM
	)
endif()
```
Tokens:
Raw