SwingUI

Main SwingUI class that handles all communication between JavaScript and GUI. It also contains utility methods not related to specific GUI components. Do not use this class directly, but instead use ui global variable, which is an instance of this class.

See usage example below.

Constructor

new SwingUI(dir)

NOTE: Do not instantiate this class. It's already instantiated and assigned to a global variable <b>ui</b>.

Parameters:
NameTypeDescription
dirstring

Module directory.

See
Example
<h2>Usage examples:</h2>
const data = ui.clipboard();
ui.openURL("http://google.com/");

Classes

SwingUI

Members

(readonly) fonts :Array.<string>

Returns an array of fonts installed on the system.

Type:
  • Array.<string>
Example
<h2>Getting a list of fonts installed on the system:</h2>
console.log(ui.fonts);

// example output:
[
  'Adobe Arabic',
  'Adobe Caslon Pro',
  'Adobe Caslon Pro Bold',
  ...
]

(readonly) license :Object

Gets a GUI software license information stored in the package.json file of your project.

Type:
  • Object

(readonly) list :Array.<string>

Getter property that returns an array of available UI look and feel IDs on your system. For example Windows OS can have a Windows look and feel that linux doesn't have. Use them to set the desired look and feel using ui.ui(id) method.

Type:
  • Array.<string>
See

(readonly) memoryUsage :Object

Returns details of memory usage by GUI process.

Type:
  • Object
Example
<h2>Getting RAM details about the GUI process:</h2>
console.log(ui.memoryUsage);

// Example output
{
  total: 268435456,
  max: 4263510016,
  max_heap: 4263510016,
  used: 23540264,
  non_heap: 39226904,
  free: 244895192,
  heap: 21443112
}

(readonly) os :string

Returns a short identifier of an operating system on current machine. Possible values: "windows", "linux", "darwin" (for Mac), "freebsd", "openbsd", "sunos", and "android".

Type:
  • string
Example
<h2>Getting a short identifier of an operating system:</h2>
console.log(ui.os); // e.g., prints "windows"

(readonly) runtime :string

Gets the JavaScript runtime name ("node", "bun", "deno", or "unknown"). Useful when building an application compatible with multiple JavaScript runtimes.

Type:
  • string
Example
<h2>Getting current JavaScript runtime:</h2>
console.log(ui.runtime);
// prints "node", or what ever your runtime is.

(readonly) screens :Array.<Object>

Returns an array of screen objects [{x,y,width,height}] that are configured on this computer. X and Y is the position of screens relative to one virtual screen. It's useful when you have multiple screens.

Type:
  • Array.<Object>
Example
<h2>Getting a list of screens:</h2>
console.debug(ui.screens);

// Example of returned array:
[
  {
    default: true,
    id: '\\Display0',
    description: 'Win32GraphicsDevice[screen=0]',
    x: 0,
    y: 0,
    width: 2560,
    height: 1080,
    refresh_rate: 59,
    bit_depth: 32,
    type: 'screen'
  },
  {
    default: false,
    id: '\\Display1',
    description: 'Win32GraphicsDevice[screen=1]',
    x: -1280,
    y: 255,
    width: 1280,
    height: 1024,
    refresh_rate: 60,
    bit_depth: 32,
    type: 'screen'
  }
]

(readonly) systemTraySupported :boolean

Checks if current operating system supports system tray icons.

Type:
  • boolean

(readonly) version :string

Gets and returns a swing-ui module version from package.json file.

Type:
  • string

Methods

adjustDefaultFontSize(by) → {this}

Increases and decreases default font size of all controls.

Parameters:
NameTypeDescription
bynumber

By how much to adjust font size (positive increases size, negative decreases)

Returns:

Returns an instance of SwingUI object for method chaining.

Type: 
this

adjustFontSize(by) → {this}

Increases and decreases default font size of all UI components.

Parameters:
NameTypeDescription
bynumber

By how many pixels to adjust font size (positive integer increases size, negative decreases)

Returns:

Returns an instance of SwingUI object for method chaining.

Type: 
this

clipboard(dataopt) → {any|SwingUI}

Sets or reads clipboard content data. Data types must be values of object (enum) UIComponent.DataType.

Parameters:
NameTypeAttributesDescription
dataobject | string<optional>

String text or object {Type: data}. See example below.

Returns:

When setting arguments, this instance of SwingUI is returned, otherwise clipboard data object is returned.

