marco 1.29.1
Window manager
Loading...
Searching...
No Matches
stack.h File Reference
View source

Which windows cover which other windows. More...

#include "screen-private.h"
Include dependency graph for stack.h:
This graph shows which files directly or indirectly include this file:

Data Structures

struct  _MetaStack
 A sorted list of windows bearing some level of resemblance to the stack of windows on the X server. More...
 

Enumerations

enum  MetaStackLayer {
  META_LAYER_DESKTOP = 0 , META_LAYER_BOTTOM = 1 , META_LAYER_NORMAL = 2 , META_LAYER_TOP = 4 ,
  META_LAYER_DOCK = 4 , META_LAYER_FULLSCREEN = 5 , META_LAYER_FOCUSED_WINDOW = 6 , META_LAYER_LAST = 7
}
 Layers a window can be in. More...
 

Functions

MetaStack * meta_stack_new (MetaScreen *screen)
 Creates and initialises a MetaStack.
 
void meta_stack_free (MetaStack *stack)
 Destroys and frees a MetaStack.
 
void meta_stack_add (MetaStack *stack, MetaWindow *window)
 Adds a window to the local stack.
 
void meta_stack_remove (MetaStack *stack, MetaWindow *window)
 Removes a window from the local stack.
 
void meta_stack_update_layer (MetaStack *stack, MetaWindow *window)
 Recalculates the correct layer for all windows in the stack, and moves them about accordingly.
 
void meta_stack_update_transient (MetaStack *stack, MetaWindow *window)
 Recalculates the correct stacking order for all windows in the stack according to their transience, and moves them about accordingly.
 
void meta_stack_raise (MetaStack *stack, MetaWindow *window)
 Move a window to the top of its layer.
 
void meta_stack_lower (MetaStack *stack, MetaWindow *window)
 Move a window to the bottom of its layer.
 
void meta_stack_freeze (MetaStack *stack)
 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.
 
void meta_stack_thaw (MetaStack *stack)
 Undoes a meta_stack_freeze(), and processes anything which has become necessary during the freeze.
 
MetaWindow * meta_stack_get_top (MetaStack *stack)
 Finds the top window on the stack.
 
MetaWindow * meta_stack_get_bottom (MetaStack *stack)
 Finds the window at the bottom of the stack.
 
MetaWindow * meta_stack_get_above (MetaStack *stack, MetaWindow *window, gboolean only_within_layer)
 Finds the window above a given window in the stack.
 
MetaWindow * meta_stack_get_below (MetaStack *stack, MetaWindow *window, gboolean only_within_layer)
 Finds the window below a given window in the stack.
 
MetaWindow * meta_stack_get_default_focus_window (MetaStack *stack, MetaWorkspace *workspace, MetaWindow *not_this_one)
 Find the topmost, focusable, mapped, window in a stack.
 
MetaWindow * meta_stack_get_default_focus_window_at_point (MetaStack *stack, MetaWorkspace *workspace, MetaWindow *not_this_one, int root_x, int root_y)
 Find the topmost, focusable, mapped, window in a stack.
 
GList * meta_stack_list_windows (MetaStack *stack, MetaWorkspace *workspace)
 Finds all the windows in the stack, in order.
 
int meta_stack_windows_cmp (MetaStack *stack, MetaWindow *window_a, MetaWindow *window_b)
 Comparison function for windows within a stack.
 
void meta_window_set_stack_position (MetaWindow *window, int position)
 Sets the position of a window within the stack.
 
GList * meta_stack_get_positions (MetaStack *stack)
 Returns the current stack state, allowing rudimentary transactions.
 
void meta_stack_set_positions (MetaStack *stack, GList *windows)
 Rolls back a transaction, given the list returned from meta_stack_get_positions().
 

Detailed 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.

Enumeration Type Documentation

◆ MetaStackLayer

Layers a window can be in.

These MUST be in the order of stacking.

Enumerator
META_LAYER_DESKTOP 
META_LAYER_BOTTOM 
META_LAYER_NORMAL 
META_LAYER_TOP 
META_LAYER_DOCK 
META_LAYER_FULLSCREEN 
META_LAYER_FOCUSED_WINDOW 
META_LAYER_LAST 

Function Documentation

◆ meta_stack_add()

void meta_stack_add ( MetaStack *  stack,
MetaWindow *  window 
)

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.

Parameters
windowThe window to add
stackThe stack to add it to

References _MetaStack::added, _MetaWindow::desc, meta_bug(), META_DEBUG_STACK, _MetaStack::n_positions, _MetaWindow::stack_position, and stack_sync_to_server().

Referenced by meta_window_new_with_attrs().

Here is the call graph for this function:

◆ meta_stack_free()

void meta_stack_free ( MetaStack *  stack)

Destroys and frees a MetaStack.

Parameters
stackThe stack to destroy.

References _MetaStack::added, _MetaStack::last_root_children_stacked, _MetaStack::removed, _MetaStack::sorted, TRUE, and _MetaStack::windows.

Referenced by meta_screen_free().

