screen_manage_window()

Temporarily transfer the ownership of a window to a manager or parent

Synopsis:

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

Arguments:

win
The window to be managed.
data
The string to be passed to the window manager. Refer to your associated manager for an appropriate value for this string. data must not be NULL.

Library:

libscreen

Description:

Function Type: Flushing Execution

This function notifies one or more managers that this window wants to be managed. At this point, the ownership of the window is transferred to the manager, or parent. The manager, or parent, can configure some of the window's properties (those that could previously only be changed by the owner) so that the manager's requirements are satisfied before allowing execution to continue. For example, the window manager may set the buffer's size (SCREEN_PROPERTY_BUFFER_SIZE).

When the manager has completed managing the window, it sets the property, SCREEN_PROPERTY_MANAGER_STRING to unblock this function. The original owner receives a SCREEN_EVENT_PROPERTY event when this property is set. At this point, the ownership of the window is transferred from the manger, or parent, back to the original window owner. Typically, this function is called immediately after the window is created.

Note:
  • An application can call screen_manage_window() only once per window to be managed.
  • This function blocks the calling thread and returns when the manager is completed managing the window.

When a window manager, or a parent window, doesn't exist for win, then an error is returned and errno is set to EAGAIN. If this is the case, your window owner can manage all of its properties.

Returns:

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