Windows

In order for windows created from an external Java apps to become io.Connect Windows, they must first be registered via the Java Window Management API.

Registering Swing Windows

The Window Management API is accessible via io.windows().

Currently, io.Connect Windows requires the underlying native handle (hwnd in the case of Windows) to be initialized and attached to the JFrame before the window can be registered. This is achieved internally through io.Connect Windows:

WindowHandle<JFrame> handle = io.windows().getWindowHandle(frame);

Window myWindow =
    io.windows().register(handle)
        .thenAccept(window ->
            frame.addWindowListener(new WindowAdapter() {
                @Override
                public void windowClosing(WindowEvent e)
                {
                    window.closeAsync();
                }
            }));

Popup Behavior

When a Swing JFrame is registered as an io.Connect Window, the window is re-parented. This affects how Swing handles popup components such as JPopupMenu and JComboBox dropdowns.

Heavyweight Popups Enforcement

By default, Swing uses lightweight popups (rendered within the same window) when possible for better performance. However, lightweight popups don't function correctly in re-parented windows due to mouse event dispatching issues - clicks may be incorrectly routed to components behind the popup rather than to the popup itself.

To address this, the io.Connect framework automatically enforces heavyweight popups for all JPopupMenu components within registered windows. Heavyweight popups are rendered in their own native window, which ensures proper event handling after re-parenting.

This may affect:

• JComboBox dropdown lists
• JPopupMenu context menus
• Any custom popup menus

Popup Focusability

Additionally, the focusable property of popup menus is disabled when windows are re-parented. This prevents focus-related issues that may occur when the parent window hierarchy of the popup has been modified. While this ensures reliable popup behavior, it means that keyboard navigation within popups may behave differently than in windows that haven't been re-parented.

⚠️ Note that these adjustments are applied automatically during window registration. If your app has specific popup requirements or you experience unexpected behavior, contact us for support.

To retrieve a list of all available io.Connect Windows, use the list() method:

List<Window> allWindows = io.windows().list();

Once an app window is registered, io.Connect Windows will accept full control over the window position, size and visibility. The app shouldn't use native methods (e.g., Swing calls) to control the window as this will interfere with the io.Connect Window management.

The Java Window Management API allows you to control the following window properties:

Mode

The window mode is controlled by the mode window option which can be specified in the app definition or during window registration:

Window myWindow = io.windows().register(handle, options -> options.mode(WindowMode.FLAT));

Title

The following example demonstrates how to set the window title during the window registration (this will ignore the title specified in the app definition):

Window myWindow = io.windows().register(handle, options -> options.title("My Title"));

To change the window title dynamically, use the changeTitle() method of an io.Connect Window instance and pass the new title as an argument:

myWindow.changeTitle("New Title");

Bounds

To change the window bounds (position and size), use the changeBounds() method and pass a Bounds object as an argument. The Bounds() constructor accepts x, y, width and height arguments specifying the position and the size of the window on the screen in pixels:

myWindow.changeBounds(new Bounds(10, 10, 400, 600));

Channel

To change the Channel of the window, use the changeChannel() method and pass the name of the new Channel as an argument:

myWindow.changeChannel("Green");

To instruct the window to leave the current Channel, pass null as an argument:

myWindow.changeChannel(null);

Visibility

To hide or show the window, use the changeVisibility() method. Changing the window visibility also affects its associated icon:

myWindow.changeVisibility(false);

State

To maximize the window, use the maximize() method:

myWindow.maximize();

To minimize the window, use the minimize() method:

myWindow.minimize();

To restore the window to its normal state, use the restore() method:

myWindow.restore();

To collapse the window, use the collapse() method:

myWindow.collapse();

To expand a collapsed window, use the expand() method:

myWindow.expand();

Focus

To focus the window, use the focus() method:

myWindow.focus();

Z-Order

Available since io.Connect Java 1.4.15

To set a window on top of the z-order, use the onTopState() method when supplying options for registering your window in the io.Connect framework:

Window myWindow = io.windows().register(handle, options -> options.onTopState(WindowOnTopState.YES));

⚠️ Note that using the WindowOnTopState.YES option will allow the io.Connect Window to be on top only until the window is visible and not joined to an io.Connect Window group. If the window is hidden programmatically or the user snaps it to another io.Connect Window or window group, it will no longer be on top of the z-order when it becomes visible or when the user tears it off from the group.

To instruct the window to remain permanently on top of the z-order, regardless of changes to its visibility or whether it joins or leaves an io.Connect Window group, use the WindowOnTopState.ALWAYS option:

Window myWindow = io.windows().register(handle, options -> options.onTopState(WindowOnTopState.ALWAYS));

To remove any z-order preferences for the window, use the WindowOnTopState.NO option:

