package oxbow

  1. Overview
  2. Docs
package oxbow
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module C.River_window_v1Source

A logical window.

This represents a logical window. For example, a window may correspond to an xdg_toplevel or Xwayland window.

A newly created window will not be displayed until the window manager makes a propose_dimensions or fullscreen request as part of a manage sequence, the server replies with a dimensions event as part of a render sequence, and that render sequence is finished.

Sourcetype 'v t = ([ `River_window_v1 ], 'v, [ `Client ]) Wayland.Proxy.t
Sourcemodule Error : sig ... end
Sourcemodule Decoration_hint : sig ... end
Sourcemodule Edges : sig ... end
Sourcemodule Capabilities : sig ... end

Version 1

Sourceval exit_fullscreen : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Make the window not fullscreen.

Make the window not fullscreen.

The position and dimensions are undefined after this request is made until a manage sequence in which the window manager makes the propose_dimensions and set_position requests is completed.

The window manager should make propose_dimensions and set_position requests in the same manage sequence as the exit_fullscreen request for frame perfection.

This request does not inform the window that it is fullscreen, see the river_window_v1.inform_fullscreen and inform_not_fullscreen requests.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval fullscreen : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> output:([ `River_output_v1 ], 'a, [ `Client ]) Wayland.Proxy.t -> unit

Make the window fullscreen.

Make the window fullscreen on the given output. If multiple windows are fullscreen on the same output at the same time only the "top" window in rendering order shall be displayed.

All river_shell_surface_v1 objects above the top fullscreen window in the rendering order will continue to be rendered.

The compositor will handle the position and dimensions of the window while it is fullscreen. The set_position and propose_dimensions requests shall not affect the current position and dimensions of a fullscreen window.

When a fullscreen request is made, the server must send a dimensions event in response as soon as possible. It may not be possible to send a dimensions event in the very next render sequence if, for example, the window takes too long to respond. In this case, the server will send the dimensions event in a future render sequence.

The compositor will clip window content, decoration surfaces, and borders to the given output's dimensions while the window is fullscreen. The effects of set_clip_box and set_content_clip_box are ignored while the window is fullscreen.

If the output on which a window is currently fullscreen is removed, the windowing state is modified as if there were an exit_fullscreen request made in the same manage sequence as the river_output_v1.removed event.

This request does not inform the window that it is fullscreen, see the river_window_v1.inform_fullscreen and inform_not_fullscreen requests.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval inform_not_fullscreen : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Inform the window that it is not fullscreen.

Inform the window that it is not fullscreen. The window might use this information to adapt the style of its client-side window decorations for example.

This request does not affect the size/position of the window or cause it to become the only window rendered, see the river_window_v1.fullscreen and exit_fullscreen requests for that.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval inform_fullscreen : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Inform the window that it is fullscreen.

Inform the window that it is fullscreen. The window might use this information to adapt the style of its client-side window decorations for example.

This request does not affect the size/position of the window or cause it to become the only window rendered, see the river_window_v1.fullscreen and exit_fullscreen requests for that.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval inform_unmaximized : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Inform the window that it is unmaximized.

Inform the window that it is unmaximized. The window might use this information to adapt the style of its client-side window decorations for example.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval inform_maximized : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Inform the window that it is maximized.

Inform the window that it is maximized. The window might use this information to adapt the style of its client-side window decorations for example.

The window manager remains responsible for handling the position and dimensions of the window while it is maximized.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval set_capabilities : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> caps:int32 -> unit

Inform window of supported capabilities.

This request informs the window of the capabilities supported by the window manager. If the window manager, for example, ignores requests to be maximized from the window it should not tell the window that it supports the maximize capability.

The window might use this information to, for example, only show a maximize button if the window manager supports the maximize capability.

The window manager client should use this request to set capabilities for all new windows. If this request is never made, the compositor will inform windows that all capabilities are supported.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval inform_resize_end : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Inform the window it no longer being resized.

Inform the window that it is no longer being resized. The window manager should use this request to inform windows that are the target of an interactive resize that the interactive resize has ended for example.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval inform_resize_start : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Inform the window it is being resized.

Inform the window that it is being resized. The window manager should use this request to inform windows that are the target of an interactive resize for example.

