XfwScreen: libxfce4windowing Reference Manual

## XfwScreen XfwScreen — An object representing a logical screen |

## Stability Level

Unstable, unless otherwise indicated

## Functions

XfwScreen * | xfw_screen_get_default ()
GList * | xfw_screen_get_seats ()
XfwWorkspaceManager * | xfw_screen_get_workspace_manager ()
GList * | xfw_screen_get_windows ()
GList * | xfw_screen_get_windows_stacked ()
XfwWindow * | xfw_screen_get_active_window ()
GList * | xfw_screen_get_monitors ()
XfwMonitor * | xfw_screen_get_primary_monitor ()
XfwMonitor * | xfw_screen_get_monitor_from_gdk_monitor ()
gboolean | xfw_screen_get_show_desktop ()
void | xfw_screen_set_show_desktop ()

## Properties

XfwWindow * | active-window | Read
GdkScreen * | gdk-screen | Read / Write / Construct Only
gboolean | show-desktop | Read / Write
XfwWorkspaceManager * | workspace-manager | Read

## Signals

void | active-window-changed | Run Last
void | monitor-added | Run Last
void | monitor-removed | Run Last
void | monitors-changed | Run Last
void | seat-added | Run Last
void | seat-removed | Run Last
void | window-closed | Run Last
void | window-manager-changed | Run Last
void | window-opened | Run Last
void | window-stacking-changed | Run Last

## Types and Values

| XfwScreen

## Object Hierarchy

        GObject
        ╰── XfwScreen

## Includes

    #include <libxfce4windowing/libxfce4windowing.h>

## Description

XfwScreen represents a logical screen. On most windowing environments, this doesn't necessarily correspond to a single monitor, but might span multiple monitors. These days, most windowing environments will only have a single screen, even if (API-wise) more than one can be represented.

The XfwScreen instance is the main entry point into this library. You can obtain an instance using `xfw_screen_get_default()`. From there, you can enumerate toplevel windows, or examine workspace groups and workspaces.

Note that XfwScreen is actually an interface; when obtaining an instance, an instance of a windowing-environment-specific object that implements this interface will be returned.

## Functions

### xfw_screen_get_default ()

    XfwScreen *
    xfw_screen_get_default (void);

Retrieves the XfwScreen instance corresponding to the default GdkScreen.

#### Returns

an XfwScreen instance, with a reference owned by the caller.

[not nullable][transfer full]

### xfw_screen_get_seats ()

    GList *
    xfw_screen_get_seats (XfwScreen *screen);

Returns the list of all XfwSeat instances available on `screen` .

#### Parameters

screen | an XfwScreen. |

#### Returns

a list of XfwSeat. The list and its contents are owned by `screen` .

[nullable][element-type XfwSeat][transfer none]

### xfw_screen_get_workspace_manager ()

    XfwWorkspaceManager *
    xfw_screen_get_workspace_manager (XfwScreen *screen);

Retrieves this screen's XfwWorkspaceManager instance, which can be used to inspect and interact with `screen` 's workspace groups and workspaces.

#### Parameters

screen | an XfwScreen. |

#### Returns

a XfwWorkspaceManager instance. This instance is a singleton and is owned by `screen` .

[not nullable][transfer none]

### xfw_screen_get_windows ()

    GList *
    xfw_screen_get_windows (XfwScreen *screen);

Retrieves the list of windows currently displayed on `screen` .

The list and its contents are owned by `screen` .

#### Parameters

screen | an XfwScreen. |

#### Returns

the list of XfwWindow on `screen` , or `NULL` if there are no windows. The list and its contents are owned by `screen` .

[nullable][element-type XfwWindow][transfer none]

### xfw_screen_get_windows_stacked ()

    GList *
    xfw_screen_get_windows_stacked (XfwScreen *screen);

Retrieves the list of windows currently displayed on `screen` , in stacking order, with the bottom-most window first in the returned list.

#### Parameters

screen | an XfwScreen. |

#### Returns

the list of XfwWindow on `screen` , in stacking order, or `NULL` if there are no windows. The list and its contents are owned by `screen` .

[nullable][element-type XfwWindow][transfer none]

### xfw_screen_get_active_window ()

    XfwWindow *
    xfw_screen_get_active_window (XfwScreen *screen);

Retrieves the window on `screen` that is currently active.

#### Parameters

screen | an XfwScreen. |

#### Returns

an XfwWindow, or `NULL` if no window is active on `screen` .

[nullable][transfer none]

### xfw_screen_get_monitors ()

    GList *
    xfw_screen_get_monitors (XfwScreen *screen);

Retrieves the list of monitors currently attached and enabled on `screen` .

#### Parameters

screen | an XfwScreen. |

#### Returns

the list of XfwMonitor on `screen` , or `NULL` if there are no connected/enabled monitors. The list and its contents are owned by `screen` .

[nullable][element-type XfwMonitor][transfer none]

Since: 4.19.4

### xfw_screen_get_primary_monitor ()

    XfwMonitor *
    xfw_screen_get_primary_monitor (XfwScreen *screen);

Returns the monitor designated as "primary".

This function will do its best to return something other than `NULL`. If the windowing system has no concept of a primary monitor, or if the primary monitor is unset, a likely candidate will be chosen from the list of available monitors.

However, if no monitors are connected, `NULL` can still be returned.

#### Parameters

screen | an XfwScreen. |

#### Returns

`screen` 's primary XfwMonitor, or `NULL`.

[nullable][transfer none]

Since: 4.19.4

