GTK4 Session Lock: gtk4-layer-shell

## GTK4 Session Lock GTK4 Session Lock — GTK4 support for the Session Lock Wayland protocol |

## Functions

gboolean | gtk_session_lock_is_supported ()
GtkSessionLockInstance * | gtk_session_lock_instance_new ()
gboolean | gtk_session_lock_instance_lock ()
void | gtk_session_lock_instance_unlock ()
gboolean | gtk_session_lock_instance_is_locked ()
void | gtk_session_lock_instance_assign_window_to_monitor ()

## Signals

void | failed | Run First
void | locked | Run First
void | monitor | Run First
void | unlocked | Run First

## Types and Values

#define | GTK4_LAYER_SHELL_EXPORT
| GtkSessionLockInstance

## Object Hierarchy

        GObject
        ╰── GtkSessionLockInstance

## Description

Session Lock is a Wayland protocol for lock screens. Use it to lock the compositor and display the lock screen. This library and the underlying Wayland protocol do not handle authentication.

### Note on popups

Popups (such as menus and tooltips) do not currently display while the screen is locked. Please use alternatives, such as GtkPopover (which is backed by a subsurface instead of a popup).

### Note On Linking

If you link against libwayland you must link this library before libwayland. See linking.md for details.

## Functions

### gtk_session_lock_is_supported ()

    gboolean
    gtk_session_lock_is_supported ();

May block for a Wayland roundtrip the first time it's called.

#### Returns

`TRUE` if the platform is Wayland and Wayland compositor supports the Session Lock protocol.

### gtk_session_lock_instance_new ()

    GtkSessionLockInstance *
    gtk_session_lock_instance_new ();

#### Returns

new session lock instance

### gtk_session_lock_instance_lock ()

    gboolean
    gtk_session_lock_instance_lock (GtkSessionLockInstance *self);

Lock the screen. This should be called before assigning any windows to monitors. If this function fails the ::failed signal is emitted, if it succeeds the ::locked signal is emitted. The ::failed signal may be emitted before the function returns (for example, if another GtkSessionLockInstance holds a lock) or later (if another process holds a lock). The only case where neither signal is triggered is if the instance is already locked.

#### Parameters

self | the instance to lock |

#### Returns

false on immediate fail, true if lock acquisition was successfully started

### gtk_session_lock_instance_unlock ()

    void
    gtk_session_lock_instance_unlock (GtkSessionLockInstance *self);

If the screen is locked by this instance unlocks it and fires ::unlocked. Otherwise has no effect

#### Parameters

self | the instance to unlock |

### gtk_session_lock_instance_is_locked ()

    gboolean
    gtk_session_lock_instance_is_locked (GtkSessionLockInstance *self);

Returns if this instance currently holds a lock.

#### Parameters

self | the instance |

### gtk_session_lock_instance_assign_window_to_monitor ()

    void
    gtk_session_lock_instance_assign_window_to_monitor
                                   (GtkSessionLockInstance *self,
                                    GtkWindow *window,
                                    GdkMonitor *monitor);

This must be called with a different unrealized window once for each monitor immediately after calling `gtk_session_lock_lock()`. Hiding a window that is active on a monitor or not letting a window be resized by the library is not allowed (may result in a Wayland protocol error). The window will be unmapped and `gtk_window_destroy()` called on it when the current lock ends.

#### Parameters

self | the instance to use |
window | The GTK Window to use as a lock surface |
monitor | The monitor to show it on. | [not nullable]

## Types and Values

### GTK4_LAYER_SHELL_EXPORT

    #define             GTK4_LAYER_SHELL_EXPORT

### GtkSessionLockInstance

    typedef struct _GtkSessionLockInstance GtkSessionLockInstance;

An instance of the object used to control locking the screen. Multiple instances can exist at once, but only one can be locked at a time.

Since: 1.1

## Signal Details

### The `“failed”` signal

    void
    user_function (GtkSessionLockInstance *self,
                   gpointer                user_data)

The ::failed signal is fired when the lock could not be acquired.

#### Parameters

self | the GtkSessionLockInstance |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“locked”` signal

    void
    user_function (GtkSessionLockInstance *self,
                   gpointer                user_data)

The ::locked signal is fired when the screen is successfully locked.

#### Parameters

self | the GtkSessionLockInstance |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“monitor”` signal

    void
    user_function (GtkSessionLockInstance *self,
                   GdkMonitor             *monitor,
                   gpointer                user_data)

The ::monitor signal is fired once for each monitor that exists when a lock is started, and then whenever a new monitor is detected during the lock. You generally want to call `gtk_session_lock_instance_assign_window_to_monitor()` once in the handler for this signal with a newly created window and the given monitor.

This API does not directly tell you when a monitor is removed (GTK APIs can be used for that), however the window you send to `gtk_session_lock_instance_assign_window_to_monitor()` will be automatically unmapped and dereferenced when its monitor is removed or the screen is unlocked.

#### Parameters

self | the GtkSessionLockInstance |
monitor | the GdkMonitor that exists or was added |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 1.2

### The `“unlocked”` signal

    void
    user_function (GtkSessionLockInstance *self,
                   gpointer                user_data)

The ::unlocked signal is fired when the session is unlocked, which may have been caused by a call to `gtk_session_lock_instance_unlock()` or by the compositor.

#### Parameters

self | the GtkSessionLockInstance |
user_data | user data set when the signal handler was connected. |

Flags: Run First