screen_join_window_group()

Updated: April 19, 2023

Cause a window to join a group or a window group

Synopsis:

#include <screen/screen.h>
int screen_join_window_group(screen_window_t win,
                             const char *name)

Arguments:

win
The handle for the window that is to join the group.
name
A unique string that identifies the group. This is the SCREEN_PROPERTY_NAME property of the group that the specified window is joining.

Library:

libscreen

Description:

Function Type: Delayed Execution

This function is used to add a window to a group or window group.

Window group: A window group is a hierarchy of windows. When an application joins a window group, it becomes parented (managed) by the window whose group it joined. Child and embedded windows remain invisible until they're parented.

Until the window joins a window group, a window of any type behaves like an application window. The window's positioning and visibility are not relative to any other window on the display.

Once a window successfully joins a window group, its position on the display is relative to the parent. The type of the window determines exactly how the window is positioned. Child windows are positioned relative to their parent (i.e., their window position is added to the parent's window position. Embedded windows are positioned relative to the source viewport of the parent.

Windows in a window group inherit the visibility and the global transparency of their parent.

Group: A group of windows is a collection of windows that share properties that can be set through screen_set_group_property_*(). Unlike a window group, there's no implication of hierarchy for windows in a group.

Returns:

0 if successful, or -1 if an error occurred (errno is set; refer to errno.h for more details).