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. Other than uniqueness, there are no other constraints on this name (for example, lower case and special characters are permitted). This string must be communicated to any window wishing to join the group as a child of win.

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