Window myWindow = io.windows().register(handle, options -> options.onTopState(WindowOnTopState.NO));

Each io.Connect Window has a dedicated context. The window context is a Map<String, Object> object which may contain any information regarding the window instance in the form of key/value pairs.

Contexts can be set initially on window creation and updated dynamically. Context changes can be tracked by subscribing to an event which fires when the window context has been updated (see Events > Context).

⚠️ Note that saving large volumes of custom data as window context (e.g., thousands of lines of table data) can lead to significant delays. A user usually has several (in some cases - many) running apps and Workspaces (which can also contain many apps) and if one or more of the apps saves large amounts of context data, this will significantly slow down the saving process (e.g., on shutdown or when saving a Layout). Saving custom context works best with smaller amounts of data. If your app needs to save large amounts of data, you have to think about how to design this process better - for instance, you may store IDs, indices, etc., as context data, save the actual data to a database, and when you restore the app, fetch the data using the data IDs saved as window context.

To update the context of an io.Connect Window, use the changeContext() method and provide the new context object as an argument:

Map<String, Object> context = new LinkedHashMap<>();
context.put("RIC", "BMW.GR");
context.put("ClientID", 235399);
context.put("AccountID", "X2343");

myWindow.changeContext(context);

You can add extra buttons in the frame area of the window and handle clicks for them.

Adding Buttons

To add a new button to the window frame, use the addFrameButton() method:

myWindow.addFrameButton(
                "search-button",
                ButtonOptions.builder()
                    .toolTip("Search")
                    .order(1)
                    .image(new byte[0]) // Must be a valid image.
                    .build())
            .thenRun(() -> System.out.println("Created a frame button."));

Removing Buttons

To remove a button from the window frame, use the removeFrameButton() method:

myWindow.removeFrameButton("search-button")
            .thenRun(() -> System.out.println("Removed a frame button."));

System Buttons

Available since io.Connect Java 1.4.17

To enable or disable the default io.Connect system buttons, use the windowButtons() method when supplying options for registering your window in the io.Connect framework:

Window myWindow =
    io.windows()
        .register(handle, options -> {
            options.windowButtons(
                WindowButtons.builder()
                                .allowClose(true)
                                .allowCollapse(false)
                                .allowLockUnlock(true)
                                .allowMaximize(false)
                                .allowMinimize(false)
                                .build()
            )});

To retrieve the current configuration of system buttons, use the getButtons() method:

WindowButtons systemButtons = myWindow.getButtons();

To provide a new configuration for the system buttons, use the resetButtons() method and pass a WindowButtons object as an argument:

myWindow.resetButtons(
            WindowButtons.builder()
                            .allowClose(true)
                            .allowMaximize(true)
                            .allowMinimize(true)
                            .build());

The Java Window Management API offers methods for handling io.Connect Window events related to changes of the window title, bounds, visibility, context and more. All subscription methods return an object that can be used to unsubscribe from the respective event.

Title

To subscribe for changes of the window title, use the onTitleChanged() method:

myWindow.onTitleChanged(e -> System.out.println("Window title changed to: " + e.getTitle()));

Bounds

To subscribe for changes of the window bounds, use the onBoundsChanged() method:

myWindow.onBoundsChanged(e -> System.out.println("Window bounds changed to: " + e.getBounds()));

Visibility

To subscribe for changes of the window visibility, use the onVisibilityChanged() method:

myWindow.onVisibilityChanged(e -> System.out.println("Window is now " + (e.isVisible() ? "visible." : "hidden.")));

State

To subscribe for changes of the window state, use the onStateChanged() method:

myWindow.onStateChanged(e -> System.out.println("Window state changed to " + e.getState()));

Focus

To subscribe for changes of the window focus, use the onFocusChanged() method:

myWindow.onFocusChanged(e -> System.out.println("Window " + (e.isFocused() ? "is now on focus." : "has lost focus.")));

Context

To subscribe for updates of the window context, use the onContextUpdated() method:

myWindow.onContextUpdated(e -> System.out.println("Window context updated: " + e.getContext()));

Frame Buttons

To subscribe for clicks on any frame buttons you may have added to the window, use the onFrameButtonClicked() method:

myWindow.onFrameButtonClicked(e -> {
    if ("search-button".equals(e.getButtonId())) {
        System.out.println("Search button clicked.");
    }
});

Close

Available since io.Connect Java 1.4.16

To prevent an io.Connect Window from closing, use the onClosing() method. The event handler callback must return asynchronously a PreventClosingOptions object whose methods you can use to specify the behavior of a window that is about to be closed.

The following example demonstrates how to prevent the window from closing and show a confirmation dialog to the user:

myWindow.onClosing(() → CompletableFuture.supplyAsync(PreventClosingOptions :: dialog));

The PreventClosingOptions object has the following methods: