.TH "wayland::xdg_surface_t" 3 "Wed May 3 2023" "Version 1.0.0" "Wayland++" \" -*- nroff -*- .ad l .nh .SH NAME wayland::xdg_surface_t \- desktop user interface surface base interface .SH SYNOPSIS .br .PP .PP \fC#include \fP .PP Inherits \fBwayland::proxy_t\fP\&. .SS "Public Types" .in +1c .ti -1c .RI "enum class \fBwrapper_type\fP { \fBstandard\fP, \fBdisplay\fP, \fBforeign\fP, \fBproxy_wrapper\fP }" .br .in -1c .SS "Public Member Functions" .in +1c .ti -1c .RI "\fBxdg_toplevel_t\fP \fBget_toplevel\fP ()" .br .RI "assign the xdg_toplevel surface role " .ti -1c .RI "\fBxdg_popup_t\fP \fBget_popup\fP (\fBxdg_surface_t\fP const &parent, \fBxdg_positioner_t\fP const &positioner)" .br .RI "assign the xdg_popup surface role " .ti -1c .RI "void \fBset_window_geometry\fP (int32_t x, int32_t y, int32_t width, int32_t height)" .br .RI "set the new window geometry " .ti -1c .RI "void \fBack_configure\fP (uint32_t serial)" .br .RI "ack a configure event " .ti -1c .RI "std::function< void(uint32_t)> & \fBon_configure\fP ()" .br .RI "suggest a surface change " .ti -1c .RI "uint32_t \fBget_id\fP () const" .br .RI "Get the id of a proxy object\&. " .ti -1c .RI "std::string \fBget_class\fP () const" .br .RI "Get the interface name (class) of a proxy object\&. " .ti -1c .RI "uint32_t \fBget_version\fP () const" .br .RI "Get the protocol object version of a proxy object\&. " .ti -1c .RI "\fBwrapper_type\fP \fBget_wrapper_type\fP () const" .br .RI "Get the type of a proxy object\&. " .ti -1c .RI "void \fBset_queue\fP (\fBevent_queue_t\fP queue)" .br .RI "Assign a proxy to an event queue\&. " .ti -1c .RI "wl_proxy * \fBc_ptr\fP () const" .br .RI "Get a pointer to the underlying C struct\&. " .ti -1c .RI "bool \fBproxy_has_object\fP () const" .br .RI "Check whether this wrapper actually wraps an object\&. " .ti -1c .RI "\fBoperator bool\fP () const" .br .RI "Check whether this wrapper actually wraps an object\&. " .ti -1c .RI "bool \fBoperator==\fP (const \fBproxy_t\fP &right) const" .br .RI "Check whether two wrappers refer to the same object\&. " .ti -1c .RI "bool \fBoperator!=\fP (const \fBproxy_t\fP &right) const" .br .RI "Check whether two wrappers refer to different objects\&. " .ti -1c .RI "void \fBproxy_release\fP ()" .br .RI "Release the wrapped object (if any), making this an empty wrapper\&. " .in -1c .SS "Static Public Attributes" .in +1c .ti -1c .RI "static constexpr std::uint32_t \fBget_toplevel_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBget_toplevel\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBget_popup_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBget_popup\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBset_window_geometry_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBset_window_geometry\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBack_configure_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBack_configure\fP function\&. " .in -1c .SH "Detailed Description" .PP desktop user interface surface base interface An interface that may be implemented by a wl_surface, for implementations that provide a desktop-style user interface\&. .PP It provides a base set of functionality required to construct user interface elements requiring management by the compositor, such as toplevel windows, menus, etc\&. The types of functionality are split into xdg_surface roles\&. .PP Creating an xdg_surface does not set the role for a wl_surface\&. In order to map an xdg_surface, the client must create a role-specific object using, e\&.g\&., get_toplevel, get_popup\&. The wl_surface for any given xdg_surface can have at most one role, and may not be assigned any role not based on xdg_surface\&. .PP A role must be assigned before any other requests are made to the xdg_surface object\&. .PP The client must call wl_surface\&.commit on the corresponding wl_surface for the xdg_surface state to take effect\&. .PP Creating an xdg_surface from a wl_surface which has a buffer attached or committed is a client error, and any attempts by a client to attach or manipulate a buffer prior to the first xdg_surface\&.configure call must also be treated as errors\&. .PP After creating a role-specific object and setting it up, the client must perform an initial commit without any buffer attached\&. The compositor will reply with an xdg_surface\&.configure event\&. The client must acknowledge it and is then allowed to attach a buffer to map the surface\&. .PP Mapping an xdg_surface-based role surface is defined as making it possible for the surface to be shown by the compositor\&. Note that a mapped surface is not guaranteed to be visible once it is mapped\&. .PP For an xdg_surface to be mapped by the compositor, the following conditions must be met: (1) the client has assigned an xdg_surface-based role to the surface (2) the client has set and committed the xdg_surface state and the role-dependent state to the surface (3) the client has committed a buffer to the surface .PP A newly-unmapped surface is considered to have met condition (1) out of the 3 required conditions for mapping a surface if its role surface has not been destroyed, i\&.e\&. the client must perform the initial commit again before attaching a buffer\&. .PP \fBExamples\fP .in +1c \fBegl\&.cpp\fP, and \fBshm\&.cpp\fP\&. .PP Definition at line \fB1001\fP of file \fBwayland\-client\-protocol\-extra\&.hpp\fP\&. .SH "Member Enumeration Documentation" .PP .SS "enum class \fBwayland::proxy_t::wrapper_type\fP\fC [strong]\fP, \fC [inherited]\fP" Underlying wl_proxy type and properties of a \fBproxy_t\fP that affect construction, destruction, and event handling .PP \fBEnumerator\fP .in +1c .TP \fB\fIstandard \fP\fP C pointer is a standard type compatible with wl_proxy*\&. Events are dispatched and it is destructed when the \fBproxy_t\fP is destructed\&. User data is set\&. .TP \fB\fIdisplay \fP\fP C pointer is a wl_display*\&. No events are dispatched, wl_display_disconnect is called when the \fBproxy_t\fP is destructed\&. User data is set\&. .TP \fB\fIforeign \fP\fP C pointer is a standard type compatible with wl_proxy*, but another library owns it and it should not be touched in a way that could affect the operation of the other library\&. No events are dispatched, wl_proxy_destroy is not called when the \fBproxy_t\fP is destructed, user data is not touched\&. Consequently, there is no reference counting for the \fBproxy_t\fP\&. Lifetime of such wrappers should preferably be short to minimize the chance that the owning library decides to destroy the wl_proxy\&. .TP \fB\fIproxy_wrapper \fP\fP C pointer is a wl_proxy* that was constructed with wl_proxy_create_wrapper\&. No events are dispatched, wl_proxy_wrapper_destroy is called when the \fBproxy_t\fP is destroyed\&. Reference counting is active\&. A reference to the \fBproxy_t\fP creating this proxy wrapper is held to extend its lifetime until after the proxy wrapper is destroyed\&. .PP Definition at line \fB115\fP of file \fBwayland\-client\&.hpp\fP\&. .SH "Member Function Documentation" .PP .SS "void xdg_surface_t::ack_configure (uint32_t serial)" .PP ack a configure event .PP \fBParameters\fP .RS 4 \fIserial\fP the serial from the configure event .RE .PP When a configure event is received, if a client commits the surface in response to the configure event, then the client must make an ack_configure request sometime before the commit request, passing along the serial of the configure event\&. .PP For instance, for toplevel surfaces the compositor might use this information to move a surface to the top left only when the client has drawn itself for the maximized or fullscreen state\&. .PP If the client receives multiple configure events before it can respond to one, it only has to ack the last configure event\&. .PP A client is not required to commit immediately after sending an ack_configure request - it may even ack_configure several times before its next surface commit\&. .PP A client may send multiple ack_configure requests before committing, but only the last request sent before a commit indicates which configure event the client really is responding to\&. .PP \fBExamples\fP .in +1c \fBegl\&.cpp\fP, and \fBshm\&.cpp\fP\&. .PP Definition at line \fB1261\fP of file \fBwayland\-client\-protocol\-extra\&.cpp\fP\&. .SS "wl_proxy * wayland::proxy_t::c_ptr () const\fC [inherited]\fP" .PP Get a pointer to the underlying C struct\&. .PP \fBReturns\fP .RS 4 The underlying wl_proxy wrapped by this \fBproxy_t\fP if it exists, otherwise an exception is thrown .RE .PP .SS "std::string wayland::proxy_t::get_class () const\fC [inherited]\fP" .PP Get the interface name (class) of a proxy object\&. .PP \fBReturns\fP .RS 4 The interface name of the object associated with the proxy .RE .PP .SS "uint32_t wayland::proxy_t::get_id () const\fC [inherited]\fP" .PP Get the id of a proxy object\&. .PP \fBReturns\fP .RS 4 The id the object associated with the proxy .RE .PP .SS "\fBxdg_popup_t\fP xdg_surface_t::get_popup (\fBxdg_surface_t\fP const & parent, \fBxdg_positioner_t\fP const & positioner)" .PP assign the xdg_popup surface role .PP \fBParameters\fP .RS 4 \fIparent\fP .br \fIpositioner\fP .RE .PP This creates an xdg_popup object for the given xdg_surface and gives the associated wl_surface the xdg_popup role\&. .PP If null is passed as a parent, a parent surface must be specified using some other protocol, before committing the initial state\&. .PP See the documentation of xdg_popup for more details about what an xdg_popup is and how it is used\&. .PP Definition at line \fB1248\fP of file \fBwayland\-client\-protocol\-extra\&.cpp\fP\&. .SS "\fBxdg_toplevel_t\fP xdg_surface_t::get_toplevel ()" .PP assign the xdg_toplevel surface role This creates an xdg_toplevel object for the given xdg_surface and gives the associated wl_surface the xdg_toplevel role\&. .PP See the documentation of xdg_toplevel for more details about what an xdg_toplevel is and how it is used\&. .PP \fBExamples\fP .in +1c \fBegl\&.cpp\fP, and \fBshm\&.cpp\fP\&. .PP Definition at line \fB1241\fP of file \fBwayland\-client\-protocol\-extra\&.cpp\fP\&. .SS "uint32_t wayland::proxy_t::get_version () const\fC [inherited]\fP" .PP Get the protocol object version of a proxy object\&. Gets the protocol object version of a proxy object, or 0 if the proxy was created with unversioned API\&. .PP A returned value of 0 means that no version information is available, so the caller must make safe assumptions about the object's real version\&. .PP \fBdisplay_t\fP will always return version 0\&. .PP \fBReturns\fP .RS 4 The protocol object version of the proxy or 0 .RE .PP .SS "\fBwrapper_type\fP wayland::proxy_t::get_wrapper_type () const\fC [inline]\fP, \fC [inherited]\fP" .PP Get the type of a proxy object\&. .PP Definition at line \fB301\fP of file \fBwayland\-client\&.hpp\fP\&. .SS "std::function< void(uint32_t)> & xdg_surface_t::on_configure ()" .PP suggest a surface change .PP \fBParameters\fP .RS 4 \fIserial\fP serial of the configure event .RE .PP The configure event marks the end of a configure sequence\&. A configure sequence is a set of one or more events configuring the state of the xdg_surface, including the final xdg_surface\&.configure event\&. .PP Where applicable, xdg_surface surface roles will during a configure sequence extend this event as a latched state sent as events before the xdg_surface\&.configure event\&. Such events should be considered to make up a set of atomically applied configuration states, where the xdg_surface\&.configure commits the accumulated state\&. .PP Clients should arrange their surface for the new states, and then send an ack_configure request with the serial sent in this configure event at some point before committing the new surface\&. .PP If the client receives multiple configure events before it can respond to one, it is free to discard all but the last event it received\&. .PP \fBExamples\fP .in +1c \fBegl\&.cpp\fP, and \fBshm\&.cpp\fP\&. .PP Definition at line \fB1267\fP of file \fBwayland\-client\-protocol\-extra\&.cpp\fP\&. .SS "wayland::proxy_t::operator bool () const\fC [inherited]\fP" .PP Check whether this wrapper actually wraps an object\&. .PP \fBReturns\fP .RS 4 true if there is an underlying object, false if this wrapper is empty .RE .PP .SS "bool wayland::proxy_t::operator!= (const \fBproxy_t\fP & right) const\fC [inherited]\fP" .PP Check whether two wrappers refer to different objects\&. .SS "bool wayland::proxy_t::operator== (const \fBproxy_t\fP & right) const\fC [inherited]\fP" .PP Check whether two wrappers refer to the same object\&. .SS "bool wayland::proxy_t::proxy_has_object () const\fC [inherited]\fP" .PP Check whether this wrapper actually wraps an object\&. .PP \fBReturns\fP .RS 4 true if there is an underlying object, false if this wrapper is empty .RE .PP .SS "void wayland::proxy_t::proxy_release ()\fC [inherited]\fP" .PP Release the wrapped object (if any), making this an empty wrapper\&. Note that \fBdisplay_t\fP instances cannot be released this way\&. Attempts to do so are ignored\&. .PP \fBExamples\fP .in +1c \fBforeign_display\&.cpp\fP\&. .SS "void wayland::proxy_t::set_queue (\fBevent_queue_t\fP queue)\fC [inherited]\fP" .PP Assign a proxy to an event queue\&. .PP \fBParameters\fP .RS 4 \fIqueue\fP The event queue that will handle this proxy .RE .PP Assign proxy to event queue\&. Events coming from proxy will be queued in queue instead of the display's main queue\&. .PP See also: \fBdisplay_t::dispatch_queue()\fP\&. .PP \fBExamples\fP .in +1c \fBproxy_wrapper\&.cpp\fP\&. .SS "void xdg_surface_t::set_window_geometry (int32_t x, int32_t y, int32_t width, int32_t height)" .PP set the new window geometry .PP \fBParameters\fP .RS 4 \fIx\fP .br \fIy\fP .br \fIwidth\fP .br \fIheight\fP .RE .PP The window geometry of a surface is its 'visible bounds' from the user's perspective\&. Client-side decorations often have invisible portions like drop-shadows which should be ignored for the purposes of aligning, placing and constraining windows\&. .PP The window geometry is double buffered, and will be applied at the time wl_surface\&.commit of the corresponding wl_surface is called\&. .PP When maintaining a position, the compositor should treat the (x, y) coordinate of the window geometry as the top left corner of the window\&. A client changing the (x, y) window geometry coordinate should in general not alter the position of the window\&. .PP Once the window geometry of the surface is set, it is not possible to unset it, and it will remain the same until set_window_geometry is called again, even if a new subsurface or buffer is attached\&. .PP If never set, the value is the full bounds of the surface, including any subsurfaces\&. This updates dynamically on every commit\&. This unset is meant for extremely simple clients\&. .PP The arguments are given in the surface-local coordinate space of the wl_surface associated with this xdg_surface\&. .PP The width and height must be greater than zero\&. Setting an invalid size will raise an error\&. When applied, the effective window geometry will be the set window geometry clamped to the bounding rectangle of the combined geometry of the surface of the xdg_surface and the associated subsurfaces\&. .PP Definition at line \fB1255\fP of file \fBwayland\-client\-protocol\-extra\&.cpp\fP\&. .SH "Member Data Documentation" .PP .SS "constexpr std::uint32_t wayland::xdg_surface_t::ack_configure_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBack_configure\fP function\&. .PP Definition at line \fB1130\fP of file \fBwayland\-client\-protocol\-extra\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::xdg_surface_t::get_popup_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBget_popup\fP function\&. .PP Definition at line \fB1057\fP of file \fBwayland\-client\-protocol\-extra\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::xdg_surface_t::get_toplevel_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBget_toplevel\fP function\&. .PP Definition at line \fB1037\fP of file \fBwayland\-client\-protocol\-extra\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::xdg_surface_t::set_window_geometry_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBset_window_geometry\fP function\&. .PP Definition at line \fB1100\fP of file \fBwayland\-client\-protocol\-extra\&.hpp\fP\&. .SH "Author" .PP Generated automatically by Doxygen for Wayland++ from the source code\&.