mirror of
https://github.com/brl/mutter.git
synced 2025-07-03 01:32:11 +00:00
Switch to gtk-doc syntax
https://bugzilla.gnome.org/show_bug.cgi?id=673752
This commit is contained in:
Jasper St. Pierre
244
src/core/stack.h
244
src/core/stack.h
@ -1,23 +1,5 @@
|
||||
/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
|
||||
|
||||
/**
|
||||
* \file stack.h 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.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Copyright (C) 2001 Havoc Pennington
|
||||
* Copyright (C) 2005 Elijah Newren
|
||||
@ -41,6 +23,25 @@
|
||||
#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"
|
||||
|
||||
/**
|
||||
@ -123,192 +124,214 @@ struct _MetaStack
|
||||
};
|
||||
|
||||
/**
|
||||
* meta_stack_new:
|
||||
* @screen: The MetaScreen which will be the parent of this stack.
|
||||
*
|
||||
* Creates and initialises a MetaStack.
|
||||
*
|
||||
* \param screen The MetaScreen which will be the parent of this stack.
|
||||
* \return The new screen.
|
||||
* Returns: The new screen.
|
||||
*/
|
||||
MetaStack *meta_stack_new (MetaScreen *screen);
|
||||
|
||||
/**
|
||||
* Destroys and frees a MetaStack.
|
||||
* meta_stack_free:
|
||||
* @stack: The stack to destroy.
|
||||
*
|
||||
* \param stack The stack to destroy.
|
||||
* Destroys and frees a MetaStack.
|
||||
*/
|
||||
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.
|
||||
*
|
||||
* \param window The window to add
|
||||
* \param stack The stack to add it to
|
||||
*/
|
||||
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.
|
||||
*
|
||||
* \param window The window to remove
|
||||
* \param stack The stack to remove it from
|
||||
*/
|
||||
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.
|
||||
*
|
||||
* \param window Dummy parameter
|
||||
* \param stack The stack to recalculate
|
||||
* \bug What's with the dummy parameter?
|
||||
*/
|
||||
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.
|
||||
*
|
||||
* \param window Dummy parameter
|
||||
* \param stack The stack to recalculate
|
||||
* \bug What's with the dummy parameter?
|
||||
* FIXME: What's with the dummy parameter?
|
||||
*/
|
||||
void meta_stack_update_transient (MetaStack *stack,
|
||||
MetaWindow *window);
|
||||
|
||||
/**
|
||||
* Move a window to the top of its layer.
|
||||
* meta_stack_raise:
|
||||
* @stack: The stack to modify.
|
||||
* @window: The window that's making an ascension.
|
||||
* (Amulet of Yendor not required.)
|
||||
*
|
||||
* \param stack The stack to modify.
|
||||
* \param window The window that's making an ascension.
|
||||
* (Amulet of Yendor not required.)
|
||||
* Move a window to the top of its layer.
|
||||
*/
|
||||
void meta_stack_raise (MetaStack *stack,
|
||||
MetaWindow *window);
|
||||
/**
|
||||
* Move a window to the bottom of its layer.
|
||||
* meta_stack_lower:
|
||||
* @stack: The stack to modify.
|
||||
* @window: The window that's on the way downwards.
|
||||
*
|
||||
* \param stack The stack to modify.
|
||||
* \param window The window that's on the way downwards.
|
||||
* Move a window to the bottom of its layer.
|
||||
*/
|
||||
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().)
|
||||
*
|
||||
* \param stack The stack to freeze.
|
||||
*/
|
||||
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.
|
||||
*
|
||||
* \param stack The stack to thaw.
|
||||
*/
|
||||
void meta_stack_thaw (MetaStack *stack);
|
||||
|
||||
/**
|
||||
* meta_stack_get_top:
|
||||
* @stack: The stack to examine.
|
||||
*
|
||||
* Finds the top window on the stack.
|
||||
*
|
||||
* \param stack The stack to examine.
|
||||
* \return The top window on the stack, or NULL in the vanishingly unlikely
|
||||
* event that you have no windows on your screen whatsoever.
|
||||
* Returns: The top window on the stack, or %NULL in the vanishingly unlikely
|
||||
* event that you have no windows on your screen whatsoever.
|
||||
*/
|
||||
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.
|
||||
*
|
||||
* \param stack The stack to search
|
||||
*/
|
||||
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.
|
||||
* the stack; the function will merely return %NULL.
|
||||
*
|
||||
* \param stack The stack to search.
|
||||
* \param window The window to look above.
|
||||
* \param only_within_layer If true, will return NULL if "window" is the
|
||||
* top window in its layer.
|
||||
* \return NULL if there is no such window;
|
||||
* the window above "window" otherwise.
|
||||
* Returns: %NULL if there is no such window;
|
||||
* the window above @window otherwise.
|
||||
*/
|
||||
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.
|
||||
* the stack; the function will merely return %NULL.
|
||||
*
|
||||
* \param stack The stack to search.
|
||||
* \param window The window to look below.
|
||||
* \param only_within_layer If true, will return NULL if "window" is the
|
||||
* bottom window in its layer.
|
||||
* \return NULL if there is no such window;
|
||||
* the window below "window" otherwise.
|
||||
*
|
||||
* Returns: %NULL if there is no such window;
|
||||
* the window below @window otherwise.
|
||||
*/
|
||||
MetaWindow* meta_stack_get_below (MetaStack *stack,
|
||||
MetaWindow *window,
|
||||
gboolean only_within_layer);
|
||||
|
||||
/**
|
||||
* 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
|
||||
* 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.
|
||||
*
|
||||
* \param stack The stack to search.
|
||||
* \param workspace NULL to search all workspaces; otherwise only windows
|
||||
* from that workspace will be returned.
|
||||
* \param not_this_one Window to ignore because it's being unfocussed or
|
||||
* going away.
|
||||
* \return The window matching all these constraints or NULL if none does.
|
||||
*
|
||||
* \bug Never called!
|
||||
* 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 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.
|
||||
*
|
||||
* \param stack The stack to search.
|
||||
* \param workspace NULL to search all workspaces; otherwise only windows
|
||||
* from that workspace will be returned.
|
||||
* \param not_this_one Window to ignore because it's being unfocussed or
|
||||
* going away.
|
||||
* \param root_x The returned window must contain this point,
|
||||
* unless it's a dock.
|
||||
* \param root_y See root_x.
|
||||
* \return The window matching all these constraints or NULL if none does.
|
||||
* 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,
|
||||
@ -317,18 +340,25 @@ MetaWindow* meta_stack_get_default_focus_window_at_point (MetaStack *stack,
|
||||
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.
|
||||
*
|
||||
* \param stack The stack to examine.
|
||||
* \param workspace If non-NULL, only windows on this workspace will be
|
||||
* returned; otherwise all windows in the stack will be
|
||||
* returned.
|
||||
* \return A list of windows, in stacking order, honouring layers.
|
||||
* Returns: A list of windows, in stacking order, honouring layers.
|
||||
*/
|
||||
GList* meta_stack_list_windows (MetaStack *stack,
|
||||
MetaWorkspace *workspace);
|
||||
|
||||
/**
|
||||
* 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.
|
||||
@ -339,9 +369,6 @@ GList* meta_stack_list_windows (MetaStack *stack,
|
||||
*
|
||||
* (FIXME: Apparently identical to compare_window_position(). Merge them.)
|
||||
*
|
||||
* \param stack A stack containing both window_a and window_b
|
||||
* \param window_a A window
|
||||
* \param window_b Another window
|
||||
* \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!
|
||||
*/
|
||||
@ -350,35 +377,40 @@ int meta_stack_windows_cmp (MetaStack *stack,
|
||||
MetaWindow *window_b);
|
||||
|
||||
/**
|
||||
* 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).
|
||||
*
|
||||
* \param window The window which is moving.
|
||||
* \param position Where it should move to (0 is the bottom).
|
||||
*/
|
||||
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.
|
||||
*
|
||||
* \param stack The stack to examine.
|
||||
* \return 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.
|
||||
* 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().
|
||||
*
|
||||
* \param stack The stack to roll back.
|
||||
* \param windows The list returned from meta_stack_get_positions().
|
||||
*/
|
||||
void meta_stack_set_positions (MetaStack *stack,
|
||||
GList *windows);
|
||||
|
||||
Reference in New Issue
Block a user