A library for imitating operating system graphical user interfaces on the web
Specifically, Windows 98 — for now at least; it could be expanded in the future.
This library powers 98.js.org, a web-based version of Windows 98, including Paint, Notepad, Sound Recorder, and more.
See the homepage for more information.
Menu bars, with support for checkbox and radio items, disabled states, submenus, keyboard shortcuts, and more
App windows which you can drag around, maximize, minimize, close, and resize
Dialog and tool window variants
Flying titlebar animation that guides your eyes during maximize/minimize/restore
Focus containment: if you Tab or Shift+Tab within a window, it wraps around to the first/last control.
Button styles, including lightweight buttons, disabled buttons, and default action buttons
Scrollbar styles, webkit-specific (in the future there could be a custom scrollbar based on a nonintrusive scrollbar library, or styles supporting a library, where you're expected to use the library directly)
Themeable with Windows .theme & .themepack files at runtime!
This library currently requires jQuery for the windowing implementation. Menu bars do not require jQuery.
(Eventually I want to have no dependencies. So far I've removed jQuery from the menu code...)
The library is not (yet) provided as a single convenient file.
You can either 1. download the repository as a ZIP file, 2. clone the repository, or 3. install the library as an npm package.
You have to include scripts for the components you want to use (MenuBar.js or $Window.js),
along with stylesheets for layout, a theme, and a color scheme.
Make sure to use the compiled CSS files, not the source files.
In <head>:
<link href="os-gui/layout.css" rel="stylesheet" type="text/css">
<link href="os-gui/windows-98.css" rel="stylesheet" type="text/css">
<link href="os-gui/windows-default.css" rel="stylesheet" type="text/css">
In <head> or <body>:
<script src="os-gui/MenuBar.js"></script>
<script src="lib/jquery.js"></script> <!-- required by $Window.js -->
<script src="os-gui/$Window.js"></script>
Note: The API will likely change a lot, but I maintain a Changelog.
.inset-deep creates a 2px inset border.outset-deep creates a 2px inset border (like a button or window or menu popup).inset-shallow creates a 1px inset border.outset-shallow creates a 1px outset borderButton styles are applied to button elements globally.
(And if you ever want to reset it, note that you have to get rid of the pseudo element ::after as well. @TODO: scope CSS)
To make a toggle button, add the .toggle class to the button.
Make it show as pressed with the .selected class. (@TODO: rename this .pressed)
You should use the styles together with semantic aria-pressed, aria-haspopup, and/or aria-expanded attributes as appropriate.
You can show button is the default action by adding .default to the button.
Note that in Windows 98, this style moves from button to button depending on the focus.
A rule of thumb is that it should be on the button that will trigger with Enter.
You can make a lightweight button by adding .lightweight to the button.
Lightweight buttons are subtle and have no border until hover.
You can disable a button by adding the standard disabled attribute to the button.
You can show a button as being pressed by adding the .pressing class to the button.
This is useful for buttons that are triggered by a keystroke.
Scrollbar styles are applied globally, but they have a -webkit- prefix, so they'll only work in "webkit-based" browsers, generally, like Chrome, Safari, and Opera.
(Can be overridden with ::-webkit-scrollbar and related selectors (but not easily reset to the browser default, unless -webkit-appearance: scrollbar works... @TODO: scope CSS)
Selection styles are applied globally.
(Can be overridden with ::selection (but not easily reset to the browser default... unless with unset? @TODO: scope CSS)
MenuBar(menus)Creates a menu bar component.
menus should be an object holding arrays of menu item specifications, keyed by menu button name.
Returns an object with property element, which you should then append to the DOM where you want it.
See examples in the demo code.
elementThe DOM element that represents the menu bar.
closeMenus()Closes any menus that are open.
setKeyboardScope(...eventTargets)Hotkeys like Alt will be handled at the level of the given element(s) or event target(s).
By default, the scope is window (global), for the case of a single-page application where the menu bar is at the top.
If you are putting the menu bar in a window, you should call this with the window's element:
menu_bar.setKeyboardScope($window[0]);
or better yet,
$window.setMenuBar(menu_bar);
which takes care of the keyboard scope for you, while attaching the menu bar to the window.
Note that some keyboard behavior is always handled if the menu bar has focus.
Note also for iframes, you may need to call this with $window[0], iframe.contentWindow currently, but this should be changed in the future (keyboard events should be proxied).
infoCan be used to implement a status bar.
A description is provided as event.detail.description when rolling over menu items that specify a description. For example:
menubar.element.addEventListener("info", (event)=> {
statusBar.textContent = event.detail?.description || "";
});
default-infoSignals that a status bar should be reset to blank or a default message.
menubar.element.addEventListener("default-info", (event)=> {
statusBar.textContent = "";
// or:
statusBar.textContent = "For Help, click Help Topics on the Help Menu.";
// like in MS Paint (and JS Paint)
// or:
statusBar.textContent = "For Help, press F1.";
// like WordPad
// or perhaps even:
statusBar.innerHTML = "For Help, <a href='docs'>click here</a>";
// Note that a link is not a common pattern, and it could only work for the default text;
// for menu item descriptions the message in the status bar is transient, so
// you wouldn't be able to reach it to click on it.
});
Menu item specifications are either MENU_DIVIDER (a constant indicating a horizontal rule), or a radio group specification, or an object with the following properties:
label: a label for the item; ampersands define access keys (to use a literal ampersand, use &&)shortcutLabel (optional): a keyboard shortcut to show for the item, like "Ctrl+A" (Note: you need to listen for the shortcut yourself, unlike access keys)ariaKeyShortcuts (optional): aria-keyshortcuts for the item, like "Control+A Meta+A", for screen readers. "Ctrl" is not valid (you must spell it out), and it's best to provide an alternative for macOS, usually with the equivalent Command key, using "Meta" (and event.metaKey).action (optional): a function to execute when the item is clicked (can only specify either action or checkbox)checkbox (optional): an object specifying that this item should behave as a checkbox.
check of this object should be a function that checks if the item should be checked or not, returning true for checked and false for unchecked. What a cutesy name.toggle should be a function that toggles the state of the option, however you're storing it; called when clicked.enabled (optional): can be false to unconditionally disable the item, or a function that determines whether the item should be enabled, returning true to enable the item, false to disable.submenu (optional): an array of menu item specifications to create a submenudescription (optional): for implementing a status bar; an info event is emitted when rolling over the item with this descriptionvalue (optional): for radio items, the value of the item; can be any type, but === is used to determine whether the item is checked.A radio group specification is an object with the following properties:
radioItems: an array of menu item specifications to create a radio button group. Unlike submenu, the items are included directly in this menu. It is recommended to separate the radio group from other menu items with a MENU_DIVIDER.getValue: a function that should return the value of the selected radio item.setValue: a function that should change the state to the given value, in an application-specific way.ariaLabel (optional): a string to use as the aria-label for the radio group (for screen reader accessibility)Menus can be navigated with contextual hotkeys known as access keys.
Place an ampersand before a letter in a menu button or menu item's label to make it an access key. Microsoft has documentation on access keys, including guidelines for choosing access keys. Generally the first letter is a good choice.
If a menu item doesn't define an access key, the first letter of the label can be used to access it.
For menu buttons, you need to hold Alt when pressing the button's access key, but for menu items in menu popups you must press the key directly, as Alt will close the menus.
If there are multiple menu items with the same access key, it will cycle between them without activating them. You should try to make the access keys unique, including between defined access keys and the first letters of menu items without defined access keys. (This behavior is observed in Windows 98, in Explorer's Favorites menu, where you can make bookmarks with the first letter matching the access keys of other menu items.)
There is an AccessKeys object exported by MenuBar.js, with functions for dealing with access keys:
AccessKeys.escape(label)Escapes ampersands in the given label, so that they are not interpreted as access keys.
This is useful for dynamic menus, like a history menu that uses page titles as labels. You don't want ampersands to be spuriously interpreted as access keys, or double ampersands to be interpreted as a single ampersand.
AccessKeys.unescape(label)Un-escapes all double ampersands in the label.
For rendering, use toHTML or toFragment instead.
AccessKeys.has(label)Returns true if the label has an access key.
AccessKeys.get(label)Returns the access key for the given label, or null if none.
MenuBar handles access keys automatically, but if you're including access keys for other UI elements, you need to handle them yourself, and you can use this rather than hard-coding the access key, so it doesn't need to be changed in two places.
AccessKeys.remove(label)Removes the access key indicator (&) from the label, and un-escapes any double ampersands.
Also removes a parenthetical access key indicator, like " (&N)", as a special case.
AccessKeys.toText(label)Removes the access key indicator (&) from the label, and un-escapes any double ampersands.
This is like toHTML but for plain text.
Note: while often access keys are part of a word, like "&New",
in translations they are often indicated separately, like "새로 만들기 (&N)",
since the access key stays the same, but the letter is no longer part of the word (or even the alphabet).
This function doesn't remove strings like " (&N)", it will remove only the "&" and leave "새로 만들기 (N)".
If you want that behavior, use AccessKeys.remove(label).
AccessKeys.toHTML(label)Returns HTML (with proper escaping) with the access key as a <span class='menu-hotkey'> element.
Security note: It is safe to use the result of this function in HTML element content, as it escapes the label. It is not safe to use in an attribute value, but this is not the intended usage.
Layout note: you may want to surround the result with <span style="white-space: pre"> to prevent whitespace from collapsing if the access key is next to a space.
AccessKeys.toFragment(label)Returns a DocumentFragment with the access key as a <span class='menu-hotkey'> element.
Layout note: you may want to surround the result with <span style="white-space: pre"> to prevent whitespace from collapsing if the access key is next to a space.
$Window(options)Creates a window component that can be dragged around and such, brought to the front when clicked, and closed. Different types of windows can be created with different options. Note that focus wraps within a window's content.
Returns a jQuery object with additional methods and properties (see below, after options).
The DOM node can be accessed with $window.element, and the $Window object can be accessed from the DOM node with with element.$window.
|
|
Returns a jQuery object with additional methods and properties:
title(text)Sets the title, or if text isn't passed, returns the current title of the window.
close()Closes the window.
focus()Tries to focus something within the window, in this order of priority:
class="default"$window.$content)blur()Removes focus from the window. If focus is outside the window, it is left unchanged.
minimize()Minimizes the window. If $window.task.$task is defined it will use that as a target for minimizing, otherwise the window will minimize to the bottom of the screen.
Current behavior is that it toggles minimization. This may change in the future.
maximize()Maximizes the window. While maximized, the window will use position: fixed, so it will not scroll with the page.
Current behavior is that it toggles maximization. This may change in the future. Also, if minimized, it will restore instead of maximizing. Basically, it does what the maximize button does, rather than simply what the method name suggests.
unminimize()PRIVATE: don't use this. Use restore() instead.
Restores the window from minimized state.
restore()Restores the window from minimized or maximized state. If the window is not minimized or maximized, this method does nothing.
center()Centers the window in the page. You should call this after the contents of the window is fully rendered, or you've set a fixed size for the window.
If you have images in the window, wait for them to load before showing and centering the window, or define a fixed size for the images.
applyBounds()Fits the window within the page if it's partially offscreen. (Doesn't resize the window if it's too large; it'll go off the right and bottom of the screen.)
bringTitleBarInBounds()Repositions the window so that the title bar is within the bounds of the page, so it can be dragged.
bringToFront()Brings the window to the front by setting its z-index to larger than any z-index yet used by the windowing system.
setDimensions({ innerWidth, innerHeight, outerWidth, outerHeight })Sets the size of the window. Pass { innerWidth, innerHeight } to specify the size in terms of the window content, or { outerWidth, outerHeight } to specify the size including the window frame.
(This may be expanded in the future to allow setting the position as well...)
setIcons(icons)Changes the icon(s) of the window. icons is in the same format as options.icons.
setTitlebarIconSize(size)Sets the size of the window's title bar icon, picking the closest size that's available.
getTitlebarIconSize()Returns the size of the window's title bar icon.
getIconAtSize(size)Picks the closest icon size that's available, and returns a unique DOM node (i.e. cloned).
This can be used for representing the window in the taskbar.
setMenuBar(menuBar)Appends the menu bar to the window, and sets the keyboard scope for the menu bar's hotkeys to the window.
Can be called with null to remove the menu bar.
setMinimizeTarget(minimizeTargetElement)The minimize target (taskbar button) represents the window when minimized, and is used for animating minimize and restore.
If minimizeTargetElement is null, the window will minimize to the bottom of the screen (the default).
$Button(text, action)Creates a button in the window's content area. It automatically closes the window when clicked. There's no (good) way to prevent this, as it's intended only for dialogs.
If you need any other behavior, just create a <button> and add it to the window's content area.
Returns a jQuery object.
addChildWindow($window)PRIVATE: don't use this.
Defines a window as a child. For tool windows, the focus state will be shared with the parent window.
This is used internally when you set options.parentWindow when creating a window.
onFocus(listener)EXPERIMENTAL: This is a potential new API for events when dependency on jQuery is removed.Not available for all events. Inspired by Webamp's API which is probably inspired by React's API.
Calls the listener when the window is (visually?) focused.
onBlur(listener)EXPERIMENTAL: potential new API for events
Calls the listener when the window (visually?) loses focus.
onClosed(listener)EXPERIMENTAL: potential new API for events
Calls the listener when the window is closed (after the close event is emitted, and if it wasn't prevented).
closedWhether the window has been closed.
iconsThe icons of the window at different sizes, as set by options.icons or setIcons().
$contentjQuery object.
Where you can append contents to the window.
$titlebarjQuery object.
The titlebar of the window, including the title, window buttons, and possibly an icon.
$title_areaPRIVATE: Don't use this. Use $title or $titlebar instead, if possible.
jQuery object.
Wrapper around the title.
$titlejQuery object.
The title portion of the titlebar.
$xjQuery object.
The close button.
$minimizejQuery object.
The minimize button.
$maximizejQuery object.
The maximize button.
$iconPRIVATE: Don't use this.
jQuery object.
The titlebar icon.
elementThe DOM element that represents the window.
closedWhether the window has been closed.
closeCan be used to prevent closing a window, with event.preventDefault().
Since there could be multiple listeners, and another listener could prevent closing, if you want to detect when the window is actually closed, use the closed event.
closedThis event is emitted when the window is closed. It cannot be prevented.
window-drag-startCan be used to prevent dragging a window, with event.preventDefault().
title-changeCan be used to update a taskbar button's label.
icon-changeCan be used to update a taskbar button's icon.
Use $window.getIconAtSize(size) to get an appropriate icon.
Other than center(), there is no API specifically for positioning windows.
You can use $window.css({ top: "500px", left: "500px" }) to set the position of the window. This is a jQuery method.
You can also set position to fixed or absolute to position the window relative to the viewport or the nearest positioned ancestor, respectively.
If you want to position a window relative to another window, you can use $otherWindow.element.getBoundingClientRect() to get the bounding rectangle of the other window, and then use that to position the window. This is a built-in DOM API. For example:
const otherRect = $otherWindow.element.getBoundingClientRect();
$window.css({
top: otherRect.top + "px",
left: (otherRect.right + 10) + "px",
});
!important) to position the window, because the library uses inline styles to position the window, which take precedence.setDimensions() in the future to allow positioning the window in addition to sizing it, or add a setPosition() method.options.constrainRect to dynamically constrain the window position and size during dragging and resizing.parse-theme.js contains functions for parsing and applying themes.
parseThemeFileString(themeString)Parses an INI file string into CSS properties.
Automatically renders dynamic theme graphics, and includes them in the CSS properties.
applyCSSProperties(cssProperties, {element=document.documentElement, recurseIntoIframes=false})cssProperties is an object with CSS properties and values. It can also be a CSSStyleDeclaration object.
element is the element to apply the properties to.
If recurseIntoIframes is true, then the properties will be applied to all <iframe> elements within the element as well.
This only works with same-origin iframes.
renderThemeGraphics(cssProperties)Can be used to update theme graphics (scrollbar icons, etc.) for a specific section of the page. Used by the demo to show variations.
Returns CSS properties representing the rendered theme graphics.
element.style.setProperty('--scrollbar-size', '30px');
applyCSSProperties(renderThemeGraphics(getComputedStyle(element)), { element });
makeThemeCSSFile(cssProperties)Exports a CSS file for a theme. Assumes that the theme graphics are already rendered. Includes a "generated file" comment.
makeBlackToInsetFilter()Initializes an SVG filter that can be used to make icons appear disabled. It may not work with all icons, since it uses the black parts of the image to form a shape.
Usage from CSS:
button:disabled .icon {
filter: saturate(0%) opacity(50%); /* fallback until SVG filter is initialized */
filter: url("#os-gui-black-to-inset-filter");
}
Licensed under the MIT License, see LICENSE for details.
Install Node.js if you don't already have it.
Clone the repository, then in the project directory run npm i to install the dependencies.
Also run npm i when pulling in changes from the repository, in case there are changes to the dependencies.
Run npm start to open a development server. It will open a demo page in your default browser. Changes to the library will be automatically recompiled, and the page will automatically reload.
Run npm run lint to run type checking and spell checking (and any other linting tasks).
Run npm test to run the tests, or npm run coverage to run the tests and generate a coverage report.
It's a good idea to close the server when updating or installing dependencies; otherwise you may run into EPERM issues.
The styles are written with PostCSS, for mixins and other transforms.
Recommended: install a PostCSS language plugin for your editor, like PostCSS Language Support for VS Code.
Currently there's some CSS that has to manually be regenerated in-browser and copied into theme-specific CSS files.
In the future this could be done with a custom PostCSS syntax parser for .theme/.themepack files, and maybe SVG instead of any raster graphics to avoid needing node-canvas (native dependencies are a pain). Or maybe UPNG.js and plain pixel manipulation.
[0.7.0] - 2024-05-23
item in favor of label for menu item labels
shortcut in favor of shortcutLabel and ariaKeyShortcuts
aria-keyshortcuts needs "Control" spelled out, and for macOS "Meta" for the command key, unlike the traditional visual representations. Hence the separation of concerns.AccessKeys API for parsing and rendering labels with access keys (syntax: & defines the following character as the access key, && inserts one literal ampersand)
AccessKeys.escape(label) escapes ampersands by doubling themAccessKeys.unescape(label) unescapes ampersands by removing one of each pairAccessKeys.has(label) returns whether the label has an access keyAccessKeys.get(label) returns the access key character, or null if there isn't oneAccessKeys.remove(label) returns plain text without access key indicator, like AccessKeys.toText() but with a special case to remove parentheticals such as " (&N)" rather than just the ampersandAccessKeys.toText(label) returns plain text without access key syntaxAccessKeys.toHTML(label) returns HTML with <span class="menu-hotkey"> around the access key (uses AccessKeys.toFragment for security)AccessKeys.toFragment(label) returns a DocumentFragment with <span class="menu-hotkey"> wrapping the access key characterAccessKeys.indexOf(label) (don't use this)os-gui package, in os-gui.d.tstsconfig.json's include or files array, or use a /// <reference path="node_modules/os-gui/os-gui.d.ts" /> directive. I'm not sure how exactly this is supposed to work.$Window methods:
onFocus, onBlur, and onClosed API for events (looking to remove dependency on jQuery)addChildWindow($window) (don't use this)unminimize() (don't use this)$Window properties:
closed: Whether the window has been closed.icons: The icons of the window at different sizes, as set by options.icons or setIcons().$minimize: the minimize button$maximize: the maximize button$title_area (don't use this)$icon (don't use this)$Window property element (already mentioned but now has a section like other properties)shortcutLabel for defining the label of the shortcut key combination separately from the ariaKeyShortcuts property; this replaces the old shortcut propertyariaKeyShortcuts for defining the access key combination for the menu item. Must follow aria-keyshortcuts syntax.label for defining the label of the menu item; this replaces the old item propertyvalue (only for radio items) for defining a radio option valuemask-image
MenuBar menu item property description is now optional.see Changed
FAQs
Retro OS styles & components for the web
The npm package os-gui receives a total of 42 weekly downloads. As such, os-gui popularity was classified as not popular.
We found that os-gui demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.