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 through 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();
                }
            }));

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 at runtime, 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

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));

To change the window context, 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 Desktop 9.2

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 udpated: " + 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

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: