Window | BOSON

Main Window

The Application::$window property provides convenient access to the main window of the application.

$app = new Boson\Application();

// Access the main window
$window = $app->window;

Title

Contains title of the specified window encoded as UTF-8. The window title can be in any language and even include emojis. All line breaks (\n) and similar characters will be removed.

To get the window title, simply read this property. The title will contain the real value, including all invisible (like \n) characters.

$title = $window->title;

echo 'Window Title: ' . $title;

To update the window title, set a new value to the property.

$window->title = 'New Window Title!';

State

Each window has several states. The window can be minimized, maximized to full screen, or in a normal state.

To get the current state of a window, you can use the Window::$state property.

echo 'Window State: ' . $window->state->name;

This property will contain one of the possible values of Boson\Window\WindowState enum.

enum WindowState
{
    /**
     * Standard window state with custom (user defined) sizes.
     */
    case Normal;

    /**
     * Maximized (i.e. zoomed) window state.
     */
    case Maximized;

    /**
     * Minimized (iconified) window state.
     */
    case Minimized;
}

There are corresponding methods for changing states from code.

Minimize

In order to minimize the window, you should use the appropriate Window::minimize() method.

// Minimize window to tray
$window->minimize();

When restoring a window from the tray using the operating system features (for example, Alt + Tab), the previous state will be restored.

Window state is Normal.
Execute $window->minimize()
Restore using OS features (like Alt + Tab).
Window state is again Normal.

Window state is Maximized.
Execute $window->minimize()
Restore using OS features (like Alt + Tab).
Window state is again Maximized.

Maximize

In order to maximize the window, you should use the appropriate Window::maximize() method.

// Maximize window from tray or normal state
$window->maximize();

Restore

In order to restore the window state (that is, switch to a Normal state), you should use the appropriate Window::restore() method.

// Restore window state
$window->restore();

Visibility

The Window::$isVisible property controls the visibility state of the window. It allows you to show or hide the window programmatically.

To check if a window is currently visible:

if ($window->isVisible) {
    echo 'Window is visible';
} else {
    echo 'Window is hidden';
}

Show

To show the window you may use desired Window::show() method.

// Show the window
$window->show();

Hide

To hide the window you may use desired Window::hide() method.

// Hide the window
$window->hide();

Decorations

The Window::$decoration property allows you to control the window's appearance and style.

// Get current decoration mode
echo $window->decoration->name;

It supports different decoration modes defined in the Boson\Window\WindowDecoration enum.

enum WindowDecoration
{
    /**
     * Default window style.
     */
    case Default;

    /**
     * Default window style with preferred dark mode.
     */
    case DarkMode;

    /**
     * A "frameless" windows is a window which hides the default
     * window buttons & handle assigned to it by the operating system.
     */
    case Frameless;

    /**
     * Enables "frameless" mode and makes the window completely transparent
     */
    case Transparent;
}

Let's say we load the content as <div style="background: #fff">Hello World!</div> in webview. So the result with different decorations will look like this.

Default

The standard window style with system default appearance (title bar, close, minimise and maximise buttons).

$window->decoration = WindowDecoration::Default;

Dark Mode

Default window style with dark theme preference.

$window->decoration = WindowDecoration::DarkMode;

Frameless

A frameless window hides the default window decorations (title bar, buttons) provided by the operating system.

$window->decoration = WindowDecoration::Frameless;

Transparent

Enables frameless mode and makes the window background transparent.

$window->decoration = WindowDecoration::Transparent;

Size

The window size can be controlled through several properties that allow you to manage the current size, minimum and maximum bounds of the window.

Current Size

The Window::$size property provides access to the current window dimensions. The object in the window is mutable which allows both reading and updating the size.

// Get current size
echo $window->size; // Size(640 × 480)

// Update width and height separately
$window->size->width  = 800;
$window->size->height = 600;

// Update both dimensions simultaneously
$window->size->update(800, 600);

// Set size using Size object
$window->size = new Boson\Window\Size(800, 600);

Minimum Size

The Window::$min property controls the minimum allowed dimensions of the window. Users cannot resize the window smaller than these values.

// Get minimum size
echo $window->min; // Size(0 × 0)

// Set minimum size separately
$window->min->width  = 400;
$window->min->height = 300;

// Or update all dimensions at once
$window->min->update(400, 300);

Maximum Size

The Window::$max property controls the maximum allowed dimensions of the window. Users cannot resize the window larger than these values.

// Get maximum size
echo $window->max; // Size(3840 × 2160)