The window manager remains responsible for handling the position and dimensions of the window while it is resizing.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval get_decoration_below : ([< `V1 | `V2 | `V3 | `V4 | `V5 ] as 'a) t -> [[ `River_decoration_v1 ], 'a, [ `Client ]] Wayland.Proxy.Handler.t -> surface:([ `Wl_surface ], 'b, [ `Client ]) Wayland.Proxy.t -> ([ `River_decoration_v1 ], 'a, [ `Client ]) Wayland.Proxy.t

Create a decoration below the window in z-order.

Create a decoration surface and assign the river_decoration_v1 role to the surface. The created decoration is placed below the window in rendering order, see the description of river_decoration_v1.

Providing a wl_surface which already has a role or already has a buffer attached or committed is a protocol error.

Sourceval get_decoration_above : ([< `V1 | `V2 | `V3 | `V4 | `V5 ] as 'a) t -> [[ `River_decoration_v1 ], 'a, [ `Client ]] Wayland.Proxy.Handler.t -> surface:([ `Wl_surface ], 'b, [ `Client ]) Wayland.Proxy.t -> ([ `River_decoration_v1 ], 'a, [ `Client ]) Wayland.Proxy.t

Create a decoration above the window in z-order.

Create a decoration surface and assign the river_decoration_v1 role to the surface. The created decoration is placed above the window in rendering order, see the description of river_decoration_v1.

Providing a wl_surface which already has a role or already has a buffer attached or committed is a protocol error.

Sourceval set_tiled : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> edges:int32 -> unit

Set window tiled state.

Inform the window that it is part of a tiled layout and adjacent to other elements in the tiled layout on the given edges.

The window should use this information to change the style of its client side decorations and avoid drawing e.g. drop shadows outside of the window dimensions on the tiled edges.

Setting the edges argument to none informs the window that it is not part of a tiled layout. If this request is never made, the window is informed that it is not part of a tiled layout.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval set_borders : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> edges:int32 -> width:int32 -> r:int32 -> g:int32 -> b:int32 -> a:int32 -> unit

Set window borders.

This request decorates the window with borders drawn by the compositor on the specified edges of the window. Borders are drawn above the window content.

Corners are drawn only between borders on adjacent edges. If e.g. the left edge has a border and the top edge does not, the border drawn on the left edge will not extend vertically beyond the top edge of the window.

Borders are not drawn while the window is fullscreen.

The color is defined by four 32-bit RGBA values. Unless specified in another protocol extension, the RGBA values use pre-multiplied alpha.

The valid range for the RGBA values is from 0x00000000 to 0xffffffff. These values are interpreted as a percentage:

  • 0x00000000 means 0% of the given color component
  • 0xffffffff means 100% of the given color component

Setting the edges to none or the width to 0 disables the borders. Setting a negative width is a protocol error.

This request completely overrides all previous set_borders requests. Only the most recent set_borders request has an effect.

Note that the position/dimensions of a river_window_v1 refer to the position/dimensions of the window content and are unaffected by the presence of borders or decoration surfaces.

This request modifies rendering state and may only be made as part of a render sequence, see the river_window_manager_v1 description.

Sourceval use_ssd : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Tell the client to use SSD.

Tell the client to use server side decoration and not draw any client side decorations.

This request will have no effect if the client only supports client side decoration, see the decoration_hint event.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval use_csd : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Tell the client to use CSD.

Tell the client to use client side decoration and draw its own title bar, borders, etc.

This is the default if neither this request nor the use_ssd request is ever made.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval show : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Request that the window be shown.

Request that the window be shown. Has no effect if the window is not hidden. Does not guarantee that the window is visible as it may be completely obscured by other windows placed above it for example.

Newly created windows are considered shown unless explicitly hidden with the hide request.

This request modifies rendering state and may only be made as part of a render sequence, see the river_window_manager_v1 description.

Sourceval hide : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Request that the window be hidden.

Request that the window be hidden. Has no effect if the window is already hidden. Hides any window borders and decorations as well.

Newly created windows are considered shown unless explicitly hidden with the hide request.

This request modifies rendering state and may only be made as part of a render sequence, see the river_window_manager_v1 description.

Sourceval propose_dimensions : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> width:int32 -> height:int32 -> unit

Propose window dimensions.

This request proposes dimensions for the window in the compositor's logical coordinate space.

The width and height must be greater than or equal to zero. If the width or height is zero the window will be allowed to decide its own dimensions.

The window may not take the exact dimensions proposed. The actual dimensions taken by the window will be sent in a subsequent river_window_v1.dimensions event. For example, a terminal emulator may only allow dimensions that are multiple of the cell size.

When a propose_dimensions request is made, the server must send a dimensions event in response as soon as possible. It may not be possible to send a dimensions event in the very next render sequence if, for example, the window takes too long to respond to the proposed dimensions. In this case, the server will send the dimensions event in a future render sequence.

Note that the dimensions of a river_window_v1 refer to the dimensions of the window content and are unaffected by the presence of borders or decoration surfaces.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval get_node : ([< `V1 | `V2 | `V3 | `V4 | `V5 ] as 'a) t -> [[ `River_node_v1 ], 'a, [ `Client ]] Wayland.Proxy.Handler.t -> ([ `River_node_v1 ], 'a, [ `Client ]) Wayland.Proxy.t

Get the window's render list node.

Get the node in the render list corresponding to the window.

It is a protocol error to make this request more than once for a single window.

Sourceval close : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Request that the window be closed.

Request that the window be closed. The window may ignore this request or only close after some delay, perhaps opening a dialog asking the user to save their work or similar.

The server will send a river_window_v1.closed event if/when the window has been closed.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Sourceval destroy : [< `V1 | `V2 | `V3 | `V4 | `V5 ] t -> unit

Destroy the window object.

This request indicates that the client will no longer use the window object and that it may be safely destroyed.

This request should be made after the river_window_v1.closed event or river_window_manager_v1.finished is received to complete destruction of the window.

Version 2

Sourceval set_clip_box : [< `V2 | `V3 | `V4 | `V5 ] t -> x:int32 -> y:int32 -> width:int32 -> height:int32 -> unit

Clip the window to a given box.

Clip the window, including borders and decoration surfaces, to the box specified by the x, y, width, and height arguments. The x/y position of the box is relative to the top left corner of the window.

The width and height arguments must be greater than or equal to 0.

Setting a clip box with 0 width or height disables clipping.

The clip box is ignored while the window is fullscreen.

Both set_clip_box and set_content_clip_box may be enabled simultaneously.

This request modifies rendering state and may only be made as part of a render sequence, see the river_window_manager_v1 description.

Version 3

Sourceval set_content_clip_box : [< `V3 | `V4 | `V5 ] t -> x:int32 -> y:int32 -> width:int32 -> height:int32 -> unit

Clip the window content to a given box.

Clip the content of the window, excluding borders and decoration surfaces, to the box specified by the x, y, width, and height arguments. The x/y position of the box is relative to the top left corner of the window.

Borders drawn by the compositor (see set_borders) are placed around the intersection of the window content (as defined by the dimensions event) and the content clip box when content clipping is enabled.

The width and height arguments must be greater than or equal to 0.

Setting a box with 0 width or height disables content clipping.

The content clip box is ignored while the window is fullscreen.

Both set_clip_box and set_content_clip_box may be enabled simultaneously.

This request modifies rendering state and may only be made as part of a render sequence, see the river_window_manager_v1 description.

Version 4

Sourceval set_dimension_bounds : [< `V4 | `V5 ] t -> max_width:int32 -> max_height:int32 -> unit

Recommend maximum dimensions to the window.

Recommend that the window keep its dimensions within a given maximum width/height. This recommendation is only a hint and the window may ignore it.

Setting the width and height to 0 indicates that there are no bounds and is equivalent to having never made this request.

Setting width or height to a negative value is a protocol error.

The server should communicate this hint to an xdg_toplevel window with the xdg_toplevel.configure_bounds event for example.

This request modifies window management state and may only be made as part of a manage sequence, see the river_window_manager_v1 description.

Version 5

Handlers

Note: Servers will always want to use v1.

Sourceclass virtual +'a v1 : object ... end

Handler for a proxy with version >= 1.

Sourceclass virtual +'a v2 : object ... end

Handler for a proxy with version >= 2.

Sourceclass virtual +'a v3 : object ... end

Handler for a proxy with version >= 3.

Sourceclass virtual +'a v4 : object ... end

Handler for a proxy with version >= 4.

Sourceclass virtual +'a v5 : object ... end

Handler for a proxy with version >= 5.