ext_tray_v1
ext_tray_v1
This is a global that advertises a tray area. It allows clients to displays items in the tray.
The compositor can advertise multiple globals of this interface. For example, if there are multiple outputs with one tray area each. In that case, clients that want to display tray items should bind to and use all of these globals.
The compositor can remove this global at any time. For example, when an output containing a tray area is disconnected. In that case, the items created from the global will no longer be displayed and the client should destroy all associated objects.
Warning! The protocol described in this file is currently in the testing phase. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes can only be done by creating a new major version of the extension.
destroy()
Destroy this object.
Created tray items are not affected by this.
get_tray_item(id: new_id<ext_tray_item_v1>, surface: object<wl_surface>)
Argument | Type | Description |
|---|---|---|
| id | new_id<ext_tray_item_v1> | the new tray item |
| surface | object<wl_surface> | the underlying surface |
Create a tray item for a surface.
The surface is assigned the ext-tray-item-v1 role. If the surface already has another role, the conflicting_role error is emitted.
If the surface already has a role object, the already_exists error is emitted.
error { conflicting_role, already_exists }
Argument | Value | Description |
|---|---|---|
| conflicting_role | 0 | the surface already has another role |
| already_exists | 1 | tray item already exists for the surface |
These fatal protocol errors may be emitted in response to invalid requests.
ext_tray_item_v1
This interface represents an item in a tray. The underlying surface will be displayed in the tray.
Unless the global has been removed, the compositor will immediately emit a configuration sequence after this object has been created. If applicable, the sequence will also contain wl_surface.preferred_buffer_scale and wp_fractional_scale_v1.preferred_scale events.
After receiving the configuration sequence, the client must ack the configuration and commit the surface. The item will not be displayed before this.
The compositor can send configuration sequences at any point.
If a null buffer is committed, the item will not be displayed. If the client wants the item to be displayed, it must ack and commit the latest configuration sequence and attach and commit a non-null buffer.
destroy()
Destroy this object. The item is immediately removed from the tray.
The client must destroy all popups before this. Otherwise the has_popups error is emitted.
ack_configure(serial: uint)
Argument | Type | Description |
|---|---|---|
| serial | uint | the serial |
Ack a configuration sequence. The acked configuration sequence is double-buffered state, see wl_surface.commit. If the compositor has never sent this serial, an invalid_configure_serial error is emitted.
get_popup(popup: object<xdg_popup>, seat: object<wl_seat>, serial: uint, focus_hint: uint<ext_tray_item_v1.keyboard_focus_hint>)
Argument | Type | Description |
|---|---|---|
| popup | object<xdg_popup> | the popup to be shown |
| seat | object<wl_seat> | the causal seat |
| serial | uint | the causal input serial |
| focus_hint | uint<ext_tray_item_v1.keyboard_focus_hint> | a hint for keyboard focus handling |
Create a popup for a tray item.
The popup should have been created with a null parent. If the popup already has a parent, the has_parent error is emitted.
The seat and serial indicate the interaction that causes this popup to be shown. If the compositor has never sent this serial, the compositor might emit the invalid_seat_serial error. This is compositor policy. If the focus_hint is invalid, the invalid_keyboard_focus_hint error is emitted.
The focus hint indicates how the client wants keyboard focus to be handled for the popup. The compositor may ignore the hint. This hint has no effect on nested popups.
The compositor may dismiss the popup at any point.
Argument | Type | Description |
|---|---|---|
| width | int | the optimal width in surface coordinates |
| height | int | the optimal height in surface coordinates |
This event is sent when the optimal size for the item has changed. This event is part of a configuration sequence that is terminated with a configure event. The client should not act on it immediately but wait for the configure event.
When the client receives this event, it should reconfigure the surface for the new size, ack the sequence, and commit the surface.
If the surface has a different size, the compositor might crop or stretch the surface. If the surface has subsurfaces that extend beyond the edges of the surface, the compositor might crop them.
The width and height are at least 1.
If a configuration sequence does not contain this event, the client should assume that the value is unchanged. The first configuration sequence must contain this event.
preferred_anchor(anchor: uint<xdg_positioner.anchor>)
Argument | Type | Description |
|---|---|---|
| anchor | uint<xdg_positioner.anchor> | the preferred anchor |
This events is sent when the preferred anchor for popup windows changes. This event is part of a configuration sequence that is terminated with a configure event. The client should not act on it immediately but wait for the configure event.
If a configuration sequence does not contain this event, the client should assume that the value is unchanged. The first configuration sequence must contain this event.
preferred_gravity(gravity: uint<xdg_positioner.gravity>)
Argument | Type | Description |
|---|---|---|
| gravity | uint<xdg_positioner.gravity> | the preferred gravity |
This events is sent when the preferred gravity for popup windows changes. This event is part of a configuration sequence that is terminated with a configure event. The client should not act on it immediately but wait for the configure event.
If a configuration sequence does not contain this event, the client should assume that the value is unchanged. The first configuration sequence must contain this event.
configure(serial: uint)
Argument | Type | Description |
|---|---|---|
| serial | uint | the serial |
This event marks the end of a configuration sequence. The client should act on the new parameters, ack the sequence, and commit the surface.
Note that this serial is not related to the wl_seat serial used in get_popup requests.
error { has_popups, has_parent, invalid_seat_serial, invalid_configure_serial, invalid_keyboard_focus_hint }
Argument | Value | Description |
|---|---|---|
| has_popups | 0 | the item has popups at destroy time |
| has_parent | 1 | the popup already has a parent |
| invalid_seat_serial | 2 | invalid serial provided to get_popup |
| invalid_configure_serial | 3 | invalid serial provided to ack_configure |
| invalid_keyboard_focus_hint | 4 | invalid keyboard focus hint provided to get_popup |
These fatal protocol errors may be emitted in response to invalid requests.
Argument | Value | Description |
|---|---|---|
| none | 0 | no keyboard focus The popup should never get the keyboard focus. |
| on_demand | 1 | on demand keyboard focus The popup should get the keyboard focus when the user requests it. |
| immediate | 2 | immediate keyboard focus The popup should get the keyboard focus as soon as it becomes visible. |
This enum describes when a popup used in the get_popup request should get keyboard focus.
Compositor Support
Copyright
Copyright © 2024 Julian Orth
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.