Lines Matching full:the
11 copy of this software and associated documentation files (the "Software"),
12 to deal in the Software without restriction, including without limitation
13 the rights to use, copy, modify, merge, publish, distribute, sublicense,
14 and/or sell copies of the Software, and to permit persons to whom the
15 Software is furnished to do so, subject to the following conditions:
17 The above copyright notice and this permission notice (including the next
18 paragraph) shall be included in all copies or substantial portions of the
21 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27 DEALINGS IN THE SOFTWARE.
33 which can be dragged, resized, stacked, and moved around by the
43 summary="the client tried to map or destroy a non-topmost popup"/>
45 summary="the client specified an invalid popup parent surface"/>
47 summary="the client provided an invalid surface state"/>
49 summary="the client provided an invalid positioner"/>
65 surfaces relative to some parent surface. See the interface description
73 This creates an xdg_surface for the given surface. While xdg_surface
74 itself is not a role, the corresponding surface may only be assigned
77 This creates an xdg_surface for the given surface. An xdg_surface is
82 See the documentation of xdg_surface for more details about what an
92 the client may be deemed unresponsive. See xdg_shell.ping.
94 <arg name="serial" type="uint" summary="serial of the ping event"/>
98 <description summary="check if the client is alive">
99 The ping event asks the client if it's still alive. Pass the
100 serial specified in the event back to the compositor by sending
101 a "pong" request back with the specified serial. See xdg_shell.ping.
103 Compositors can use this to determine if the client is still
104 alive. It's unspecified what will happen if the client doesn't
105 respond to the ping request, or in what timeframe. Clients should
111 <arg name="serial" type="uint" summary="pass this to the pong request"/>
117 The xdg_positioner provides a collection of rules for the placement of a
119 the child surface remains within the visible area's borders, and to
120 specify how the child surface changes its position, such as sliding along
122 constrained by the requirement that a child surface must intersect with or
125 See the various requests for details about possible rules.
127 At the time of the request, the compositor makes a copy of the rules
128 specified by the xdg_positioner. Thus, after the request is complete the
129 xdg_positioner object can be destroyed or reused; further changes to the
143 <description summary="destroy the xdg_positioner object">
144 Notify the compositor that the xdg_positioner will no longer be used.
149 <description summary="set the size of the to-be positioned rectangle">
150 Set the size of the surface that is to be positioned with the positioner
151 object. The size is in surface-local coordinates and corresponds to the
154 If a zero or negative size is set the invalid_input error is raised.
161 <description summary="set the anchor rectangle within the parent surface">
162 Specify the anchor rectangle within the parent surface that the child
163 surface will be placed relative to. The rectangle is relative to the
164 window geometry as defined by xdg_surface.set_window_geometry of the
165 parent surface. The rectangle must be at least 1x1 large.
167 When the xdg_positioner object is used to position a child surface, the
168 anchor rectangle may not extend outside the window geometry of the
171 If a zero or negative size is set the invalid_input error is raised.
181 summary="the center of the anchor rectangle"/>
183 summary="the top edge of the anchor rectangle"/>
185 summary="the bottom edge of the anchor rectangle"/>
187 summary="the left edge of the anchor rectangle"/>
189 summary="the right edge of the anchor rectangle"/>
194 Defines a set of edges for the anchor rectangle. These are used to
195 derive an anchor point that the child surface will be positioned
197 'left'), then the anchor point will be the intersection of the edges
198 (e.g. the top left position of the rectangle); otherwise, the derived
199 anchor point will be centered on the specified edge, or in the center of
200 the anchor rectangle if no edge is specified.
203 the invalid_input error is raised.
211 summary="center over the anchor edge"/>
213 summary="position above the anchor edge"/>
215 summary="position below the anchor edge"/>
217 summary="position to the left of the anchor edge"/>
219 summary="position to the right of the anchor edge"/>
225 the anchor point of the parent surface. If two orthogonal gravities are
226 specified (e.g. 'bottom' and 'right'), then the child surface will be
227 placed in the specified direction; otherwise, the child surface will be
228 centered over the anchor point on any axis that had no gravity
231 If two parallel gravities are specified (e.g. 'left' and 'right'), the
240 The constraint adjustment value define ways the compositor will adjust
241 the position of the surface, if the unadjusted position would result
242 in the surface being partly constrained.
244 Whether a surface is considered 'constrained' is left to the compositor
245 to determine. For example, the surface may be partly outside the
246 compositor's defined 'work area', thus necessitating the child surface's
247 position be adjusted until it is entirely inside the work area.
249 The adjustments can be combined, according to a defined precedence: 1)
253 <description summary="don't move the child surface when constrained">
254 Don't alter the surface position even if it is constrained on some
255 axis, for example partially outside the edge of a monitor.
259 <description summary="move along the x axis until unconstrained">
260 Slide the surface along the x axis until it is no longer constrained.
262 First try to slide towards the direction of the gravity on the x axis
263 until either the edge in the opposite direction of the gravity is
264 unconstrained or the edge in the direction of the gravity is
267 Then try to slide towards the opposite direction of the gravity on the
268 x axis until either the edge in the direction of the gravity is
269 unconstrained or the edge in the opposite direction of the gravity is
274 <description summary="move along the y axis until unconstrained">
275 Slide the surface along the y axis until it is no longer constrained.
277 First try to slide towards the direction of the gravity on the y axis
278 until either the edge in the opposite direction of the gravity is
279 unconstrained or the edge in the direction of the gravity is
282 Then try to slide towards the opposite direction of the gravity on the
283 y axis until either the edge in the direction of the gravity is
284 unconstrained or the edge in the opposite direction of the gravity is
289 <description summary="invert the anchor and gravity on the x axis">
290 Invert the anchor and gravity on the x axis if the surface is
291 constrained on the x axis. For example, if the left edge of the
292 surface is constrained, the gravity is 'left' and the anchor is
293 'left', change the gravity to 'right' and the anchor to 'right'.
295 If the adjusted position also ends up being constrained, the resulting
296 position of the flip_x adjustment will be the one before the
301 <description summary="invert the anchor and gravity on the y axis">
302 Invert the anchor and gravity on the y axis if the surface is
303 constrained on the y axis. For example, if the bottom edge of the
304 surface is constrained, the gravity is 'bottom' and the anchor is
305 'bottom', change the gravity to 'top' and the anchor to 'top'.
307 If the adjusted position also ends up being constrained, the resulting
308 position of the flip_y adjustment will be the one before the
313 <description summary="horizontally resize the surface">
314 Resize the surface horizontally so that it is completely
319 <description summary="vertically resize the surface">
320 Resize the surface vertically so that it is completely unconstrained.
326 <description summary="set the adjustment to be done when constrained">
327 Specify how the window should be positioned if the originally intended
328 position caused the surface to be constrained, meaning at least
329 partially outside positioning boundaries set by the compositor. The
330 adjustment is set by constructing a bitmask describing the adjustment to
331 be made when the surface is constrained on that axis.
333 If no bit for one axis is set, the compositor will assume that the child
336 If more than one bit for one axis is set, the order of how adjustments
337 are applied is specified in the corresponding adjustment descriptions.
339 The default adjustment is none.
347 Specify the surface position offset relative to the position of the
348 anchor on the anchor rectangle and the anchor on the surface. For
349 example if the anchor of the anchor rectangle is at (x, y), the surface
350 has the gravity bottom|right, and the offset is (ox, oy), the calculated
351 surface position will be (x + ox, y + oy). The offset position of the
352 surface is the one used for constraint testing. See
356 element, while aligning the user interface element of the parent surface
357 with some user interface element placed somewhere in the popup surface.
370 interface elements requiring management by the compositor, such as
371 toplevel windows, menus, etc. The types of functionality are split into
374 Creating an xdg_surface does not set the role for a wl_surface. In order
375 to map an xdg_surface, the client must create a role-specific object
376 using, e.g., get_toplevel, get_popup. The wl_surface for any given
380 A role must be assigned before any other requests are made to the
383 The client must call wl_surface.commit on the corresponding wl_surface
384 for the xdg_surface state to take effect.
388 manipulate a buffer prior to the first xdg_surface.configure call must
391 For a surface to be mapped by the compositor, the following conditions
392 must be met: (1) the client has assigned a xdg_surface based role to the
393 surface, (2) the client has set and committed the xdg_surface state and
394 the role dependent state to the surface and (3) the client has committed a
395 buffer to the surface.
405 <description summary="destroy the xdg_surface">
406 Destroy the xdg_surface object. An xdg_surface must only be destroyed
412 <description summary="assign the xdg_toplevel surface role">
413 This creates an xdg_toplevel object for the given xdg_surface and gives
414 the associated wl_surface the xdg_toplevel role.
416 See the documentation of xdg_toplevel for more details about what an
423 <description summary="assign the xdg_popup surface role">
424 This creates an xdg_popup object for the given xdg_surface and gives the
425 associated wl_surface the xdg_popup role.
427 See the documentation of xdg_popup for more details about what an
436 <description summary="set the new window geometry">
437 The window geometry of a surface is its "visible bounds" from the
439 portions like drop-shadows which should be ignored for the
442 The window geometry is double buffered, and will be applied at the
443 time wl_surface.commit of the corresponding wl_surface is called.
445 Once the window geometry of the surface is set, it is not possible to
446 unset it, and it will remain the same until set_window_geometry is
449 If never set, the value is the full bounds of the surface,
453 The arguments are given in the surface-local coordinate space of
454 the wl_surface associated with this xdg_surface.
456 The width and height must be greater than zero. Setting an invalid size
457 will raise an error. When applied, the effective window geometry will be
458 the set window geometry clamped to the bounding rectangle of the
459 combined geometry of the surface of the xdg_surface and the associated
470 When a configure event is received, if a client commits the
471 surface in response to the configure event, then the client
472 must make an ack_configure request sometime before the commit
473 request, passing along the serial of the configure event.
475 For instance, for toplevel surfaces the compositor might use this
476 information to move a surface to the top left only when the client has
477 drawn itself for the maximized or fullscreen state.
479 If the client receives multiple configure events before it
480 can respond to one, it only has to ack the last configure event.
487 only the last request sent before a commit indicates which configure
488 event the client really is responding to.
490 <arg name="serial" type="uint" summary="the serial from the configure event"/>
495 The configure event marks the end of a configure sequence. A configure
496 sequence is a set of one or more events configuring the state of the
497 xdg_surface, including the final xdg_surface.configure event.
500 sequence extend this event as a latched state sent as events before the
502 a set of atomically applied configuration states, where the
503 xdg_surface.configure commits the accumulated state.
505 Clients should arrange their surface for the new states, and then send
506 an ack_configure request with the serial sent in this configure event at
507 some point before committing the new surface.
509 If the client receives multiple configure events before it can respond
510 to one, it is free to discard all but the last event it received.
512 <arg name="serial" type="uint" summary="serial of the configure event"/>
526 <description summary="destroy the xdg_toplevel">
527 Unmap and destroy the window. The window will be effectively
528 hidden from the user's point of view, and all state like
534 <description summary="set the parent of this surface">
535 Set the "parent" of this surface. This window should be stacked
536 above a parent. The parent surface must be mapped as long as this
540 "auxiliary" surfaces, so that the parent is raised when the dialog
548 Set a short title for the surface.
550 This string may be used to identify the surface in a task bar,
551 window list, or other user interface elements provided by the
554 The string must be encoded in UTF-8.
561 Set an application identifier for the surface.
563 The app ID identifies the general class of applications to which
564 the surface belongs. The compositor can use this to group multiple
567 For D-Bus activatable applications, the app ID is used as the D-Bus
570 The compositor shell will try to group application surfaces together
572 ID's that match the basename of the application's .desktop file.
573 For example, "org.freedesktop.FooViewer" where the .desktop file is
576 See the desktop-entry specification [0] for more details on
586 <description summary="show the window menu">
588 a context menu when right-clicking on the decorations, giving the
589 user a menu that they can use to maximize or minimize the window.
591 This request asks the compositor to pop up such a window menu at
592 the given position, relative to the local surface coordinates of
593 the parent surface. There are no guarantees as to what menu items
594 the window menu contains.
599 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
600 <arg name="serial" type="uint" summary="the serial of the user event"/>
601 <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
602 <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
607 Start an interactive, user-driven move of the surface.
610 like a button press, key press, or touch down event. The passed
611 serial is used to determine the type of interactive move (touch,
614 The server may ignore move requests depending on the state of
615 the surface (e.g. fullscreen or maximized), or if the passed serial
618 If triggered, the surface will lose the focus of the device
619 (wl_pointer, wl_touch, etc) used for the move. It is up to the
620 compositor to visually indicate that the move is taking place, such as
621 updating a pointer cursor, during the move. There is no guarantee
622 that the device focus will return when the move is completed.
624 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
625 <arg name="serial" type="uint" summary="the serial of the user event"/>
646 Start a user-driven, interactive resize of the surface.
649 like a button press, key press, or touch down event. The passed
650 serial is used to determine the type of interactive resize (touch,
653 The server may ignore resize requests depending on the state of
654 the surface (e.g. fullscreen or maximized).
656 If triggered, the client will receive configure events with the
657 "resize" state enum value and the expected sizes. See the "resize"
658 enum value for more details about what is required. The client
660 the resize is completed, the client will receive another "configure"
661 event without the resize state.
663 If triggered, the surface also will lose the focus of the device
664 (wl_pointer, wl_touch, etc) used for the resize. It is up to the
665 compositor to visually indicate that the resize is taking place,
666 such as updating a pointer cursor, during the resize. There is no
667 guarantee that the device focus will return when the resize is
670 The edges parameter specifies how the surface should be resized,
671 and is one of the values of the resize_edge enum. The compositor
672 may use this information to update the surface position for
673 example when dragging the top left corner. The compositor may also
677 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
678 <arg name="serial" type="uint" summary="the serial of the user event"/>
683 <description summary="types of state on the surface">
684 The different state values used on the surface. This is designed for
685 state values like maximized, fullscreen. It is paired with the
686 configure event to ensure that both the client and the compositor
687 setting the state can be synchronized.
690 the next commit.
692 <entry name="maximized" value="1" summary="the surface is maximized">
693 <description summary="the surface is maximized">
694 The surface is maximized. The window geometry specified in the configure
695 event must be obeyed by the client.
698 <entry name="fullscreen" value="2" summary="the surface is fullscreen">
699 <description summary="the surface is fullscreen">
700 The surface is fullscreen. The window geometry specified in the configure
701 event must be obeyed by the client.
704 <entry name="resizing" value="3" summary="the surface is being resized">
705 <description summary="the surface is being resized">
706 The surface is being resized. The window geometry specified in the
707 configure event is a maximum; the client cannot resize beyond it.
712 <entry name="activated" value="4" summary="the surface is now activated">
713 <description summary="the surface is now activated">
714 Client window decorations should be painted as if the window is
715 active. Do not assume this means that the window actually has
722 <description summary="set the maximum size">
723 Set a maximum size for the window.
725 The client can specify a maximum size so that the compositor does
726 not try to configure the window beyond this size.
728 The width and height arguments are in window geometry coordinates.
732 on the next commit.
734 The compositor can use this information to allow or disallow
741 The client should not rely on the compositor to obey the maximum
742 size. The compositor may decide to ignore the values set by the
745 If never set, or a value of zero in the request, means that the
746 client has no expected maximum size in the given dimension.
747 As a result, a client wishing to reset the maximum size
748 to an unspecified state can use zero for width and height in the
751 Requesting a maximum size to be smaller than the minimum size of
754 The width and height must be greater than or equal to zero. Using
763 <description summary="set the minimum size">
764 Set a minimum size for the window.
766 The client can specify a minimum size so that the compositor does
767 not try to configure the window below this size.
769 The width and height arguments are in window geometry coordinates.
773 on the next commit.
775 The compositor can use this information to allow or disallow
782 The client should not rely on the compositor to obey the minimum
783 size. The compositor may decide to ignore the values set by the
786 If never set, or a value of zero in the request, means that the
787 client has no expected minimum size in the given dimension.
788 As a result, a client wishing to reset the minimum size
789 to an unspecified state can use zero for width and height in the
792 Requesting a minimum size to be larger than the maximum size of
795 The width and height must be greater than or equal to zero. Using
804 <description summary="maximize the window">
805 Maximize the surface.
807 After requesting that the surface should be maximized, the compositor
808 will respond by emitting a configure event with the "maximized" state
809 and the required window geometry. The client should then update its
811 decoration outside of the window geometry. The client must also
812 acknowledge the configure when committing the new content (see
815 It is up to the compositor to decide how and where to maximize the
816 surface, for example which output and what region of the screen should
819 If the surface was already maximized, the compositor will still emit
820 a configure event with the "maximized" state.
825 <description summary="unmaximize the window">
826 Unmaximize the surface.
828 After requesting that the surface should be unmaximized, the compositor
829 will respond by emitting a configure event without the "maximized"
830 state. If available, the compositor will include the window geometry
831 dimensions the window had prior to being maximized in the configure
832 request. The client must then update its content, drawing it in a
833 regular state, i.e. potentially with shadow, etc. The client must also
834 acknowledge the configure when committing the new content (see
837 It is up to the compositor to position the surface after it was
838 unmaximized; usually the position the surface had before maximizing, if
841 If the surface was already not maximized, the compositor will still
842 emit a configure event without the "maximized" state.
847 <description summary="set the window as fullscreen on a monitor">
848 Make the surface fullscreen.
851 If this value is NULL, it's up to the compositor to choose which
854 If the surface doesn't cover the whole output, the compositor will
855 position the surface in the center of the output and compensate with
856 black borders filling the rest of the output.
863 <description summary="set the window as minimized">
864 Request that the compositor minimize your surface. There is no
865 way to know if the surface is currently minimized, nor is there
869 instead use the wl_surface.frame event for this, as this will
877 This configure event asks the client to resize its toplevel surface or
878 to change its state. The configured state should not be applied
881 The width and height arguments specify a hint to the window
885 If the width or height arguments are zero, it means the client
886 should decide its own window dimension. This may happen when the
887 compositor needs to configure the state of the surface but doesn't
890 The states listed in the event specify how the width/height
904 The close event is sent by the compositor when the user
905 wants the surface to be closed. This should be equivalent to
906 the user clicking the close button in client-side decorations,
909 This is only a request that the user intends to close the
910 window. The client may choose to ignore this request, or show
911 a dialog to ask the user to save their data, etc.
925 When the popup is dismissed, a popup_done event will be sent out, and at
926 the same time the surface will be unmapped. See the xdg_popup.popup_done
929 Explicitly destroying the xdg_popup object will also dismiss the popup and
930 unmap the surface. Clients that want to dismiss the popup when another
931 surface of their own is clicked should dismiss the popup using the destroy
934 The parent surface must have either the xdg_toplevel or xdg_popup surface
938 xdg_popup surfaces associated with the same xdg_toplevel.
940 The parent of an xdg_popup must be mapped (see the xdg_surface
941 description) before the xdg_popup itself.
943 The x and y arguments passed when creating the popup object specify
944 where the top left of the popup should be placed, relative to the
945 local surface coordinates of the parent surface. See
949 The client must call wl_surface.commit on the corresponding wl_surface
950 for the xdg_popup state to take effect.
960 This destroys the popup. Explicitly destroying the xdg_popup
961 object will also dismiss the popup, and unmap the surface.
963 If this xdg_popup is not the "topmost" popup, a protocol error
969 <description summary="make the popup take an explicit grab">
970 This request makes the created popup take an explicit grab. An explicit
971 grab will be dismissed when the user dismisses the popup, or when the
972 client destroys the xdg_popup. This can be done by the user clicking
973 outside the surface, using the keyboard, or even locking the screen
974 through closing the lid or a timeout.
976 If the compositor denies the grab, the popup will be immediately
980 button press, key press, or touch down event. The serial number of the
983 The parent of a grabbing popup must either be an xdg_toplevel surface or
984 another xdg_popup with an explicit grab. If the parent is another
985 xdg_popup it means that the popups are nested, with this popup now being
986 the topmost popup.
988 Nested popups must be destroyed in the reverse order they were created
989 in, e.g. the only popup you are allowed to destroy at all times is the
994 will follow the same dismissing order as required from the client.
996 The parent of a grabbing popup must either be another xdg_popup with an
1000 If the topmost grabbing popup is destroyed, the grab will be returned to
1001 the parent of the popup, if that parent previously had an explicit grab.
1003 If the parent is a grabbing popup which has already been dismissed, this
1004 popup will be immediately dismissed. If the parent is a popup that did
1007 During a popup grab, the client owning the grab will receive pointer
1009 "owner-events" grab in X11 parlance), while the top most grabbing popup
1013 summary="the wl_seat of the user event"/>
1014 <arg name="serial" type="uint" summary="the serial of the user event"/>
1018 <description summary="configure the popup surface">
1019 This event asks the popup surface to configure itself given the
1020 configuration. The configured state should not be applied immediately.
1023 The x and y arguments represent the position the popup was placed at
1024 given the xdg_positioner rule, relative to the upper left corner of the
1025 window geometry of the parent surface.
1037 The popup_done event is sent out when a popup is dismissed by the
1038 compositor. The client should destroy the xdg_popup object at this