max1220 Window Manager Library - Documentation

A simple Window management library for the web.
Implemented using Vanilla JavaScript, HTML5, and CSS3.

Usage

To use the max1220 JavaScript Window manager library, simply instantiate a new WindowManager object, pass the required parameters, and register required event handlers:

let wm = new WindowManager(window_container, window_template, log_enable);
wm.register_mouse_events(window)
wm.register_message_events()

The library allows you to manage multiple windows and provides callbacks to handle various window events.

You can create a new window by calling the add_window method with a URL to load the content into an iframe. This also supports passing arguments to the window client:

wm.add_window("window.html", { my_arg: "hello world!" })

See also the section below about the WindowClient, which makes some functionality of the window manager available to the document inside the iframe.

HTML setup

In order to use this library, you need to load the stylesheet for the window decorations, and create a template HTML element.

<link rel="stylesheet" href="window_common.css">
<link rel="stylesheet" href="window_flat.css"> <!-- Theme -->

<template id="window_template">
	<div class="win">
		<nav class="win-titlebar win-drag-handle">
			<span class="win-icon">🗔</span>
			<span class="win-title win-drag-handle">Unnamed window</span>
			<button class="win-btn win-btn-minimize" onclick="wm.minimize_window(this.closest('.win'))" title="Minimize">▁</button>
			<button class="win-btn win-btn-restore hidden" onclick="wm.restore_window(this.closest('.win'))" title="Restore">🗗</button>
			<button class="win-btn win-btn-maximize" onclick="wm.maximize_window(this.closest('.win'))" title="Maximize">🗖</button>
			<button class="win-btn win-btn-close" onclick="wm.remove_window(this.closest('.win'))" title="Close">🞮</button>
		</nav>
		<iframe class="win-iframe"></iframe>
		<div class="win-resize-handle"></div>
	</div>
</template>

Mouse events and iframes