// Set maximum size
$window->max->width  = 1920;
$window->max->height = 1080;

// Or update both at once
$window->max->update(1920, 1080);

Resizing

The Window::startResize() method allows you to programmatically start resizing the window. This is particularly useful for frameless windows where you need to implement custom window controls.

The method takes one of the available arguments:

Boson\Window\WindowCorner - window corner.
Boson\Window\WindowEdge - window edge.

// Start resizing the window on the right side
$window->startResize(Boson\Window\WindowEdge::Right);

// Start resizing the window on the bottom-left side
$window->startResize(Boson\Window\WindowCorner::BottomLeft);

$app = new Boson\Application();

$app->webview->functions->bind('resize', function () use ($app) {
    $app->window->startResize(
        Boson\Window\WindowCorner::BottomRight,
    );
});

$app->webview->html = <<<'HTML'
    <div onmousedown="resize()">
        Press + hold to resize the window!
    </div>
    HTML;

Resize via HTML

You can also use the data-webview-resize HTML attribute to implement the window resize functionality.

Possible values for window edges:

t - Top resize edge handle.
b - Bottom resize edge handle.
l - Left resize edge handle.
r - Right resize edge handle.

Possible values for window corners:

tr - Top-Right resize corner handle.
br - Bottom-Right resize corner handle.
bl - Bottom-Left resize corner handle.
tl - Top-Left resize corner handle.

<button data-webview-resize="t">    ↑   </button>
<button data-webview-resize="l">    ←   </button>
<button data-webview-resize="tr">   ↗   </button>
<button data-webview-resize="bl">   ↙   </button>

Dragging

The Window::startDrag() method allows you to programmatically start dragging the window. This is particularly useful for frameless windows where you need to implement custom window controls.

// Start dragging the window
$window->startDrag();

$app = new Boson\Application();

$app->webview->functions->bind('drag', function () use ($app) {
    $app->window->startDrag();
});

$app->webview->html = <<<'HTML'
    <div onmousedown="drag()">
        Press + hold to drag the window!
    </div>
    HTML;

Drag via HTML

You can also use the data-webview-drag HTML attribute to make specific elements draggable.

<header data-webview-drag>
    <span>Custom Title Bar</span>
</header>

Focus

Windows can be given input focus and brought to the front with Window::focus() method.

// Focus the window
$window->focus();

Always On Top

The Window::$isAlwaysOnTop property allows you to control whether a window should stay on top of other windows. When enabled, the window will remain visible even when other windows are in focus.

// Check if window is always on top
if ($window->isAlwaysOnTop) {
    echo 'Window is always on top';
} else {
    echo 'Window is not always on top';
}

// Enable always on top
$window->isAlwaysOnTop = true;

// Disable always on top
$window->isAlwaysOnTop = false;

Click Through

The Window::$isClickThrough property allows you to control whether a window should intercept mouse events. When enabled, mouse clicks will pass through the window to the windows or applications behind it.

// Check if window is click-through
if ($window->isClickThrough) {
    echo 'Window does not intercept mouse events';
} else {
    echo 'Window intercepts mouse events';
}

// Enable click-through feature
$window->isClickThrough = true;

// Disable click-through feature
$window->isClickThrough = false;

When "click-through" is enabled:

The window cannot be moved, resized, or focused by clicking.
All mouse events will be ignored.
The window will effectively become a visual overlay only.

Window Close

The Window::close() method allows you to close and destroy a window and its associated resources. This operation is irreversible - once a window is closed, it cannot be reopened.

// Close the window
$window->close();

You can check if a window is closed using the $isClosed property:

if ($window->isClosed) {
    echo 'Window is already closed';
} else {
    $window->close();
}

Identifier

The Boson\Window\WindowId is a unique identifier for each window in the application. The identifier is needed to compare different windows for their equivalence.

To get window identifier use the Window::$id property.

$app = new Boson\Application();

echo 'ID: ' . $app->window->id;

An identifier is a value object and contains methods for comparison and conversion to scalars.

if ($window1->id->equals($window2->id)) {
    echo sprintf('The %s is equals to %s', $window1, $window2);
}

The identifier consists of two parts:

A unique integer value that identifies the window in the application.
A pointer to the native window handle.

In addition to the ability to convert to a string (i.e. implementations of the Stringable interface), this identifier can also be converted to an 64-bit (or 32-bit on 32-bit OS) signed integer, which represents the actual physical address of the window pointer.

echo $window->id->toInteger();