Create a window group that other windows can join.
#include <screen/screen.h>
int screen_create_window_group(screen_window_t win, const char *name)
The handle of the window for which the group is created. This window must have been created with screen_create_window_type() with a type of SCREEN_APPLICATION_WINDOW or SCREEN_CHILD_WINDOW.
auto-1564694-00007FFF000000370000138A00002567It is recommended that, unless a static name is explicitly required, you should call this function with name as NULL so that a unique group name is automatically generated. You can use screen_get_window_property_cv() with SCREEN_PROPERTY_GROUP as the property to retrieve the name of the window group.
Function Type: Delayed Execution
This function creates a window group and assigns it to the specified window. The group is identified by the name string, which must be unique. The request will fail if another group was previously created with the same name.
Windows can parent only one group. Therefore, screen_create_window_group() can be called successfully only once for any given window. Additionally, only windows of certain types can parent a group of windows. Windows with a type of SCREEN_APPLICATION_WINDOW can parent windows of type SCREEN_CHILD_WINDOW and SCREEN_EMBEDDED_WINDOW. Windows with a type of SCREEN_CHILD_WINDOW can also create a group and parent windows of type SCREEN_EMBEDDED_WINDOW.
Once a group is created, it exists until the window that parents the group is destroyed. When a parent window is destroyed, all children are orphaned and made invisible. Destroying a child has no effect on the group other than removing the window from the group.
Group owners have privileged access to the windows that they parent. When windows join the group, the parent will receive a SCREEN_EVENT_CREATE that contains a handle to the child window that can be used by the parent to set properties or send events. Conversely, the parent gets notified when a child window gets destroyed. The parent window is expected to destroy its local copy of the window handle when one of its children is destroyed.
0 if request for the new window group was queued, or -1 if an error occurred (errno is set; refer to /usr/include/errno.h for more details).