Type: 
any | SwingUI
Examples
<h2>Valid data types for the clipboard data object:</h2>
// Sets all possible data types to clipboard
ui.clipboard({
    Text: "text to copy",
    HTML: "<b>HTML Content</b>",
    JSON: object,
    Image: "base64 encoded image data",
    URIList: ["http://url_1.com", "http://url_2.com"],
    FileList: ["C://my_file.txt", ...],
    URL: "http://url.com"
});
<h2>Setting some plain text and HTML data to clipboard:</h2>
const data = {};
data[UIComponent.DataType.Text] = "Plain text content";
data[UIComponent.DataType.HTML] = "<b>HTML Content</b>";
ui.clipboard(data);

dynamicLayout(valueopt) → {boolean|SwingUI}

Sets or gets boolean whether the layout of containers is validated during resizing, or after resizing is complete.

Parameters:
NameTypeAttributesDescription
valueboolean<optional>

Enabled or disabled dynamic layout

Returns:

When setting arguments, this instance of SwingUI is returned, otherwise current value is returned.

Type: 
boolean | SwingUI

eventThrottle(msopt) → {SwingUI|number}

Gets or sets the event throttle interval for high-frequency events, like mouse motion or resizing. Value is in milliseconds, so 100 means no more than 10 same type of events per component per second. Applies only to some high frequency events, such as resizing and moving.

Parameters:
NameTypeAttributesDescription
msnumber<optional>

Minimum amount of time (in milliseconds) between same type of events per component.

Returns:

When setting arguments, this instance of SwingUI is returned, otherwise current value is returned.

Type: 
SwingUI | number
Example
<h2>Setting and getting examples:</h2>
ui.eventThrottle(10); // Sets new value
console.debug(ui.eventThrottle()); // prints current value

exit(exitCodeopt) → {void}

Gracefully exits the application with specified exit code (status code) after closing connection to GUI and notifying GUI to gracefully exit too. Recommended way to exit, though not required.

Parameters:
NameTypeAttributesDefaultDescription
exitCodenumber<optional>
0

Exit code.

Returns:

Does not return a value.

Type: 
void
Example
<h2>Exiting the app gracefully:</h2>
ui.exit();
ui.exit(10); // existing with exit code 10

gc() → {SwingUI}

Performs garbage collection in JavaScript and GUI.

Returns:

Returns an instance of SwingUI object for method chaining.

Type: 
SwingUI
Example
<h2>Usage example:</h2>
ui.gc();

iconLoadingThreads(minopt, maxopt, keep_aliveopt) → {object|SwingUI}

Adjusts or retrieves the thread pool size and keep-alive time for image loading tasks. Each argument is optional. Setting null to any argument will not change it's value. Returns current configuration if no arguments are specified.

Parameters:
NameTypeAttributesDescription
minnumber<optional>

The minimum number of threads to keep alive (core pool size). Default is 1.

maxnumber<optional>

The maximum number of threads allowed (max pool size). Default is 5.

keep_alivenumber<optional>

The idle time (in seconds) before excess threads are terminated when idle. Default is 5 seconds.

Returns:

When setting arguments, this instance of SwingUI is returned, otherwise current value is returned.

Type: 
object | SwingUI

keyboardAction(action, key_code_or_string) → {SwingUI}

Performs a key press, key release, or key type operation. For value use one character string when using "Press" or "Release" action, or a string of text to be typed when using "Type" action.

Parameters:
NameTypeDescription
actionKeyAction

KeyAction.[Press|Release|Type]

key_code_or_stringnumber | Array.<number> | string

Key code, array of key codes, or a string, which will be converted to an array of key codes.

See
Returns:

Returns this instance of SwingUI class.

Type: 
SwingUI
Example
<h2>Performing a key type action:</h2>
ui.keyboardAction(KeyAction.Type, "A");

lockingKeys(keysopt) → {Object|SwingUI}

Sets and gets locking keys state (Caps lock key, Num lock key, and Scroll lock key) to ON and OFF.

Parameters:
NameTypeAttributesDescription
keysObject<optional>

Keys object example {caps_lock: false, num_lock: true, scroll_lock: false}. Only set keys you want to change.

Returns:

When setting arguments, this instance of SwingUI is returned, otherwise current value is returned.

Type: 
Object | SwingUI
Example
<h2>Setting Caps Lock to ON</h2>
ui.lockingKeys({caps_lock: true});

mouseAction(action, button_or_scrolls) → {SwingUI}

Performs mouse button action or mouse wheel scrolling action.

Parameters:
NameTypeDescription
actionMouseAction

MouseAction.[Press, Release, Click, DoubleClick, VerticalScroll, HorizontalScroll]

button_or_scrollsMouseButton

MouseButton.[Left, Right, Middle] OR integer for scroll amount if action is UIComponent.MouseAction.VerticalScroll or UIComponent.MouseAction.HorizontalScroll

See
Returns:

Returns this instance of SwingUI class.

Type: 
SwingUI

mouseLocation(xopt, yopt, screenopt) → {Object|SwingUI}

