screen_create_window_group()

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 is used to identify the window group. This name must be communicated to any window that wants to join the group as a child of win. Lower case and special characters are permitted in string. However, the string must be unique within your system and must not start with __scrn-. If name is a NULL pointer, or an empty string, then Screen generates a string for you starting with __scrn-. It is recommended that, unless a static name is explicitly required, you should call this function with name as NULL (or an empty string) 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:

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 fails 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 receives a SCREEN_EVENT_CREATE event 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.

Call screen_destroy_group() when you no longer need the window group. Note the screen_group_t handle required by screen_destroy_group() can be obtained by calling screen_get_window_property_pv().

Returns:

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