◆ meta_stack_freeze()

void meta_stack_freeze ( MetaStack *  stack)

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().)

Parameters
stackThe stack to freeze.

References _MetaStack::freeze_count.

Referenced by meta_group_update_layers(), meta_screen_composite_all_windows(), meta_screen_manage_all_windows(), meta_window_free(), meta_window_make_fullscreen_internal(), meta_window_new_with_attrs(), and meta_window_update_layer().

◆ meta_stack_get_above()

MetaWindow * meta_stack_get_above ( MetaStack *  stack,
MetaWindow *  window,
gboolean  only_within_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.

Parameters
stackThe stack to search.
windowThe window to look above.
only_within_layerIf true, will return NULL if "window" is the top window in its layer.
Returns
NULL if there is no such window; the window above "window" otherwise.

References _MetaWindow::layer, NULL, _MetaStack::sorted, and stack_ensure_sorted().

Referenced by handle_raise_or_lower().

Here is the call graph for this function:

◆ meta_stack_get_below()

MetaWindow * meta_stack_get_below ( MetaStack *  stack,
MetaWindow *  window,
gboolean  only_within_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.

Parameters
stackThe stack to search.
windowThe window to look below.
only_within_layerIf true, will return NULL if "window" is the bottom window in its layer.
Returns
NULL if there is no such window; the window below "window" otherwise.

References _MetaWindow::layer, NULL, _MetaStack::sorted, and stack_ensure_sorted().

Here is the call graph for this function:

◆ meta_stack_get_bottom()

MetaWindow * meta_stack_get_bottom ( MetaStack *  stack)

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.

Parameters
stackThe stack to search

References NULL, _MetaStack::sorted, and stack_ensure_sorted().

Here is the call graph for this function:

◆ meta_stack_get_default_focus_window()

MetaWindow * meta_stack_get_default_focus_window ( MetaStack *  stack,
MetaWorkspace *  workspace,
MetaWindow *  not_this_one 
)

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.

Parameters
stackThe stack to search.
workspaceNULL to search all workspaces; otherwise only windows from that workspace will be returned.
not_this_oneWindow to ignore because it's being unfocussed or going away.
Returns
The window matching all these constraints or NULL if none does.
Bug:
Never called!

References FALSE, and get_default_focus_window().

Referenced by focus_ancestor_or_top_window().

Here is the call graph for this function:

◆ meta_stack_get_default_focus_window_at_point()

MetaWindow * meta_stack_get_default_focus_window_at_point ( MetaStack *  stack,
MetaWorkspace *  workspace,
MetaWindow *  not_this_one,
int  root_x,
int  root_y 
)

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.

Parameters
stackThe stack to search.
workspaceNULL to search all workspaces; otherwise only windows from that workspace will be returned.
not_this_oneWindow to ignore because it's being unfocussed or going away.
root_xThe returned window must contain this point, unless it's a dock.
root_ySee root_x.
Returns
The window matching all these constraints or NULL if none does.

References get_default_focus_window(), and TRUE.

Referenced by meta_screen_get_mouse_window().

Here is the call graph for this function:

◆ meta_stack_get_positions()

GList * meta_stack_get_positions ( MetaStack *  stack)

Returns the current stack state, allowing rudimentary transactions.

Parameters
stackThe stack to examine.
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.

References compare_just_window_stack_position(), _MetaStack::sorted, and stack_ensure_sorted().

Referenced by meta_display_begin_grab_op().

Here is the call graph for this function:

◆ meta_stack_get_top()

MetaWindow * meta_stack_get_top ( MetaStack *  stack)

Finds the top window on the stack.

Parameters
stackThe stack to examine.
Returns
The top window on the stack, or NULL in the vanishingly unlikely event that you have no windows on your screen whatsoever.

References NULL, _MetaStack::sorted, and stack_ensure_sorted().

Referenced by handle_raise_or_lower(), meta_core_lower_beneath_focus_window(), and window_raise_with_delay_callback().

Here is the call graph for this function:

◆ meta_stack_list_windows()

GList * meta_stack_list_windows ( MetaStack *  stack,
MetaWorkspace *  workspace 
)

Finds all the windows in the stack, in order.

Parameters
stackThe stack to examine.
workspaceIf non-NULL, only windows on this workspace will be returned; otherwise all windows in the stack will be returned.
Returns
A list of windows, in stacking order, honouring layers.

References meta_window_located_on_workspace(), NULL, _MetaStack::sorted, and stack_ensure_sorted().

Referenced by compute_resistance_and_snapping_edges(), meta_select_workspace_draw(), and meta_window_find_tile_match().

Here is the call graph for this function:

◆ meta_stack_lower()

void meta_stack_lower ( MetaStack *  stack,
MetaWindow *  window 
)

Move a window to the bottom of its layer.

Parameters
stackThe stack to modify.
windowThe window that's on the way downwards.

References _MetaStack::added, meta_window_get_workspace(), meta_window_located_on_workspace(), meta_window_set_stack_position_no_sync(), NULL, _MetaStack::sorted, _MetaWindow::stack_position, and stack_sync_to_server().

Referenced by meta_window_lower().

Here is the call graph for this function:

◆ meta_stack_new()

MetaStack * meta_stack_new ( MetaScreen *  screen)

Creates and initialises a MetaStack.

Parameters
screenThe MetaScreen which will be the parent of this stack.
Returns
The new screen.

References _MetaStack::added, FALSE, _MetaStack::freeze_count, _MetaStack::last_root_children_stacked, _MetaStack::n_positions, _MetaStack::need_constrain, _MetaStack::need_relayer, _MetaStack::need_resort, NULL, _MetaStack::removed, _MetaStack::screen, screen, _MetaStack::sorted, and _MetaStack::windows.

Referenced by meta_screen_new().

◆ meta_stack_raise()

void meta_stack_raise ( MetaStack *  stack,
MetaWindow *  window 
)

Move a window to the top of its layer.

Parameters
stackThe stack to modify.
windowThe window that's making an ascension. (Amulet of Yendor not required.)

References _MetaStack::added, meta_window_get_workspace(), meta_window_located_on_workspace(), meta_window_set_stack_position_no_sync(), NULL, _MetaStack::sorted, _MetaWindow::stack_position, and stack_sync_to_server().

Referenced by meta_window_raise().

Here is the call graph for this function:

◆ meta_stack_remove()

void meta_stack_remove ( MetaStack *  stack,
MetaWindow *  window 
)

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.

Parameters
windowThe window to remove
stackThe stack to remove it from

References _MetaStack::added, _MetaWindow::desc, _MetaWindow::frame, meta_bug(), META_DEBUG_STACK, meta_window_set_stack_position_no_sync(), _MetaStack::n_positions, _MetaStack::removed, _MetaStack::sorted, _MetaWindow::stack_position, stack_sync_to_server(), _MetaFrame::xwindow, and _MetaWindow::xwindow.

Referenced by meta_window_free().

Here is the call graph for this function:

◆ meta_stack_set_positions()

void meta_stack_set_positions ( MetaStack *  stack,
GList *  windows 
)

Rolls back a transaction, given the list returned from meta_stack_get_positions().

Parameters
stackThe stack to roll back.
windowsThe list returned from meta_stack_get_positions().

References lists_contain_same_windows(), META_DEBUG_STACK, meta_warning(), _MetaStack::need_constrain, _MetaStack::need_resort, NULL, _MetaStack::sorted, stack_ensure_sorted(), _MetaWindow::stack_position, stack_sync_to_server(), TRUE, and windows.

Referenced by event_callback(), and process_tab_grab().

Here is the call graph for this function:

◆ meta_stack_thaw()

void meta_stack_thaw ( MetaStack *  stack)

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.

Parameters
stackThe stack to thaw.

References _MetaStack::freeze_count, and stack_sync_to_server().

Referenced by meta_group_update_layers(), meta_screen_composite_all_windows(), meta_screen_manage_all_windows(), meta_window_free(), meta_window_make_fullscreen_internal(), meta_window_new_with_attrs(), and meta_window_update_layer().

Here is the call graph for this function:

◆ meta_stack_update_layer()

void meta_stack_update_layer ( MetaStack *  stack,
MetaWindow *  window 
)

Recalculates the correct layer for all windows in the stack, and moves them about accordingly.

Parameters
windowDummy parameter
stackThe stack to recalculate
Bug:
What's with the dummy parameter?

References _MetaStack::need_relayer, stack_sync_to_server(), and TRUE.

Referenced by meta_group_update_layers(), and meta_window_update_layer().

Here is the call graph for this function:

◆ meta_stack_update_transient()

void meta_stack_update_transient ( MetaStack *  stack,
MetaWindow *  window 
)

Recalculates the correct stacking order for all windows in the stack according to their transience, and moves them about accordingly.

Parameters
windowDummy parameter
stackThe stack to recalculate
Bug:
What's with the dummy parameter?

References _MetaStack::need_constrain, stack_sync_to_server(), and TRUE.

Referenced by reload_transient_for().

Here is the call graph for this function:

◆ meta_stack_windows_cmp()

int meta_stack_windows_cmp ( MetaStack *  stack,
MetaWindow *  window_a,
MetaWindow *  window_b 
)

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.)

Parameters
stackA stack containing both window_a and window_b
window_aA window
window_bAnother window
Returns
-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!

References _MetaWindow::layer, _MetaWindow::screen, stack_ensure_sorted(), and _MetaWindow::stack_position.

Referenced by meta_display_stack_cmp(), and stackcmp().

Here is the call graph for this function:

◆ meta_window_set_stack_position()

void meta_window_set_stack_position ( MetaWindow *  window,
int  position 
)

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).

Parameters
windowThe window which is moving.
positionWhere it should move to (0 is the bottom).

References meta_window_set_stack_position_no_sync(), _MetaWindow::screen, _MetaScreen::stack, and stack_sync_to_server().

Referenced by meta_window_stack_just_below().

Here is the call graph for this function: