stack.h File Reference

Which windows cover which other windows. More...

Go to the source code of 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.

Definition in file stack.h.

---

Enumeration Type Documentation

enum 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

Definition at line 50 of file stack.h.

---

Function Documentation

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:

	window	The window to add
	stack	The stack to add it to

Definition at line 107 of file stack.c.

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

void meta_stack_free

(

MetaStack *

stack

)

Destroys and frees a MetaStack.

Parameters:

stack

The stack to destroy.

Definition at line 92 of file stack.c.

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

Referenced by meta_screen_free().

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:

stack

The stack to freeze.

Definition at line 200 of file stack.c.

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

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:

	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.

Returns:

NULL if there is no such window; the window above "window" otherwise.

Definition at line 1268 of file stack.c.

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

Referenced by handle_raise_or_lower().

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:

	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.

Returns:

NULL if there is no such window; the window below "window" otherwise.

Definition at line 1293 of file stack.c.

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

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:

stack

The stack to search

Definition at line 1254 of file stack.c.

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

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:

	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.

Returns:

The window matching all these constraints or NULL if none does.

Bug:

Never called!

Definition at line 1438 of file stack.c.

References FALSE, and get_default_focus_window().

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:

	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.

Returns:

The window matching all these constraints or NULL if none does.

Definition at line 1427 of file stack.c.

References get_default_focus_window(), and TRUE.

Referenced by meta_screen_get_mouse_window().

GList* meta_stack_get_positions

(

MetaStack *

stack

)

Returns the current stack state, allowing rudimentary transactions.

Parameters:

stack

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

Definition at line 1513 of file stack.c.

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

Referenced by meta_display_begin_grab_op().

MetaWindow* meta_stack_get_top

(

MetaStack *

stack

)

Finds the top window on the stack.

Parameters:

stack

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

Definition at line 1243 of file stack.c.

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

Referenced by handle_raise_or_lower(), and window_raise_with_delay_callback().

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

Finds all the windows in the stack, in order.

Parameters:

	stack	The stack to examine.
	workspace	If 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.

Definition at line 1447 of file stack.c.

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

Referenced by meta_display_compute_resistance_and_snapping_edges(), and meta_select_workspace_expose_event().

void meta_stack_lower	(	MetaStack *	stack,
		MetaWindow *	window
	)

Move a window to the bottom of its layer.

Parameters:

	stack	The stack to modify.
	window	The window that's on the way downwards.

Definition at line 191 of file stack.c.

References meta_window_set_stack_position_no_sync(), and stack_sync_to_server().

Referenced by meta_window_lower().

MetaStack* meta_stack_new

(

MetaScreen *

screen

)

Creates and initialises a MetaStack.

Parameters:

screen

The MetaScreen which will be the parent of this stack.

Returns:

The new screen.

Definition at line 66 of file stack.c.

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, _MetaStack::sorted, and _MetaStack::windows.

Referenced by meta_screen_new().

void meta_stack_raise	(	MetaStack *	stack,
		MetaWindow *	window
	)

Move a window to the top of its layer.

Parameters:

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

Definition at line 181 of file stack.c.

References meta_window_set_stack_position_no_sync(), _MetaStack::n_positions, and stack_sync_to_server().

Referenced by meta_window_raise().

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:

	window	The window to remove
	stack	The stack to remove it from

Definition at line 127 of file stack.c.

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

void meta_stack_set_positions	(	MetaStack *	stack,
		GList *	windows
	)

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

Parameters:

	stack	The stack to roll back.
	windows	The list returned from meta_stack_get_positions().

Definition at line 1564 of file stack.c.

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(), and TRUE.

Referenced by event_callback(), and process_tab_grab().

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:

stack

The stack to thaw.

Definition at line 206 of file stack.c.

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

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:

	window	Dummy parameter
	stack	The stack to recalculate

Bug:

What's with the dummy parameter?

Definition at line 162 of file stack.c.

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

Referenced by meta_group_update_layers(), and meta_window_update_layer().

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:

	window	Dummy parameter
	stack	The stack to recalculate

Bug:

What's with the dummy parameter?

Definition at line 171 of file stack.c.

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

Referenced by reload_transient_for().

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:

	stack	A stack containing both window_a and window_b
	window_a	A window
	window_b	Another 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!

Definition at line 1475 of file stack.c.

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

Referenced by meta_display_stack_cmp(), and stackcmp().

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:

	window	The window which is moving.
	position	Where it should move to (0 is the bottom).

Definition at line 1656 of file stack.c.

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

Referenced by meta_window_stack_just_below().