Due to how mouse events and iframes work together(or rather don't), only the currently focused window can receive mouse events. This explains why the first click on a window will focus it, but not send a click event to the iframe. Because iframes eat mouse events it is also necessary to disable mouse input during window moving/resizing.
This is done in JavaScript by setting the element pointer-events CSS attribute during moving, resizing, and during focus changes.

`WindowManager` Constructor

The WindowManager class manages the creation, interaction, and lifecycle of application windows.
It supports dragging, resizing, minimizing/unminimizing, maximizing/restoring, and postMessage()-based interaction between window clients and window manager.

`WindowManager(window_container, window_template, log_enable)`

window_container - The container element in which all windows will be placed.
window_template - A template element that defines the structure of a window.
log_enable - A boolean flag to enable or disable logging for debugging purposes.

Properties

window_list - An array that holds all the window elements managed by the WindowManager.
callbacks - An object containing the callback functions for different window events (e.g., win_add, win_remove).
resize_size_limits - Defines the minimum width and height for resizing windows.
create_size_limits - Defines the minimum and maximum size limits for newly created windows.
place - The next position where a new window will be placed.

Methods

register_mouse_events(elem)

Start listening for mouse events from elem that can move or resize windows.
Typically elem is simply the global window object(register_mouse_events(window)).
Call this function at load to enable movement and resizing of windows.
register_message_events()

Start listening for message events, triggered by the WindowClient inside the window iframes.
Call this function at load to enable child windows to control themselves and create other windows.
add_window(url, window_arg)

Creates a new window with content loaded from the specified URL.
window_arg is transferred to the iframe via postMessage.
focus_window(win_elem)

Focuses the specified window, bringing it to the front of the window stack and making it possible for this window to receive mouse events.
See note on iframes and mouse input.
minimize_window(win_elem)

Minimizes (hides) the specified window.
unminimize_window(win_elem)

Unminimizes (shows) the specified window.
maximize_window(win_elem)

Maximizes the specified window, making it fill the entire container.
restore_window(win_elem)

Restores a maximized window to its original size and position after being maximized.
remove_window(win_elem, force)

Removes the specified window from the container.
If the window requires confirmation to close, it will ask for it using postMessage unless force is set to true.

Callbacks

win_add(win_elem) - Triggered when a new window is added.
win_remove(win_elem) - Triggered when a window is removed.
win_focus(win_elem) - Triggered when a window is focused.
win_minimize(win_elem) - Triggered when a window is minimized.
win_unminimize(win_elem) - Triggered when a window is unminimized.
win_maximize(win_elem) - Triggered when a window is maximized.
win_restore(win_elem) - Triggered when a window is restored from maximized state.
win_resize(resize_state) - Triggered during the resizing of a window.
win_move(drag_state) - Triggered during the dragging/moving of a window.
win_onload(win_elem) - Triggered when the window iframe is loaded
win_message(message_arg) - Triggered when the window manager gets a message from a window client. If this returns truethy the default message handler is not called.
wm_has_maximized(has_maximized) - Triggered when the window manager gets at least one maximized window, or looses all it's maximized windows.

Supported Classes

These classes are to be used in the window_template, and are automatically setup with the correct functionality as aproriate.

.win - The main class for a window element.
.win-titlebar - The class for the titlebar, used for double-click maximization.
.win-title - The class for the window title text. Automatically set from iframe document title if possible.
.win-drag-handle - The class for elements that handle window dragging.
.win-resize-handle - The class for elements that handle window resizing.
.win-btn-minimize - The class for the minimize button.
.win-btn-maximize - The class for the maximize button.
.win-btn-restore - The class for the restore button.
.win-btn-close - The class for the close button.
.win-icon - The class for the window icon. Will be replaced with an img containing the favicon of the window if possible.
.win-iframe - The class for the window iframe where the content is loaded.

Additionally the window_container gets the has-maximized class if a window in it is maximized.

Window state classes

These classes are added/removed from a window as it's state changes.

.focused - Applied to a window when it is focused (active) by the user.
.disabled - Applied to a window when it is not interactable(e.g. waiting for a dialog box)
.minimized - Applied to a window when it is minimized(hidden).
.maximized - Applied to a window when it is maximized(fills entire window).
.fixed-size - Applied to a window when it is not resizeable.
.fixed-position - Applied to a window when it is not moveable.
.close-confirm - Applied to a window when closing it requires a confirmation from the window(e.g. to ask for unsaved changes).

Supported attributes

These attributes can be directly applied to the window element.

data-min-w - Minimum width of a resizeable window
data-min-h - Minimum height of a resizeable window
data-max-w - Maximum width of a resizeable window
data-max-h - Maximum height of a resizeable window

`WindowClient` Constructor

The WindowClient is a simple library for use inside a window's iframe document.
It enables the window to perform certain window operations on itself(close, focus, maximize, etc.), and enables a window to open other windows, optionally as dialogs with return values that block the input to the host window.

`WindowClient(wm_window)`

wm_window - Parent window element to post messages to(typically window.parent).

Properties

window_arg - The argument passed to add_window when creating this window.
callbacks - An object containing the callback functions for different window events (e.g., win_add, win_remove).

Methods

add_window(url,arg)

Add a window to the parent's window manager.
close(force)

Close this window. If force is set, don't ask for confirmation.
focus()

Focus this window.
maximize()

Maximize this window.
minimize()

Minimize this window.
unminimize()

Unminimize this window.
restore()

Restore this window
set_fixed_position(is_fixed)

disable/enable dragging of this window.
set_fixed_size(is_fixed)

disable/enable resizing of this window.
set_enabled(is_enabled)

disable/enable mouse input events to this window.
set_confirm(is_enabled)

disable/enable asking for confirmation before closing this window.
set_size(w,h)

Set window size in pixels(sets size of complete window element!).
set_position(x,y)

Set window position in pixels.
set_title(title_text)

Set window title text.
set_icon(icon_url_or_text)

Set window icon. NYI.
add_dialog(url, arg)

Add a dialog window and disable the current window.
return_dialog(arg)

Return a value from a dialog window.
register_message_handler(arg)

Start listening to message events from the parent window manager.

Callbacks

wm_message - Triggered when the client gets any message from the parent window manager
window_arg - Triggered when the client gets it's window arguments
dialog_return - Triggered when a dialog this client opened returned it's value.
close_confirm - Triggered when a window required confirmation before closing. If this callback returns truethy, the window is not closed.

License

The max1220 Window Manager Library is released under the MIT license.
See license.html

max1220 Window Manager Library - Documentation

Usage

HTML setup

Mouse events and iframes

WindowManager Constructor

WindowManager(window_container, window_template, log_enable)

Properties

Methods

register_mouse_events(elem)

register_message_events()

add_window(url, window_arg)

focus_window(win_elem)

minimize_window(win_elem)

unminimize_window(win_elem)

maximize_window(win_elem)

restore_window(win_elem)

remove_window(win_elem, force)

Callbacks

Supported Classes

Window state classes

Supported attributes

WindowClient Constructor

WindowClient(wm_window)

Properties

Methods

add_window(url,arg)

close(force)

focus()

maximize()

minimize()

unminimize()

restore()

set_fixed_position(is_fixed)

set_fixed_size(is_fixed)

set_enabled(is_enabled)

set_confirm(is_enabled)

set_size(w,h)

set_position(x,y)

set_title(title_text)

set_icon(icon_url_or_text)

add_dialog(url, arg)

return_dialog(arg)

register_message_handler(arg)

Callbacks

License

`WindowManager` Constructor

`WindowManager(window_container, window_template, log_enable)`

`register_mouse_events(elem)`

`register_message_events()`

`add_window(url, window_arg)`

`focus_window(win_elem)`

`minimize_window(win_elem)`

`unminimize_window(win_elem)`

`maximize_window(win_elem)`

`restore_window(win_elem)`

`remove_window(win_elem, force)`

`WindowClient` Constructor

`WindowClient(wm_window)`

`add_window(url,arg)`

`close(force)`

`focus()`

`maximize()`

`minimize()`

`unminimize()`

`restore()`

`set_fixed_position(is_fixed)`

`set_fixed_size(is_fixed)`

`set_enabled(is_enabled)`

`set_confirm(is_enabled)`

`set_size(w,h)`

`set_position(x,y)`

`set_title(title_text)`

`set_icon(icon_url_or_text)`

`add_dialog(url, arg)`

`return_dialog(arg)`

`register_message_handler(arg)`