screen_create_window_group()

Create a window group that other windows can join.

Synopsis:

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

Arguments:

win

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.

name
A unique string that will be used to identify the window group. This name must be communicated to any window wishing to join the group as a child of win. Other than uniqueness, there are no other constraints on this name (for example, lower case and special characters are permitted). If name is a NULL pointer, then a a string is generated for you with this format: auto-<pid>-<32 alpha-numeric characters> For example:
 auto-1564694-00007FFF000000370000138A00002567
It 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.

Library:

libscreen

Description:

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.

Returns:

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