Gets or sets a position of a pointing device. If "screen" is specified, the {x,y} position will be relative to the specified screen, otherwise the position will be set relative to screen at index 0 (default screen). You can get a list of screens with ui.screens getter method.

Parameters:
NameTypeAttributesDescription
xnumber<optional>

Use only to set pointer location

ynumber<optional>

required if x is specified

screennumber<optional>
Returns:

When setting arguments, this instance of SwingUI is returned, otherwise current value is returned.

Type: 
Object | SwingUI

onCLI(callbackopt, remove) → {SwingUI}

Registers, unregisters and retrieves event handler that receive STDIN data sent by command line interface (CLI).

Parameters:
NameTypeAttributesDefaultDescription
callbackfunction<optional>

Function to handle the event, null to remove all handlers, or omit to retrieve an array of handlers.

removebooleanfalse

Removed the callback from this event

Returns:

Returns this instance of SwingUI class.

Type: 
SwingUI
Example
<h2>Registering an event handler to receive CLI input:</h2>
ui.onCLI(e => {console.log(`Received: ${e.data}`);});

onDragMotion(callback, remove) → {SwingUI}

Registers global onDragMotion event handler that works in all Java apps (but not outside of Java applications).

Parameters:
NameTypeDefaultDescription
callbackfunction

Function to handle the event

removebooleanfalse

Removed the callback from this event

Returns:

Returns this instance of SwingUI class.

Type: 
SwingUI

onError(callback) → {SwingUI}

Sets a custom Error handler when error events come if from GUI. Event object has a "e.message" parameter, and may have "e.target" that references a component related to the error. e:{ message (always) target: (when component is related to the error) }

Parameters:
NameTypeDescription
callbackfunction

Function to be called instead of default error handling.

Returns:

Returns this instance of SwingUI class.

Type: 
SwingUI

onMouseEvents(callback, remove) → {SwingUI}

Registers global onMouseEvent event handler that works in all Java apps (but not outside of Java applications).

Parameters:
NameTypeDefaultDescription
callbackfunction

Function to handle the event

removebooleanfalse

Removed the callback from this event

Returns:

Returns this instance of SwingUI class.

Type: 
SwingUI

onMouseMotion(callback, remove) → {SwingUI}

Registers global onMouseMotions event handler that works in all Java apps (but not outside of Java applications).

Parameters:
NameTypeDefaultDescription
callbackfunction

Function to handle the event

removebooleanfalse

Removed the callback from this event

Returns:

Returns this instance of SwingUI class.

Type: 
SwingUI

onMouseWheel(callback, remove) → {SwingUI}

Registers global onMouseWheel event handler that works in all Java apps (but not outside of Java applications).

Parameters:
NameTypeDefaultDescription
callbackfunction

Function to handle the event

removebooleanfalse

Removed the callback from this event

Returns:

Returns this instance of SwingUI class.

Type: 
SwingUI

openUrl(url) → {this}

Opens provided URL in a default web browser.

Parameters:
NameTypeDescription
urlstring

Website address to open.

Returns:

Returns this instance of SwingUI class.

Type: 
this

sendMessageQueue(compressopt) → {this}

Immediately sends all queued messages to GUI without waiting for queue threshold or execution end. It's similar to flush() function in data streams. It can be used to force messages to be sent imedietly instead of waiting for message queue to be full, if it's important to update some UI component or content right away. It may improve performance to set compress to false to skip compression for already compressed data, such as UI component's background image or large icon.

Parameters:
NameTypeAttributesDefaultDescription
compressboolean<optional>
true

Whether to compress messages before sending.

Returns:

Returns this instance for chaining.

Type: 
this
Examples
<h2>Sending queued messages before proceeding:</h2>
ui.sendMessageQueue();
<h2>Sending queued messages without compressing:</h2>
ui.sendMessageQueue(false);

showMessage(message, titleopt, iconopt, ownerWindowopt) → {void}

Shows a message dialog window like alert() in web browser.

Parameters:
NameTypeAttributesDefaultDescription
messagestring
titlestring<optional>
Message

Message window title

iconUIComponent.MessageIcon<optional>

Use: UIComponent.MessageIcon.[Info|Warning|Error]

ownerWindowWindow<optional>
null

If set, the message dialog window will attempts to be centered at specified window

Returns:

Does not return a value.

Type: 
void

ui(idopt) → {string|SwingUI}

Gets or sets Java's GUI look and feel ID. Obtain a list of supported UIs by the system using ui.list getter property.

Parameters:
NameTypeAttributesDescription
idstring<optional>

Identifies of Java Swing's UI to be used.

Returns:

When setting arguments, this instance of SwingUI is returned, otherwise current value is returned.

Type: 
string | SwingUI