mutter/src/core/stack.h

419 lines
14 KiB
C
Raw Normal View History

/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2001-06-10 03:52:35 -04:00
/*
* Copyright (C) 2001 Havoc Pennington
* Copyright (C) 2005 Elijah Newren
2001-06-10 03:52:35 -04:00
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of the
* License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <http://www.gnu.org/licenses/>.
2001-06-10 03:52:35 -04:00
*/
#ifndef META_STACK_H
#define META_STACK_H
/**
* SECTION:stack
* @short_description: Which windows cover which other windows
*
* There are two factors that determine window position.
*
* One is window->stack_position, which is a unique integer
* indicating how windows are ordered with respect to one
* another. The ordering here transcends layers; it isn't changed
* as the window is moved among layers. This allows us to move several
* windows from one layer to another, while preserving the relative
* order of the moved windows. Also, it allows us to restore
* the stacking order from a saved session.
*
* However when actually stacking windows on the screen, the
* layer overrides the stack_position; windows are first sorted
* by layer, then by stack_position within each layer.
*/
#include "screen-private.h"
2001-06-10 03:52:35 -04:00
/**
* A sorted list of windows bearing some level of resemblance to the stack of
* windows on the X server.
*
* (This is only used as a field within a MetaScreen; we treat it as a separate
* class for simplicity.)
*/
2001-06-10 03:52:35 -04:00
struct _MetaStack
{
/** The MetaScreen containing this stack. */
2001-06-10 03:52:35 -04:00
MetaScreen *screen;
/**
* A sequence of all the Windows (X handles, not MetaWindows) of the windows
* we manage, sorted in order. Suitable to be passed into _NET_CLIENT_LIST.
2001-06-10 03:52:35 -04:00
*/
Add support for stacking X and Wayland windows together This breaks down the assumptions in stack-tracker.c and stack.c that Mutter is only stacking X windows. The stack tracker now tracks windows using a MetaStackWindow structure which is a union with a type member so that X windows can be distinguished from Wayland windows. Some notable changes are: Queued stack tracker operations that affect Wayland windows will not be associated with an X serial number. If an operation only affects a Wayland window and there are no queued stack tracker operations ("unvalidated predictions") then the operation is applied immediately since there is no server involved with changing the stacking for Wayland windows. The stack tracker can no longer respond to X events by turning them into stack operations and discarding the predicted operations made prior to that event because operations based on X events don't know anything about the stacking of Wayland windows. Instead of discarding old predictions the new approach is to trust the predictions but whenever we receive an event from the server that affects stacking we cross-reference with the predicted stack and check for consistency. So e.g. if we have an event that says ADD window A then we apply the predictions (up to the serial for that event) and verify the predicted state includes a window A. Similarly if an event says RAISE_ABOVE(B, C) we can apply the predictions (up to the serial for that event) and verify that window B is above C. If we ever receive spurious stacking events (with a serial older than we would expect) or find an inconsistency (some things aren't possible to predict from the compositor) then we hit a re-synchronization code-path that will query the X server for the full stacking order and then use that stack to walk through our combined stack and force the X windows to match the just queried stack but avoiding disrupting the relative stacking of Wayland windows. This will be relatively expensive but shouldn't be hit for compositor initiated restacking operations where our predictions should be accurate. The code in core/stack.c that deals with synchronizing the window stack with the X server had to be updated quite heavily. In general the patch avoids changing the fundamental approach being used but most of the code did need some amount of re-factoring to consider what re-stacking operations actually involve X or not and when we need to restack X windows we sometimes need to search for a suitable X sibling to restack relative too since the closest siblings may be Wayland windows.
2012-04-05 06:22:13 -04:00
GArray *xwindows;
2001-06-10 03:52:35 -04:00
/** The MetaWindows of the windows we manage, sorted in order. */
GList *sorted;
/**
* MetaWindows waiting to be added to the "sorted" and "windows" list, after
* being added by meta_stack_add() and before being assimilated by
* stack_ensure_sorted().
*
* The order of the elements in this list is not important; what is important
* is the stack_position element of each window.
*/
GList *added;
/**
* Windows (X handles, not MetaWindows) waiting to be removed from the
* "windows" list, after being removed by meta_stack_remove() and before
* being assimilated by stack_ensure_sorted(). (We already removed them
* from the "sorted" list.)
*
* The order of the elements in this list is not important.
*/
GList *removed;
2001-06-10 03:52:35 -04:00
/**
* If this is zero, the local stack oughtn't to be brought up to date with
* the X server's stack, because it is in the middle of being updated.
* If it is positive, the local stack is said to be "frozen", and will need
* to be thawed that many times before the stack can be brought up to date
* again. You may freeze the stack with meta_stack_freeze() and thaw it
* with meta_stack_thaw().
*/
2001-06-10 03:52:35 -04:00
int freeze_count;
/**
* The last-known stack of all windows, bottom to top. We cache it here
* so that subsequent times we'll be able to do incremental moves.
*/
Add support for stacking X and Wayland windows together This breaks down the assumptions in stack-tracker.c and stack.c that Mutter is only stacking X windows. The stack tracker now tracks windows using a MetaStackWindow structure which is a union with a type member so that X windows can be distinguished from Wayland windows. Some notable changes are: Queued stack tracker operations that affect Wayland windows will not be associated with an X serial number. If an operation only affects a Wayland window and there are no queued stack tracker operations ("unvalidated predictions") then the operation is applied immediately since there is no server involved with changing the stacking for Wayland windows. The stack tracker can no longer respond to X events by turning them into stack operations and discarding the predicted operations made prior to that event because operations based on X events don't know anything about the stacking of Wayland windows. Instead of discarding old predictions the new approach is to trust the predictions but whenever we receive an event from the server that affects stacking we cross-reference with the predicted stack and check for consistency. So e.g. if we have an event that says ADD window A then we apply the predictions (up to the serial for that event) and verify the predicted state includes a window A. Similarly if an event says RAISE_ABOVE(B, C) we can apply the predictions (up to the serial for that event) and verify that window B is above C. If we ever receive spurious stacking events (with a serial older than we would expect) or find an inconsistency (some things aren't possible to predict from the compositor) then we hit a re-synchronization code-path that will query the X server for the full stacking order and then use that stack to walk through our combined stack and force the X windows to match the just queried stack but avoiding disrupting the relative stacking of Wayland windows. This will be relatively expensive but shouldn't be hit for compositor initiated restacking operations where our predictions should be accurate. The code in core/stack.c that deals with synchronizing the window stack with the X server had to be updated quite heavily. In general the patch avoids changing the fundamental approach being used but most of the code did need some amount of re-factoring to consider what re-stacking operations actually involve X or not and when we need to restack X windows we sometimes need to search for a suitable X sibling to restack relative too since the closest siblings may be Wayland windows.
2012-04-05 06:22:13 -04:00
GArray *last_all_root_children_stacked;
/**
* Number of stack positions; same as the length of added, but
* kept for quick reference.
*/
gint n_positions;
/** Is the stack in need of re-sorting? */
unsigned int need_resort : 1;
/**
* Are the windows in the stack in need of having their
* layers recalculated?
*/
unsigned int need_relayer : 1;
/**
* Are the windows in the stack in need of having their positions
* recalculated with respect to transiency (parent and child windows)?
*/
unsigned int need_constrain : 1;
2001-06-10 03:52:35 -04:00
};
/**
* meta_stack_new:
* @screen: The MetaScreen which will be the parent of this stack.
*
* Creates and initialises a MetaStack.
*
* Returns: The new screen.
*/
2001-06-10 03:52:35 -04:00
MetaStack *meta_stack_new (MetaScreen *screen);
/**
* meta_stack_free:
* @stack: The stack to destroy.
*
* Destroys and frees a MetaStack.
*/
2001-06-10 03:52:35 -04:00
void meta_stack_free (MetaStack *stack);
/**
* meta_stack_add:
* @stack: The stack to add it to
* @window: The window to add
*
* Adds a window to the local stack. It is a fatal error to call this
* function on a window which already exists on the stack of any screen.
*/
2001-06-10 03:52:35 -04:00
void meta_stack_add (MetaStack *stack,
MetaWindow *window);
/**
* meta_stack_remove:
* @stack: The stack to remove it from
* @window: The window to remove
*
* Removes a window from the local stack. It is a fatal error to call this
* function on a window which exists on the stack of any screen.
*/
2001-06-10 03:52:35 -04:00
void meta_stack_remove (MetaStack *stack,
MetaWindow *window);
/**
* meta_stack_update_layer:
* @stack: The stack to recalculate
* @window: Dummy parameter
*
* Recalculates the correct layer for all windows in the stack,
* and moves them about accordingly.
*
*/
2001-06-10 03:52:35 -04:00
void meta_stack_update_layer (MetaStack *stack,
MetaWindow *window);
/**
* meta_stack_update_transient:
* @stack: The stack to recalculate
* @window: Dummy parameter
*
* Recalculates the correct stacking order for all windows in the stack
* according to their transience, and moves them about accordingly.
*
* FIXME: What's with the dummy parameter?
*/
2001-06-10 03:52:35 -04:00
void meta_stack_update_transient (MetaStack *stack,
MetaWindow *window);
/**
* meta_stack_raise:
* @stack: The stack to modify.
* @window: The window that's making an ascension.
* (Amulet of Yendor not required.)
*
* Move a window to the top of its layer.
*/
2001-06-10 03:52:35 -04:00
void meta_stack_raise (MetaStack *stack,
MetaWindow *window);
/**
* meta_stack_lower:
* @stack: The stack to modify.
* @window: The window that's on the way downwards.
*
* Move a window to the bottom of its layer.
*/
2001-06-10 03:52:35 -04:00
void meta_stack_lower (MetaStack *stack,
MetaWindow *window);
/**
* meta_stack_freeze:
* @stack: The stack to freeze.
*
* Prevent syncing to server until the next call of meta_stack_thaw(),
* so that we can carry out multiple operations in one go without having
* everything halfway reflected on the X server.
*
* (Calls to meta_stack_freeze() nest, so that multiple calls to
* meta_stack_freeze will require multiple calls to meta_stack_thaw().)
*/
2001-06-10 03:52:35 -04:00
void meta_stack_freeze (MetaStack *stack);
/**
* meta_stack_thaw:
* @stack: The stack to thaw.
*
* Undoes a meta_stack_freeze(), and processes anything which has become
* necessary during the freeze. It is an error to call this function if
* the stack has not been frozen.
*/
2001-06-10 03:52:35 -04:00
void meta_stack_thaw (MetaStack *stack);
/**
* meta_stack_get_top:
* @stack: The stack to examine.
*
* Finds the top window on the stack.
*
* Returns: The top window on the stack, or %NULL in the vanishingly unlikely
* event that you have no windows on your screen whatsoever.
*/
2001-06-23 23:18:10 -04:00
MetaWindow* meta_stack_get_top (MetaStack *stack);
/**
* meta_stack_get_bottom:
* @stack: The stack to search
*
* Finds the window at the bottom of the stack. Since that's pretty much
* always the desktop, this isn't the most useful of functions, and nobody
* actually calls it. We should probably get rid of it.
*/
2001-06-23 23:18:10 -04:00
MetaWindow* meta_stack_get_bottom (MetaStack *stack);
/**
* meta_stack_get_above:
* @stack: The stack to search.
* @window: The window to look above.
* @only_within_layer: If %TRUE, will return %NULL if @window is the
* top window in its layer.
*
* Finds the window above a given window in the stack.
* It is not an error to pass in a window which does not exist in
* the stack; the function will merely return %NULL.
*
* Returns: %NULL if there is no such window;
* the window above @window otherwise.
*/
2001-06-23 23:18:10 -04:00
MetaWindow* meta_stack_get_above (MetaStack *stack,
MetaWindow *window,
gboolean only_within_layer);
/**
* meta_stack_get_below:
* @stack: The stack to search.
* @window: The window to look below.
* @only_within_layer: If %TRUE, will return %NULL if window is the
* bottom window in its layer.
*
* Finds the window below a given window in the stack.
* It is not an error to pass in a window which does not exist in
* the stack; the function will merely return %NULL.
*
*
* Returns: %NULL if there is no such window;
* the window below @window otherwise.
*/
2001-06-23 23:18:10 -04:00
MetaWindow* meta_stack_get_below (MetaStack *stack,
MetaWindow *window,
gboolean only_within_layer);
/**
* meta_stack_get_default_focus_window:
* @stack: The stack to search.
* @workspace: %NULL to search all workspaces; otherwise only windows
* from that workspace will be returned.
* @not_this_one: Window to ignore because it's being unfocussed or
* going away.
*
* Find the topmost, focusable, mapped, window in a stack. If you supply
* a window as @not_this_one, we won't return that one (presumably
* because it's going to be going away). But if you do supply @not_this_one
* and we find its parent, we'll return that; and if @not_this_one is in
* a group, we'll return the top window of that group.
*
* Also, we are prejudiced against dock windows. Every kind of window, even
* the desktop, will be returned in preference to a dock window.
*
* Returns: The window matching all these constraints or %NULL if none does.
*/
MetaWindow* meta_stack_get_default_focus_window (MetaStack *stack,
MetaWorkspace *workspace,
MetaWindow *not_this_one);
/**
* meta_stack_get_default_focus_window_at_point:
* @stack: The stack to search.
* @workspace: %NULL to search all workspaces; otherwise only windows
* from that workspace will be returned.
* @not_this_one: Window to ignore because it's being unfocussed or
* going away.
* @root_x: The returned window must contain this point,
* unless it's a dock.
* @root_y: See root_x.
*
* Find the topmost, focusable, mapped, window in a stack. If you supply
* a window as @not_this_one, we won't return that one (presumably
* because it's going to be going away). But if you do supply @not_this_one
* and we find its parent, we'll return that; and if @not_this_one is in
* a group, we'll return the top window of that group.
*
* Also, we are prejudiced against dock windows. Every kind of window, even
* the desktop, will be returned in preference to a dock window.
*
* Returns: The window matching all these constraints or %NULL if none does.
*/
MetaWindow* meta_stack_get_default_focus_window_at_point (MetaStack *stack,
MetaWorkspace *workspace,
MetaWindow *not_this_one,
int root_x,
int root_y);
/**
* meta_stack_list_windows:
* @stack: The stack to examine.
* @workspace: If not %NULL, only windows on this workspace will be
* returned; otherwise all windows in the stack will be
* returned.
*
* Finds all the windows in the stack, in order.
*
* Returns: A list of windows, in stacking order, honouring layers.
*/
GList* meta_stack_list_windows (MetaStack *stack,
MetaWorkspace *workspace);
2001-06-23 23:18:10 -04:00
/**
* meta_stack_windows_cmp:
* @stack: A stack containing both window_a and window_b
* @window_a: A window
* @window_b Another window
*
* Comparison function for windows within a stack. This is not directly
* suitable for use within a standard comparison routine, because it takes
* an extra parameter; you will need to wrap it.
*
* (FIXME: We could remove the stack parameter and use the stack of
* the screen of window A, and complain if the stack of the screen of
* window B differed; then this would be a usable general comparison function.)
*
* (FIXME: Apparently identical to compare_window_position(). Merge them.)
*
* \return -1 if window_a is below window_b, honouring layers; 1 if it's
* above it; 0 if you passed in the same window twice!
*/
2001-06-24 04:09:10 -04:00
int meta_stack_windows_cmp (MetaStack *stack,
MetaWindow *window_a,
MetaWindow *window_b);
2001-06-23 23:18:10 -04:00
/**
* meta_window_set_stack_position:
* @window: The window which is moving.
* @position: Where it should move to (0 is the bottom).
*
* Sets the position of a window within the stack. This will only move it
* up or down within its layer. It is an error to attempt to move this
* below position zero or above the last position in the stack (however, since
* we don't provide a simple way to tell the number of windows in the stack,
* this requirement may not be easy to fulfil).
*/
void meta_window_set_stack_position (MetaWindow *window,
int position);
/**
* meta_stack_get_positions:
* @stack: The stack to examine.
*
* Returns the current stack state, allowing rudimentary transactions.
*
* Returns: An opaque GList representing the current stack sort order;
* it is the caller's responsibility to free it.
* Pass this to meta_stack_set_positions() later if you want to restore
* the state to where it was when you called this function.
*/
GList* meta_stack_get_positions (MetaStack *stack);
/**
* meta_stack_set_positions:
* @stack: The stack to roll back.
* @windows: The list returned from meta_stack_get_positions().
*
* Rolls back a transaction, given the list returned from
* meta_stack_get_positions().
*
*/
void meta_stack_set_positions (MetaStack *stack,
GList *windows);
void meta_stack_update_window_tile_matches (MetaStack *stack,
MetaWorkspace *workspace);
2001-06-10 03:52:35 -04:00
#endif