Windows

Registering Windows

See the C++ MFC example on GitHub.

You can register the main and child windows of your app as io.Connect Windows in order to enable them to consume io.Connect functionalities (Interop, Channels, Shared Contexts) and participate in all io.Connect visual integration operations like grouping or ungrouping with other io.Connect Windows. Window registration is usually executed when initializing io.Connect - the stage where you can also handle the save and restore state of the main window in case it's saved or restored in a Global Layout, register an app factory and handle the save and restore state of child windows.

Main Window

To register the main window of your app, use glue_register_main_window() or glue_register_window().

The glue_register_main_window() method accepts as arguments the window handle - HWND, an app event handler as an app_callback_function, a window event handler as a glue_window_callback_function, an optional title for the io.Connect Window, and an optional callback cookie.

The following example demonstrates how to register the main window of your app using glue_register_main_window():

// Here `my_app` is a previously defined MFC object from which you can extract the window handle.
const HWND handle = my_app->m_pMainWnd->m_hWnd;

// Callback for handling io.Connect app events.
void app_event_callback (glue_app_command command, const void* callback, const glue_payload* payload, COOKIE cookie) {
    std::cout << "App event for main window: " << command << std::endl;
}

// Callback for handling io.Connect Window events.
void window_event_callback (glue_window_command command, const char* context_name, COOKIE cookie) {
    std::cout << "Window event for main window: " << command << std::endl;
}

// Register the main window of your app.
glue_register_main_window(handle, &app_event_calback, &window_event_callback, "Main Window");

The glue_register_window() method accepts as arguments the window handle - HWND, a window event handler as a glue_window_callback_function, an optional title for the io.Connect Window, an optional callback cookie, and a bool flag indicating whether this is the main (startup) or a child window - it must be set to true when registering the main window.

The following example demonstrates how to register the main window of your app using glue_register_window():

// Here `my_app` is a previously defined MFC object from which you can extract the window handle.
const HWND handle = my_app->m_pMainWnd->m_hWnd;

// Callback for handling io.Connect Window events.
void window_event_callback (glue_window_command command, const char* context_name, COOKIE cookie) {
    std::cout << "Window event for main window: " << command << std::endl;
}

// Register the main window by setting the startup flag to `true`.
glue_register_window(handle, &window_event_callback, "Main Window", nullptr, true);

⚠️ Note that glue_register_main_window() and glue_register_window() will register the main window simultaneously as an io.Connect Window and as an io.Connect app within the io.Connect environment.

Child Windows

To register a child window of your app, use glue_register_window(), as when registering the main window, but either omit or explicitly set the startup bool flag to false to indicate that this is a child window.

Child windows won't be saved or restored in a Layout, but can participate in all visual operations like sticking or unsticking to other io.Connect Windows, and can also consume io.Connect functionalities.

The following example demonstrates how to register a child window of your app:

// Here `my_child_window` is a previously defined MFC object from which you can extract the window handle.
const HWND handle = my_child_window->m_hWnd;

// Callback for handling io.Connect Window events.
void window_event_callback (glue_window_command command, const char* context_name, COOKIE cookie) {
    std::cout << "Window event for child window: " << command << std::endl;
}

// Register a child window - omitting the startup `bool` flag automatiaclly sets it to `false`.
glue_register_window(handle, &window_event_callback, "Child Window");

Events

To handle io.Connect Window events (initializing the window, changing or updating the Channel to which the window is joined), use the glue_window_callback_function passed to glue_register_main_window() or glue_register_window() when registering the window. It will be invoked with a window command as a glue_window_command indicating the io.Connect Window event, the name of the Channel to which the window is currently joined, and an optional callback cookie.

The following example demonstrates how to handle io.Connect Window events in the main window of your app:

// Here `my_app` is a previously defined MFC object from which you can extract the window handle.
HWND handle = my_app->m_pMainWnd->m_hWnd;

// Callback for handling io.Connect app events.
void app_event_callback (glue_app_command command, const void* callback, const glue_payload* payload, COOKIE cookie) {
    std::cout << "App event for main window: " << command << std::endl;
}

// Callback for handling io.Connect Window events.
void window_event_callback (glue_window_command command, const char* context_name, COOKIE cookie) {

    // Handle the io.Connect Window events based on the received command.
    switch (command) {
        // The event triggered when the window has been initialized.
        case glue_window_command::init:
            std::cout << "The window has been initialized." << std::endl;
            break;
        // The event triggered when the window Channel has been changed.
        case glue_window_command::channel_switch:
            std::cout << "Window has been switched to Channel \"" << context_name << "\"." << std::endl;
            break;
        // The event triggered when the window Channel has been updated.
        case glue_window_command::data_update:
            std::cout << "Channel \"" << context_name << "\" has been updated." std::endl;
            break;
        default:
            break;
    }
}

glue_register_main_window(handle, &app_event_callback, &window_event_callback, "Main Window");

io.Connect Window events for child windows can be handled in the same manner either in the glue_window_callback_function passed to glue_register_window() when you register a child window, or in the glue_window_callback_function passed to glue_app_announce_instance() when you register an app factory for child windows.