Unstable protocols¶
fullscreen-shell¶
zwp_fullscreen_shell_v1¶
Client Headers¶
-
group
iface_zwp_fullscreen_shell_v1
Displays a single surface per output.
This interface provides a mechanism for a single client to display simple full-screen surfaces. While there technically may be multiple clients bound to this interface, only one of those clients should be shown at a time.
To present a surface, the client uses either the present_surface or present_surface_for_mode requests. Presenting a surface takes effect on the next wl_surface.commit. See the individual requests for details about scaling and mode switches.
The client can have at most one surface per output at any time. Requesting a surface to be presented on an output that already has a surface replaces the previously presented surface. Presenting a null surface removes its content and effectively disables the output. Exactly what happens when an output is “disabled” is compositor-specific. The same surface may be presented on multiple outputs simultaneously.
Once a surface is presented on an output, it stays on that output until either the client removes it or the compositor destroys the output. This way, the client can update the output’s contents by simply attaching a new buffer.
Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.
Defines
-
ZWP_FULLSCREEN_SHELL_V1_CAPABILITY_SINCE_VERSION
¶
-
ZWP_FULLSCREEN_SHELL_V1_RELEASE_SINCE_VERSION
¶
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_SURFACE_SINCE_VERSION
¶
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_SURFACE_FOR_MODE_SINCE_VERSION
¶
Enums
-
enum
zwp_fullscreen_shell_v1_capability
¶ capabilities advertised by the compositor
Various capabilities that can be advertised by the compositor. They are advertised one-at-a-time when the wl_fullscreen_shell interface is bound. See the wl_fullscreen_shell.capability event for more details.
ARBITRARY_MODES: This is a hint to the client that indicates that the compositor is capable of setting practically any mode on its outputs. If this capability is provided, wl_fullscreen_shell.present_surface_for_mode will almost never fail and clients should feel free to set whatever mode they like. If the compositor does not advertise this, it may still support some modes that are not advertised through wl_global.mode but it is less likely.
CURSOR_PLANE: This is a hint to the client that indicates that the compositor can handle a cursor surface from the client without actually compositing. This may be because of a hardware cursor plane or some other mechanism. If the compositor does not advertise this capability then setting wl_pointer.cursor may degrade performance or be ignored entirely. If CURSOR_PLANE is not advertised, it is recommended that the client draw its own cursor and set wl_pointer.cursor(NULL).
Values:
-
ZWP_FULLSCREEN_SHELL_V1_CAPABILITY_ARBITRARY_MODES
= 1¶ compositor is capable of almost any output mode
-
ZWP_FULLSCREEN_SHELL_V1_CAPABILITY_CURSOR_PLANE
= 2¶ compositor has a separate cursor plane
-
-
enum
zwp_fullscreen_shell_v1_present_method
¶ different method to set the surface fullscreen
Hints to indicate to the compositor how to deal with a conflict between the dimensions of the surface and the dimensions of the output. The compositor is free to ignore this parameter.
Values:
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_DEFAULT
= 0¶ no preference, apply default policy
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_CENTER
= 1¶ center the surface on the output
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_ZOOM
= 2¶ scale the surface, preserving aspect ratio, to the largest size that will fit on the output
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_ZOOM_CROP
= 3¶ scale the surface, preserving aspect ratio, to fully fill the output cropping if needed
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_STRETCH
= 4¶ scale the surface to the size of the output ignoring aspect ratio
-
Functions
-
static int
zwp_fullscreen_shell_v1_add_listener
(struct zwp_fullscreen_shell_v1 *zwp_fullscreen_shell_v1, const struct zwp_fullscreen_shell_v1_listener *listener, void *data)¶
-
static void
zwp_fullscreen_shell_v1_set_user_data
(struct zwp_fullscreen_shell_v1 *zwp_fullscreen_shell_v1, void *user_data)¶
-
static void *
zwp_fullscreen_shell_v1_get_user_data
(struct zwp_fullscreen_shell_v1 *zwp_fullscreen_shell_v1)¶
-
static void
zwp_fullscreen_shell_v1_destroy
(struct zwp_fullscreen_shell_v1 *zwp_fullscreen_shell_v1)¶
-
static void
zwp_fullscreen_shell_v1_release
(struct zwp_fullscreen_shell_v1 *zwp_fullscreen_shell_v1)¶ Release the binding from the wl_fullscreen_shell interface.
This destroys the server-side object and frees this binding. If the client binds to wl_fullscreen_shell multiple times, it may wish to free some of those bindings.
-
static void
zwp_fullscreen_shell_v1_present_surface
(struct zwp_fullscreen_shell_v1 *zwp_fullscreen_shell_v1, struct wl_surface *surface, uint32_t method, struct wl_output *output)¶ Present a surface on the given output.
If the output is null, the compositor will present the surface on whatever display (or displays) it thinks best. In particular, this may replace any or all surfaces currently presented so it should not be used in combination with placing surfaces on specific outputs.
The method parameter is a hint to the compositor for how the surface is to be presented. In particular, it tells the compositor how to handle a size mismatch between the presented surface and the output. The compositor is free to ignore this parameter.
The “zoom”, “zoom_crop”, and “stretch” methods imply a scaling operation on the surface. This will override any kind of output scaling, so the buffer_scale property of the surface is effectively ignored.
-
static struct zwp_fullscreen_shell_mode_feedback_v1 *
zwp_fullscreen_shell_v1_present_surface_for_mode
(struct zwp_fullscreen_shell_v1 *zwp_fullscreen_shell_v1, struct wl_surface *surface, struct wl_output *output, int32_t framerate)¶ Presents a surface on the given output for a particular mode.
If the current size of the output differs from that of the surface, the compositor will attempt to change the size of the output to match the surface. The result of the mode-switch operation will be returned via the provided wl_fullscreen_shell_mode_feedback object.
If the current output mode matches the one requested or if the compositor successfully switches the mode to match the surface, then the mode_successful event will be sent and the output will contain the contents of the given surface. If the compositor cannot match the output size to the surface size, the mode_failed will be sent and the output will contain the contents of the previously presented surface (if any). If another surface is presented on the given output before either of these has a chance to happen, the present_cancelled event will be sent.
Due to race conditions and other issues unknown to the client, no mode-switch operation is guaranteed to succeed. However, if the mode is one advertised by wl_output.mode or if the compositor advertises the ARBITRARY_MODES capability, then the client should expect that the mode-switch operation will usually succeed.
If the size of the presented surface changes, the resulting output is undefined. The compositor may attempt to change the output mode to compensate. However, there is no guarantee that a suitable mode will be found and the client has no way to be notified of success or failure.
The framerate parameter specifies the desired framerate for the output in mHz. The compositor is free to ignore this parameter. A value of 0 indicates that the client has no preference.
If the value of wl_output.scale differs from wl_surface.buffer_scale, then the compositor may choose a mode that matches either the buffer size or the surface size. In either case, the surface will fill the output.
-
struct
zwp_fullscreen_shell_v1_listener
¶ - #include <fullscreen-shell-client-protocol.h>
Public Members
-
void (*
capability
)(void *data, struct zwp_fullscreen_shell_v1 *zwp_fullscreen_shell_v1, uint32_t capability)¶ advertises a capability of the compositor
Advertises a single capability of the compositor.
When the wl_fullscreen_shell interface is bound, this event is emitted once for each capability advertised. Valid capabilities are given by the wl_fullscreen_shell.capability enum. If clients want to take advantage of any of these capabilities, they should use a wl_display.sync request immediately after binding to ensure that they receive all the capability events.
-
void (*
-
Server Headers¶
-
group
iface_zwp_fullscreen_shell_v1
Displays a single surface per output.
This interface provides a mechanism for a single client to display simple full-screen surfaces. While there technically may be multiple clients bound to this interface, only one of those clients should be shown at a time.
To present a surface, the client uses either the present_surface or present_surface_for_mode requests. Presenting a surface takes effect on the next wl_surface.commit. See the individual requests for details about scaling and mode switches.
The client can have at most one surface per output at any time. Requesting a surface to be presented on an output that already has a surface replaces the previously presented surface. Presenting a null surface removes its content and effectively disables the output. Exactly what happens when an output is “disabled” is compositor-specific. The same surface may be presented on multiple outputs simultaneously.
Once a surface is presented on an output, it stays on that output until either the client removes it or the compositor destroys the output. This way, the client can update the output’s contents by simply attaching a new buffer.
Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.
Defines
-
ZWP_FULLSCREEN_SHELL_V1_CAPABILITY_SINCE_VERSION
-
ZWP_FULLSCREEN_SHELL_V1_RELEASE_SINCE_VERSION
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_SURFACE_SINCE_VERSION
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_SURFACE_FOR_MODE_SINCE_VERSION
Enums
-
enum
zwp_fullscreen_shell_v1_capability
capabilities advertised by the compositor
Various capabilities that can be advertised by the compositor. They are advertised one-at-a-time when the wl_fullscreen_shell interface is bound. See the wl_fullscreen_shell.capability event for more details.
ARBITRARY_MODES: This is a hint to the client that indicates that the compositor is capable of setting practically any mode on its outputs. If this capability is provided, wl_fullscreen_shell.present_surface_for_mode will almost never fail and clients should feel free to set whatever mode they like. If the compositor does not advertise this, it may still support some modes that are not advertised through wl_global.mode but it is less likely.
CURSOR_PLANE: This is a hint to the client that indicates that the compositor can handle a cursor surface from the client without actually compositing. This may be because of a hardware cursor plane or some other mechanism. If the compositor does not advertise this capability then setting wl_pointer.cursor may degrade performance or be ignored entirely. If CURSOR_PLANE is not advertised, it is recommended that the client draw its own cursor and set wl_pointer.cursor(NULL).
Values:
-
ZWP_FULLSCREEN_SHELL_V1_CAPABILITY_ARBITRARY_MODES
= 1 compositor is capable of almost any output mode
-
ZWP_FULLSCREEN_SHELL_V1_CAPABILITY_CURSOR_PLANE
= 2 compositor has a separate cursor plane
-
-
enum
zwp_fullscreen_shell_v1_present_method
different method to set the surface fullscreen
Hints to indicate to the compositor how to deal with a conflict between the dimensions of the surface and the dimensions of the output. The compositor is free to ignore this parameter.
Values:
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_DEFAULT
= 0 no preference, apply default policy
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_CENTER
= 1 center the surface on the output
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_ZOOM
= 2 scale the surface, preserving aspect ratio, to the largest size that will fit on the output
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_ZOOM_CROP
= 3 scale the surface, preserving aspect ratio, to fully fill the output cropping if needed
-
ZWP_FULLSCREEN_SHELL_V1_PRESENT_METHOD_STRETCH
= 4 scale the surface to the size of the output ignoring aspect ratio
-
-
enum
zwp_fullscreen_shell_v1_error
wl_fullscreen_shell error values
These errors can be emitted in response to wl_fullscreen_shell requests.
Values:
-
ZWP_FULLSCREEN_SHELL_V1_ERROR_INVALID_METHOD
= 0 present_method is not known
-
Functions
-
static void
zwp_fullscreen_shell_v1_send_capability
(struct wl_resource *resource_, uint32_t capability)¶ Sends an capability event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
struct
zwp_fullscreen_shell_v1_interface
¶ - #include <fullscreen-shell-server-protocol.h>
Public Members
-
void (*
release
)(struct wl_client *client, struct wl_resource *resource)¶ release the wl_fullscreen_shell interface
Release the binding from the wl_fullscreen_shell interface.
This destroys the server-side object and frees this binding. If the client binds to wl_fullscreen_shell multiple times, it may wish to free some of those bindings.
-
void (*
present_surface
)(struct wl_client *client, struct wl_resource *resource, struct wl_resource *surface, uint32_t method, struct wl_resource *output)¶ present surface for display
Present a surface on the given output.
If the output is null, the compositor will present the surface on whatever display (or displays) it thinks best. In particular, this may replace any or all surfaces currently presented so it should not be used in combination with placing surfaces on specific outputs.
The method parameter is a hint to the compositor for how the surface is to be presented. In particular, it tells the compositor how to handle a size mismatch between the presented surface and the output. The compositor is free to ignore this parameter.
The “zoom”, “zoom_crop”, and “stretch” methods imply a scaling operation on the surface. This will override any kind of output scaling, so the buffer_scale property of the surface is effectively ignored.
-
void (*
present_surface_for_mode
)(struct wl_client *client, struct wl_resource *resource, struct wl_resource *surface, struct wl_resource *output, int32_t framerate, uint32_t feedback)¶ present surface for display at a particular mode
Presents a surface on the given output for a particular mode.
If the current size of the output differs from that of the surface, the compositor will attempt to change the size of the output to match the surface. The result of the mode-switch operation will be returned via the provided wl_fullscreen_shell_mode_feedback object.
If the current output mode matches the one requested or if the compositor successfully switches the mode to match the surface, then the mode_successful event will be sent and the output will contain the contents of the given surface. If the compositor cannot match the output size to the surface size, the mode_failed will be sent and the output will contain the contents of the previously presented surface (if any). If another surface is presented on the given output before either of these has a chance to happen, the present_cancelled event will be sent.
Due to race conditions and other issues unknown to the client, no mode-switch operation is guaranteed to succeed. However, if the mode is one advertised by wl_output.mode or if the compositor advertises the ARBITRARY_MODES capability, then the client should expect that the mode-switch operation will usually succeed.
If the size of the presented surface changes, the resulting output is undefined. The compositor may attempt to change the output mode to compensate. However, there is no guarantee that a suitable mode will be found and the client has no way to be notified of success or failure.
The framerate parameter specifies the desired framerate for the output in mHz. The compositor is free to ignore this parameter. A value of 0 indicates that the client has no preference.
If the value of wl_output.scale differs from wl_surface.buffer_scale, then the compositor may choose a mode that matches either the buffer size or the surface size. In either case, the surface will fill the output.
-
void (*
-
zwp_fullscreen_shell_mode_feedback_v1¶
Client Headers¶
-
group
iface_zwp_fullscreen_shell_mode_feedback_v1
Defines
-
ZWP_FULLSCREEN_SHELL_MODE_FEEDBACK_V1_MODE_SUCCESSFUL_SINCE_VERSION
¶
-
ZWP_FULLSCREEN_SHELL_MODE_FEEDBACK_V1_MODE_FAILED_SINCE_VERSION
¶
-
ZWP_FULLSCREEN_SHELL_MODE_FEEDBACK_V1_PRESENT_CANCELLED_SINCE_VERSION
¶
Functions
-
static int
zwp_fullscreen_shell_mode_feedback_v1_add_listener
(struct zwp_fullscreen_shell_mode_feedback_v1 *zwp_fullscreen_shell_mode_feedback_v1, const struct zwp_fullscreen_shell_mode_feedback_v1_listener *listener, void *data)¶
-
static void
zwp_fullscreen_shell_mode_feedback_v1_set_user_data
(struct zwp_fullscreen_shell_mode_feedback_v1 *zwp_fullscreen_shell_mode_feedback_v1, void *user_data)¶
-
static void *
zwp_fullscreen_shell_mode_feedback_v1_get_user_data
(struct zwp_fullscreen_shell_mode_feedback_v1 *zwp_fullscreen_shell_mode_feedback_v1)¶
-
static void
zwp_fullscreen_shell_mode_feedback_v1_destroy
(struct zwp_fullscreen_shell_mode_feedback_v1 *zwp_fullscreen_shell_mode_feedback_v1)¶
-
struct
zwp_fullscreen_shell_mode_feedback_v1_listener
¶ - #include <fullscreen-shell-client-protocol.h>
Public Members
-
void (*
mode_successful
)(void *data, struct zwp_fullscreen_shell_mode_feedback_v1 *zwp_fullscreen_shell_mode_feedback_v1)¶ mode switch succeeded
This event indicates that the attempted mode switch operation was successful. A surface of the size requested in the mode switch will fill the output without scaling.
Upon receiving this event, the client should destroy the wl_fullscreen_shell_mode_feedback object.
-
void (*
mode_failed
)(void *data, struct zwp_fullscreen_shell_mode_feedback_v1 *zwp_fullscreen_shell_mode_feedback_v1)¶ mode switch failed
This event indicates that the attempted mode switch operation failed. This may be because the requested output mode is not possible or it may mean that the compositor does not want to allow it.
Upon receiving this event, the client should destroy the wl_fullscreen_shell_mode_feedback object.
-
void (*
present_cancelled
)(void *data, struct zwp_fullscreen_shell_mode_feedback_v1 *zwp_fullscreen_shell_mode_feedback_v1)¶ mode switch cancelled
This event indicates that the attempted mode switch operation was cancelled. Most likely this is because the client requested a second mode switch before the first one completed.
Upon receiving this event, the client should destroy the wl_fullscreen_shell_mode_feedback object.
-
void (*
-
Server Headers¶
-
group
iface_zwp_fullscreen_shell_mode_feedback_v1
Defines
-
ZWP_FULLSCREEN_SHELL_MODE_FEEDBACK_V1_MODE_SUCCESSFUL_SINCE_VERSION
-
ZWP_FULLSCREEN_SHELL_MODE_FEEDBACK_V1_MODE_FAILED_SINCE_VERSION
-
ZWP_FULLSCREEN_SHELL_MODE_FEEDBACK_V1_PRESENT_CANCELLED_SINCE_VERSION
Functions
-
static void
zwp_fullscreen_shell_mode_feedback_v1_send_mode_successful
(struct wl_resource *resource_)¶ Sends an mode_successful event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
static void
zwp_fullscreen_shell_mode_feedback_v1_send_mode_failed
(struct wl_resource *resource_)¶ Sends an mode_failed event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
static void
zwp_fullscreen_shell_mode_feedback_v1_send_present_cancelled
(struct wl_resource *resource_)¶ Sends an present_cancelled event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
idle-inhibit¶
zwp_idle_inhibit_manager_v1¶
Client Headers¶
-
group
iface_zwp_idle_inhibit_manager_v1
This interface permits inhibiting the idle behavior such as screen blanking, locking, and screensaving.
The client binds the idle manager globally, then creates idle-inhibitor objects for each surface.
Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.
Defines
-
ZWP_IDLE_INHIBIT_MANAGER_V1_DESTROY_SINCE_VERSION
¶
-
ZWP_IDLE_INHIBIT_MANAGER_V1_CREATE_INHIBITOR_SINCE_VERSION
¶
Functions
-
static void
zwp_idle_inhibit_manager_v1_set_user_data
(struct zwp_idle_inhibit_manager_v1 *zwp_idle_inhibit_manager_v1, void *user_data)¶
-
static void *
zwp_idle_inhibit_manager_v1_get_user_data
(struct zwp_idle_inhibit_manager_v1 *zwp_idle_inhibit_manager_v1)¶
-
static void
zwp_idle_inhibit_manager_v1_destroy
(struct zwp_idle_inhibit_manager_v1 *zwp_idle_inhibit_manager_v1)¶ Destroy the inhibit manager.
-
static struct zwp_idle_inhibitor_v1 *
zwp_idle_inhibit_manager_v1_create_inhibitor
(struct zwp_idle_inhibit_manager_v1 *zwp_idle_inhibit_manager_v1, struct wl_surface *surface)¶ Create a new inhibitor object associated with the given surface.
-
Server Headers¶
-
group
iface_zwp_idle_inhibit_manager_v1
This interface permits inhibiting the idle behavior such as screen blanking, locking, and screensaving.
The client binds the idle manager globally, then creates idle-inhibitor objects for each surface.
Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.
Defines
-
ZWP_IDLE_INHIBIT_MANAGER_V1_DESTROY_SINCE_VERSION
-
ZWP_IDLE_INHIBIT_MANAGER_V1_CREATE_INHIBITOR_SINCE_VERSION
-
struct
zwp_idle_inhibit_manager_v1_interface
¶ - #include <idle-inhibit-server-protocol.h>
Public Members
-
void (*
destroy
)(struct wl_client *client, struct wl_resource *resource)¶ destroy the idle inhibitor object
Destroy the inhibit manager.
-
void (*
create_inhibitor
)(struct wl_client *client, struct wl_resource *resource, uint32_t id, struct wl_resource *surface)¶ create a new inhibitor object
Create a new inhibitor object associated with the given surface.
- Parameters
surface
: the surface that inhibits the idle behavior
-
void (*
-
iface_zwp_idle_inhibitor_v1¶
Client Headers¶
-
group
iface_zwp_idle_inhibitor_v1
An idle inhibitor prevents the output that the associated surface is visible on from being set to a state where it is not visually usable due to lack of user interaction (e.g.
blanked, dimmed, locked, set to power save, etc.) Any screensaver processes are also blocked from displaying.
If the surface is destroyed, unmapped, becomes occluded, loses visibility, or otherwise becomes not visually relevant for the user, the idle inhibitor will not be honored by the compositor; if the surface subsequently regains visibility the inhibitor takes effect once again. Likewise, the inhibitor isn’t honored if the system was already idled at the time the inhibitor was established, although if the system later de-idles and re-idles the inhibitor will take effect.
Defines
-
ZWP_IDLE_INHIBITOR_V1_DESTROY_SINCE_VERSION
¶
Functions
-
static void
zwp_idle_inhibitor_v1_set_user_data
(struct zwp_idle_inhibitor_v1 *zwp_idle_inhibitor_v1, void *user_data)¶
-
static void *
zwp_idle_inhibitor_v1_get_user_data
(struct zwp_idle_inhibitor_v1 *zwp_idle_inhibitor_v1)¶
-
static void
zwp_idle_inhibitor_v1_destroy
(struct zwp_idle_inhibitor_v1 *zwp_idle_inhibitor_v1)¶ Remove the inhibitor effect from the associated wl_surface.
-
Server Headers¶
-
group
iface_zwp_idle_inhibitor_v1
An idle inhibitor prevents the output that the associated surface is visible on from being set to a state where it is not visually usable due to lack of user interaction (e.g.
blanked, dimmed, locked, set to power save, etc.) Any screensaver processes are also blocked from displaying.
If the surface is destroyed, unmapped, becomes occluded, loses visibility, or otherwise becomes not visually relevant for the user, the idle inhibitor will not be honored by the compositor; if the surface subsequently regains visibility the inhibitor takes effect once again. Likewise, the inhibitor isn’t honored if the system was already idled at the time the inhibitor was established, although if the system later de-idles and re-idles the inhibitor will take effect.
Defines
-
ZWP_IDLE_INHIBITOR_V1_DESTROY_SINCE_VERSION
-
input-method¶
zwp_input_method_context_v1¶
Client Headers¶
-
group
iface_zwp_input_method_context_v1
Corresponds to a text input on the input method side.
An input method context is created on text input activation on the input method side. It allows receiving information about the text input from the application via events. Input method contexts do not keep state after deactivation and should be destroyed after deactivation is handled.
Text is generally UTF-8 encoded, indices and lengths are in bytes.
Serials are used to synchronize the state between the text input and an input method. New serials are sent by the text input in the commit_state request and are used by the input method to indicate the known text input state in events like preedit_string, commit_string, and keysym. The text input can then ignore events from the input method which are based on an outdated state (for example after a reset).
Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.
Defines
-
ZWP_INPUT_METHOD_CONTEXT_V1_SURROUNDING_TEXT_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_RESET_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_CONTENT_TYPE_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_INVOKE_ACTION_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_COMMIT_STATE_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_PREFERRED_LANGUAGE_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_DESTROY_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_COMMIT_STRING_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_PREEDIT_STRING_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_PREEDIT_STYLING_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_PREEDIT_CURSOR_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_DELETE_SURROUNDING_TEXT_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_CURSOR_POSITION_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_MODIFIERS_MAP_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_KEYSYM_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_GRAB_KEYBOARD_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_KEY_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_MODIFIERS_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_LANGUAGE_SINCE_VERSION
¶
-
ZWP_INPUT_METHOD_CONTEXT_V1_TEXT_DIRECTION_SINCE_VERSION
¶
Functions
-
static int
zwp_input_method_context_v1_add_listener
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, const struct zwp_input_method_context_v1_listener *listener, void *data)¶
-
static void
zwp_input_method_context_v1_set_user_data
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, void *user_data)¶
-
static void *
zwp_input_method_context_v1_get_user_data
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1)¶
-
static void
zwp_input_method_context_v1_destroy
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1)¶
-
static void
zwp_input_method_context_v1_commit_string
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, uint32_t serial, const char *text)¶ Send the commit string text for insertion to the application.
The text to commit could be either just a single character after a key press or the result of some composing (pre-edit). It could be also an empty text when some text should be removed (see delete_surrounding_text) or when the input cursor should be moved (see cursor_position).
Any previously set composing text will be removed.
-
static void
zwp_input_method_context_v1_preedit_string
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, uint32_t serial, const char *text, const char *commit)¶ Send the pre-edit string text to the application text input.
The commit text can be used to replace the pre-edit text on reset (for example on unfocus).
Previously sent preedit_style and preedit_cursor requests are also processed by the text_input.
-
static void
zwp_input_method_context_v1_preedit_styling
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, uint32_t index, uint32_t length, uint32_t style)¶ Set the styling information on composing text.
The style is applied for length in bytes from index relative to the beginning of the composing text (as byte offset). Multiple styles can be applied to a composing text.
This request should be sent before sending a preedit_string request.
-
static void
zwp_input_method_context_v1_preedit_cursor
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, int32_t index)¶ Set the cursor position inside the composing text (as byte offset) relative to the start of the composing text.
When index is negative no cursor should be displayed.
This request should be sent before sending a preedit_string request.
-
static void
zwp_input_method_context_v1_delete_surrounding_text
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, int32_t index, uint32_t length)¶ Remove the surrounding text.
This request will be handled on the text_input side directly following a commit_string request.
-
static void
zwp_input_method_context_v1_cursor_position
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, int32_t index, int32_t anchor)¶ Set the cursor and anchor to a new position.
Index is the new cursor position in bytes (when >= 0 this is relative to the end of the inserted text, otherwise it is relative to the beginning of the inserted text). Anchor is the new anchor position in bytes (when >= 0 this is relative to the end of the inserted text, otherwise it is relative to the beginning of the inserted text). When there should be no selected text, anchor should be the same as index.
This request will be handled on the text_input side directly following a commit_string request.
-
static void
zwp_input_method_context_v1_modifiers_map
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, struct wl_array *map)¶
-
static void
zwp_input_method_context_v1_keysym
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, uint32_t serial, uint32_t time, uint32_t sym, uint32_t state, uint32_t modifiers)¶ Notify when a key event was sent.
Key events should not be used for normal text input operations, which should be done with commit_string, delete_surrounding_text, etc. The key event follows the wl_keyboard key event convention. Sym is an XKB keysym, state is a wl_keyboard key_state.
-
static struct wl_keyboard *
zwp_input_method_context_v1_grab_keyboard
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1)¶ Allow an input method to receive hardware keyboard input and process key events to generate text events (with pre-edit) over the wire.
This allows input methods which compose multiple key events for inputting text like it is done for CJK languages.
-
static void
zwp_input_method_context_v1_key
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, uint32_t serial, uint32_t time, uint32_t key, uint32_t state)¶ Forward a wl_keyboard::key event to the client that was not processed by the input method itself.
Should be used when filtering key events with grab_keyboard. The arguments should be the ones from the wl_keyboard::key event.
For generating custom key events use the keysym request instead.
-
static void
zwp_input_method_context_v1_modifiers
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, uint32_t serial, uint32_t mods_depressed, uint32_t mods_latched, uint32_t mods_locked, uint32_t group)¶ Forward a wl_keyboard::modifiers event to the client that was not processed by the input method itself.
Should be used when filtering key events with grab_keyboard. The arguments should be the ones from the wl_keyboard::modifiers event.
-
static void
zwp_input_method_context_v1_language
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, uint32_t serial, const char *language)¶
-
static void
zwp_input_method_context_v1_text_direction
(struct zwp_input_method_context_v1 *zwp_input_method_context_v1, uint32_t serial, uint32_t direction)¶
-
struct
zwp_input_method_context_v1_listener
¶ - #include <input-method-client-protocol.h>
Public Members
-
void (*
surrounding_text
)(void *data, struct zwp_input_method_context_v1 *zwp_input_method_context_v1, const char *text, uint32_t cursor, uint32_t anchor)¶ surrounding text event
The plain surrounding text around the input position. Cursor is the position in bytes within the surrounding text relative to the beginning of the text. Anchor is the position in bytes of the selection anchor within the surrounding text relative to the beginning of the text. If there is no selected text then anchor is the same as cursor.
-
void (*
commit_state
)(void *data, struct zwp_input_method_context_v1 *zwp_input_method_context_v1, uint32_t serial)¶ - Parameters
serial
: serial of text input state
-
void (*
-
Server Headers¶
-
group
iface_zwp_input_method_context_v1
Corresponds to a text input on the input method side.
An input method context is created on text input activation on the input method side. It allows receiving information about the text input from the application via events. Input method contexts do not keep state after deactivation and should be destroyed after deactivation is handled.
Text is generally UTF-8 encoded, indices and lengths are in bytes.
Serials are used to synchronize the state between the text input and an input method. New serials are sent by the text input in the commit_state request and are used by the input method to indicate the known text input state in events like preedit_string, commit_string, and keysym. The text input can then ignore events from the input method which are based on an outdated state (for example after a reset).
Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.
Defines
-
ZWP_INPUT_METHOD_CONTEXT_V1_SURROUNDING_TEXT_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_RESET_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_CONTENT_TYPE_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_INVOKE_ACTION_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_COMMIT_STATE_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_PREFERRED_LANGUAGE_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_DESTROY_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_COMMIT_STRING_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_PREEDIT_STRING_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_PREEDIT_STYLING_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_PREEDIT_CURSOR_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_DELETE_SURROUNDING_TEXT_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_CURSOR_POSITION_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_MODIFIERS_MAP_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_KEYSYM_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_GRAB_KEYBOARD_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_KEY_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_MODIFIERS_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_LANGUAGE_SINCE_VERSION
-
ZWP_INPUT_METHOD_CONTEXT_V1_TEXT_DIRECTION_SINCE_VERSION
Functions
-
static void
zwp_input_method_context_v1_send_surrounding_text
(struct wl_resource *resource_, const char *text, uint32_t cursor, uint32_t anchor)¶ Sends an surrounding_text event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
static void
zwp_input_method_context_v1_send_reset
(struct wl_resource *resource_)¶ Sends an reset event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
static void
zwp_input_method_context_v1_send_content_type
(struct wl_resource *resource_, uint32_t hint, uint32_t purpose)¶ Sends an content_type event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
static void
zwp_input_method_context_v1_send_invoke_action
(struct wl_resource *resource_, uint32_t button, uint32_t index)¶ Sends an invoke_action event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
static void
zwp_input_method_context_v1_send_commit_state
(struct wl_resource *resource_, uint32_t serial)¶ Sends an commit_state event to the client owning the resource.
- Parameters
resource_
: The client’s resourceserial
: serial of text input state
-
static void
zwp_input_method_context_v1_send_preferred_language
(struct wl_resource *resource_, const char *language)¶ Sends an preferred_language event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
struct
zwp_input_method_context_v1_interface
¶ - #include <input-method-server-protocol.h>
Public Members
-
void (*
commit_string
)(struct wl_client *client, struct wl_resource *resource, uint32_t serial, const char *text)¶ commit string
Send the commit string text for insertion to the application.
The text to commit could be either just a single character after a key press or the result of some composing (pre-edit). It could be also an empty text when some text should be removed (see delete_surrounding_text) or when the input cursor should be moved (see cursor_position).
Any previously set composing text will be removed.
- Parameters
serial
: serial of the latest known text input state
-
void (*
preedit_string
)(struct wl_client *client, struct wl_resource *resource, uint32_t serial, const char *text, const char *commit)¶ pre-edit string
Send the pre-edit string text to the application text input.
The commit text can be used to replace the pre-edit text on reset (for example on unfocus).
Previously sent preedit_style and preedit_cursor requests are also processed by the text_input.
- Parameters
serial
: serial of the latest known text input state
-
void (*
preedit_styling
)(struct wl_client *client, struct wl_resource *resource, uint32_t index, uint32_t length, uint32_t style)¶ pre-edit styling
Set the styling information on composing text. The style is applied for length in bytes from index relative to the beginning of the composing text (as byte offset). Multiple styles can be applied to a composing text.
This request should be sent before sending a preedit_string request.
-
void (*
preedit_cursor
)(struct wl_client *client, struct wl_resource *resource, int32_t index)¶ pre-edit cursor
Set the cursor position inside the composing text (as byte offset) relative to the start of the composing text.
When index is negative no cursor should be displayed.
This request should be sent before sending a preedit_string request.
-
void (*
delete_surrounding_text
)(struct wl_client *client, struct wl_resource *resource, int32_t index, uint32_t length)¶ delete text
Remove the surrounding text.
This request will be handled on the text_input side directly following a commit_string request.
-
void (*
cursor_position
)(struct wl_client *client, struct wl_resource *resource, int32_t index, int32_t anchor)¶ set cursor to a new position
Set the cursor and anchor to a new position. Index is the new cursor position in bytes (when >= 0 this is relative to the end of the inserted text, otherwise it is relative to the beginning of the inserted text). Anchor is the new anchor position in bytes (when >= 0 this is relative to the end of the inserted text, otherwise it is relative to the beginning of the inserted text). When there should be no selected text, anchor should be the same as index.
This request will be handled on the text_input side directly following a commit_string request.
-
void (*
keysym
)(struct wl_client *client, struct wl_resource *resource, uint32_t serial, uint32_t time, uint32_t sym, uint32_t state, uint32_t modifiers)¶ keysym
Notify when a key event was sent. Key events should not be used for normal text input operations, which should be done with commit_string, delete_surrounding_text, etc. The key event follows the wl_keyboard key event convention. Sym is an XKB keysym, state is a wl_keyboard key_state.
- Parameters
serial
: serial of the latest known text input state
-
void (*
grab_keyboard
)(struct wl_client *client, struct wl_resource *resource, uint32_t keyboard)¶ grab hardware keyboard
Allow an input method to receive hardware keyboard input and process key events to generate text events (with pre-edit) over the wire. This allows input methods which compose multiple key events for inputting text like it is done for CJK languages.
-
void (*
key
)(struct wl_client *client, struct wl_resource *resource, uint32_t serial, uint32_t time, uint32_t key, uint32_t state)¶ forward key event
Forward a wl_keyboard::key event to the client that was not processed by the input method itself. Should be used when filtering key events with grab_keyboard. The arguments should be the ones from the wl_keyboard::key event.
For generating custom key events use the keysym request instead.
- Parameters
serial
: serial from wl_keyboard::keytime
: time from wl_keyboard::keykey
: key from wl_keyboard::keystate
: state from wl_keyboard::key
-
void (*
modifiers
)(struct wl_client *client, struct wl_resource *resource, uint32_t serial, uint32_t mods_depressed, uint32_t mods_latched, uint32_t mods_locked, uint32_t group)¶ forward modifiers event
Forward a wl_keyboard::modifiers event to the client that was not processed by the input method itself. Should be used when filtering key events with grab_keyboard. The arguments should be the ones from the wl_keyboard::modifiers event.
- Parameters
serial
: serial from wl_keyboard::modifiersmods_depressed
: mods_depressed from wl_keyboard::modifiersmods_latched
: mods_latched from wl_keyboard::modifiersmods_locked
: mods_locked from wl_keyboard::modifiersgroup
: group from wl_keyboard::modifiers
-
void (*
language
)(struct wl_client *client, struct wl_resource *resource, uint32_t serial, const char *language)¶ - Parameters
serial
: serial of the latest known text input state
-
void (*
text_direction
)(struct wl_client *client, struct wl_resource *resource, uint32_t serial, uint32_t direction)¶ - Parameters
serial
: serial of the latest known text input state
-
void (*
-
zwp_input_method_v1¶
Client Headers¶
-
group
iface_zwp_input_method_v1
An input method object is responsible for composing text in response to input from hardware or virtual keyboards.
There is one input method object per seat. On activate there is a new input method context object created which allows the input method to communicate with the text input.
Functions
-
static int
zwp_input_method_v1_add_listener
(struct zwp_input_method_v1 *zwp_input_method_v1, const struct zwp_input_method_v1_listener *listener, void *data)¶
-
static void
zwp_input_method_v1_set_user_data
(struct zwp_input_method_v1 *zwp_input_method_v1, void *user_data)¶
-
static void *
zwp_input_method_v1_get_user_data
(struct zwp_input_method_v1 *zwp_input_method_v1)¶
-
static void
zwp_input_method_v1_destroy
(struct zwp_input_method_v1 *zwp_input_method_v1)¶
-
struct
zwp_input_method_v1_listener
¶ - #include <input-method-client-protocol.h>
Public Members
-
void (*
activate
)(void *data, struct zwp_input_method_v1 *zwp_input_method_v1, struct zwp_input_method_context_v1 *id)¶ activate event
A text input was activated. Creates an input method context object which allows communication with the text input.
-
void (*
deactivate
)(void *data, struct zwp_input_method_v1 *zwp_input_method_v1, struct zwp_input_method_context_v1 *context)¶ deactivate event
The text input corresponding to the context argument was deactivated. The input method context should be destroyed after deactivation is handled.
-
void (*
-
static int
Server Headers¶
-
group
iface_zwp_input_method_v1
An input method object is responsible for composing text in response to input from hardware or virtual keyboards.
There is one input method object per seat. On activate there is a new input method context object created which allows the input method to communicate with the text input.
Defines
-
ZWP_INPUT_METHOD_V1_ACTIVATE_SINCE_VERSION
-
ZWP_INPUT_METHOD_V1_DEACTIVATE_SINCE_VERSION
Functions
-
static void
zwp_input_method_v1_send_activate
(struct wl_resource *resource_, struct wl_resource *id)¶ Sends an activate event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
static void
zwp_input_method_v1_send_deactivate
(struct wl_resource *resource_, struct wl_resource *context)¶ Sends an deactivate event to the client owning the resource.
- Parameters
resource_
: The client’s resource
-
zwp_input_panel_v1¶
Client Headers¶
-
group
iface_zwp_input_panel_v1
Only one client can bind this interface at a time.
Defines
-
ZWP_INPUT_PANEL_V1_GET_INPUT_PANEL_SURFACE_SINCE_VERSION
¶
Functions
-
static void
zwp_input_panel_v1_set_user_data
(struct zwp_input_panel_v1 *zwp_input_panel_v1, void *user_data)¶
-
static void *
zwp_input_panel_v1_get_user_data
(struct zwp_input_panel_v1 *zwp_input_panel_v1)¶
-
static void
zwp_input_panel_v1_destroy
(struct zwp_input_panel_v1 *zwp_input_panel_v1)¶
-
static struct zwp_input_panel_surface_v1 *
zwp_input_panel_v1_get_input_panel_surface
(struct zwp_input_panel_v1 *zwp_input_panel_v1, struct wl_surface *surface)¶
-
Server Headers¶
-
group
iface_zwp_input_panel_v1
Only one client can bind this interface at a time.
Defines
-
ZWP_INPUT_PANEL_V1_GET_INPUT_PANEL_SURFACE_SINCE_VERSION
-
zwp_input_panel_surface_v1¶
Client Headers¶
-
group
iface_zwp_input_panel_surface_v1
Defines
-
ZWP_INPUT_PANEL_SURFACE_V1_SET_TOPLEVEL_SINCE_VERSION
¶
-
ZWP_INPUT_PANEL_SURFACE_V1_SET_OVERLAY_PANEL_SINCE_VERSION
¶
Functions
-
static void
zwp_input_panel_surface_v1_set_user_data
(struct zwp_input_panel_surface_v1 *zwp_input_panel_surface_v1, void *user_data)¶
-
static void *
zwp_input_panel_surface_v1_get_user_data
(struct zwp_input_panel_surface_v1 *zwp_input_panel_surface_v1)¶
-
static void
zwp_input_panel_surface_v1_destroy
(struct zwp_input_panel_surface_v1 *zwp_input_panel_surface_v1)¶
-
static void
zwp_input_panel_surface_v1_set_toplevel
(struct zwp_input_panel_surface_v1 *zwp_input_panel_surface_v1, struct wl_output *output, uint32_t position)¶ Set the input_panel_surface type to keyboard.
A keyboard surface is only shown when a text input is active.
-
static void
zwp_input_panel_surface_v1_set_overlay_panel
(struct zwp_input_panel_surface_v1 *zwp_input_panel_surface_v1)¶ Set the input_panel_surface to be an overlay panel.
This is shown near the input cursor above the application window when a text input is active.
-
Server Headers¶
-
group
iface_zwp_input_panel_surface_v1
Defines
-
ZWP_INPUT_PANEL_SURFACE_V1_SET_TOPLEVEL_SINCE_VERSION
-
ZWP_INPUT_PANEL_SURFACE_V1_SET_OVERLAY_PANEL_SINCE_VERSION
-
struct
zwp_input_panel_surface_v1_interface
¶ - #include <input-method-server-protocol.h>
Public Members
-
void (*
set_toplevel
)(struct wl_client *client, struct wl_resource *resource, struct wl_resource *output, uint32_t position)¶ set the surface type as a keyboard
Set the input_panel_surface type to keyboard.
A keyboard surface is only shown when a text input is active.
-
void (*
set_overlay_panel
)(struct wl_client *client, struct wl_resource *resource)¶ set the surface type as an overlay panel
Set the input_panel_surface to be an overlay panel.
This is shown near the input cursor above the application window when a text input is active.
-
void (*
-