### xfw_screen_get_monitor_from_gdk_monitor ()

    XfwMonitor *
    xfw_screen_get_monitor_from_gdk_monitor
                                   (XfwScreen *screen,
                                    GdkMonitor *monitor);

Attempts to find the XfwMonitor corresponding to `monitor` .

#### Parameters

screen | an XfwScreen. |
monitor | a GdkMonitor. |

#### Returns

An XfwMonitor, or `NULL` if the corresponding XfwMonitor could not be determined.

[nullable][transfer none]

Since: 4.20.6

### xfw_screen_get_show_desktop ()

    gboolean
    xfw_screen_get_show_desktop (XfwScreen *screen);

#### Parameters

screen | an XfwScreen. |

#### Returns

`TRUE` if the desktop is shown, `FALSE` otherwise.

### xfw_screen_set_show_desktop ()

    void
    xfw_screen_set_show_desktop (XfwScreen *screen,
                                 gboolean show);

Showing the desktop minimizes the windows not minimized at the time of the query. The reverse process unminimizes those same windows, if they have not already been unminimized or destroyed. The desktop show state can be tracked via “show-desktop”.

The state of the previously active window is always restored upon unminimization, but there is no guarantee for the rest of the window stacking order on Wayland.

A request to switch to the current state is silently ignored.

#### Parameters

screen | an XfwScreen. |
show | `TRUE` to show the desktop, `FALSE` to restore the previous state. |

## Types and Values

### XfwScreen

    typedef struct _XfwScreen XfwScreen;

## Property Details

### The `“active-window”` property

      “active-window”            XfwWindow *

The currently-active window.

Owner: XfwScreen

Flags: Read

### The `“gdk-screen”` property

      “gdk-screen”               GdkScreen *

The GdkScreen instance used to construct this XfwScreen.

Owner: XfwScreen

Flags: Read / Write / Construct Only

### The `“show-desktop”` property

      “show-desktop”             gboolean

Whether or not to show the desktop.

Owner: XfwScreen

Flags: Read / Write

Default value: FALSE

### The `“workspace-manager”` property

      “workspace-manager”        XfwWorkspaceManager *

The XfwWorkspaceManager that manages and describes workspace groups and workspaces on this screen instance.

Owner: XfwScreen

Flags: Read

## Signal Details

### The `“active-window-changed”` signal

    void
    user_function (XfwScreen *screen,
                   XfwWindow *window,
                   gpointer   user_data)

Emitted when a new window becomes the active window. Often the active window will receive keyboard focus. While `window` is the previously-active window (if any, and may be `NULL`), the newly-active window can be retrieved via `xfw_screen_get_active_window()`.

#### Parameters

screen | the object which received the signal. |
window | the previously-active window. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“monitor-added”` signal

    void
    user_function (XfwScreen  *screen,
                   XfwMonitor *monitor,
                   gpointer    user_data)

Emitted when a monitor is added to `screen` .

#### Parameters

screen | the object which received the signal. |
monitor | the monitor that was added. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 4.19.4

### The `“monitor-removed”` signal

    void
    user_function (XfwScreen  *screen,
                   XfwMonitor *monitor,
                   gpointer    user_data)

Emitted when a monitor is removed from `screen` .

#### Parameters

screen | the object which received the signal. |
monitor | the monitor that was removed. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 4.19.4

### The `“monitors-changed”` signal

    void
    user_function (XfwScreen *screen,
                   gpointer   user_data)

Emitted when one of the following has changed about the monitors attached to `screen` :

- A monitor was added.

- A monitor was removed.

- A monitor's resolution changed (including if the scale factor changed).

- A monitor was re-positioned in the global screen space.

- Which monitor is primary has changed.

Note that changes such as the subpixel layout or model name will not result in the emission of this signal. Connect to the propert notify signals on XfwMonitor to be notified of changes in other aspects of the monitor.

#### Parameters

screen | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 4.19.4

### The `“seat-added”` signal

    void
    user_function (XfwScreen *screen,
                   XfwSeat   *seat,
                   gpointer   user_data)

Emitted when `seat` has been added to `screen` .

#### Parameters

screen | the object which received the signal. |
seat | the new XfwSeat that was added. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“seat-removed”` signal

    void
    user_function (XfwScreen *screen,
                   XfwSeat   *seat,
                   gpointer   user_data)

Emitted when `seat` has been added to `screen` .

#### Parameters

screen | the object which received the signal. |
seat | the XfwSeat that was removed. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“window-closed”` signal

    void
    user_function (XfwScreen *screen,
                   XfwWindow *window,
                   gpointer   user_data)

Emitted when a window is closed on the screen.

#### Parameters

screen | the object that received the signal. |
window | the window that has been closed. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“window-manager-changed”` signal

    void
    user_function (XfwScreen *screen,
                   gpointer   user_data)

Emitted when the window manager on `screen` has changed.

Note that currently this signal is not emitted on Wayland.

#### Parameters

screen | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“window-opened”` signal

    void
    user_function (XfwScreen *screen,
                   XfwWindow *window,
                   gpointer   user_data)

Emitted when a new window is opened on the screen.

#### Parameters

screen | the object which received the signal. |
window | the new window that was opened. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“window-stacking-changed”` signal

    void
    user_function (XfwScreen *screen,
                   gpointer   user_data)

Emitted when the order of the windows as displayed on the screen has changed. Windows, in stacking order, can be retrieved via `xfw_screen_get_windows_stacked()`.

Note that currently this signal is not emitted on Wayland.

#### Parameters

screen | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last