Commit 044d5895 authored by Jasper St. Pierre's avatar Jasper St. Pierre
parent 9c97e899
......@@ -396,7 +396,7 @@ meta_plugin_begin_modal (MetaPlugin *plugin,
}
/**
* meta_plugin_end_modal
* meta_plugin_end_modal:
* @plugin: a #MetaPlugin
* @timestamp: the time used for releasing grabs
*
......
......@@ -23,7 +23,8 @@
*/
/**
* \file bell.c Ring the bell or flash the screen
* SECTION:Bell
* @short_description: Ring the bell or flash the screen
*
* Sometimes, X programs "ring the bell", whatever that means. Mutter lets
* the user configure the bell to be audible or visible (aka visual), and
......@@ -57,6 +58,10 @@
#endif
/**
* bell_flash_screen:
* @display: The display which owns the screen (rather redundant)
* @screen: The screen to flash
*
* Flashes one entire screen. This is done by making a window the size of the
* whole screen (or reusing the old one, if it's still around), mapping it,
* painting it white and then black, and then unmapping it. We set saveunder so
......@@ -65,14 +70,12 @@
* Unlike frame flashes, we don't do fullscreen flashes with a timeout; rather,
* we do them in one go, because we don't have to rely on the theme code
* redrawing the frame for us in order to do the flash.
*
* \param display The display which owns the screen (rather redundant)
* \param screen The screen to flash
*
* \bug The way I read it, this appears not to do the flash
*/
/*
* Bug: The way I read it, this appears not to do the flash
* the first time we flash a particular display. Am I wrong?
*
* \bug This appears to destroy our current XSync status.
* Bug: This appears to destroy our current XSync status.
*/
static void
bell_flash_screen (MetaDisplay *display,
......@@ -137,14 +140,15 @@ bell_flash_screen (MetaDisplay *display,
}
/**
* bell_flash_fullscreen:
* @display: The display the event came in on
* @xkb_ev: The bell event
*
* Flashes one screen, or all screens, in response to a bell event.
* If the event is on a particular window, flash the screen that
* window is on. Otherwise, flash every screen on this display.
*
* If the configure script found we had no XKB, this does not exist.
*
* \param display The display the event came in on
* \param xkb_ev The bell event
*/
#ifdef HAVE_XKB
static void
......@@ -182,17 +186,21 @@ bell_flash_fullscreen (MetaDisplay *display,
}
/**
* bell_unflash_frame:
* @data: The frame to unflash, cast to a gpointer so it can go into
* a callback function.
*
* Makes a frame be not flashed; this is the timeout half of
* bell_flash_window_frame(). This is done simply by clearing the
* flash flag and queuing a redraw of the frame.
*
* If the configure script found we had no XKB, this does not exist.
*
* \param data The frame to unflash, cast to a gpointer so it can go into
* a callback function.
* \return Always FALSE, so we don't get called again.
*
* \bug This is the parallel to bell_flash_window_frame(), so it should
* Returns: Always FALSE, so we don't get called again.
*/
/*
* Bug: This is the parallel to bell_flash_window_frame(), so it should
* really be called meta_bell_unflash_window_frame().
*/
static gboolean
......@@ -205,6 +213,9 @@ bell_unflash_frame (gpointer data)
}
/**
* bell_flash_window_frame:
* @window: The window to flash
*
* Makes a frame flash and then return to normal shortly afterwards.
* This is done by setting a flag so that the theme
* code will temporarily draw the frame as focussed if it's unfocussed and
......@@ -212,8 +223,6 @@ bell_unflash_frame (gpointer data)
* that the flag can be unset and the frame re-redrawn.
*
* If the configure script found we had no XKB, this does not exist.
*
* \param window The window to flash
*/
static void
bell_flash_window_frame (MetaWindow *window)
......@@ -231,11 +240,12 @@ bell_flash_window_frame (MetaWindow *window)
}
/**
* bell_flash_frame:
* @display: The display the bell event came in on
* @xkb_ev: The bell event we just received
*
* Flashes the frame of the focussed window. If there is no focussed window,
* flashes the screen.
*
* \param display The display the bell event came in on
* \param xkb_ev The bell event we just received
*/
static void
bell_flash_frame (MetaDisplay *display,
......@@ -261,15 +271,18 @@ bell_flash_frame (MetaDisplay *display,
}
/**
* bell_visual_notify:
* @display: The display the bell event came in on
* @xkb_ev: The bell event we just received
*
* Gives the user some kind of visual bell substitute, in response to a
* bell event. What this is depends on the "visual bell type" pref.
*
* If the configure script found we had no XKB, this does not exist.
*
* \param display The display the bell event came in on
* \param xkb_ev The bell event we just received
*
* \bug This should be merged with meta_bell_notify().
*/
/*
* Bug: This should be merged with meta_bell_notify().
*/
static void
bell_visual_notify (MetaDisplay *display,
......@@ -407,12 +420,13 @@ meta_bell_shutdown (MetaDisplay *display)
}
/**
* meta_bell_notify_frame_destroy:
* @frame: The frame which is being destroyed
*
* Deals with a frame being destroyed. This is important because if we're
* using a visual bell, we might be flashing the edges of the frame, and
* so we'd have a timeout function waiting ready to un-flash them. If the
* frame's going away, we can tell the timeout not to bother.
*
* \param frame The frame which is being destroyed
*/
void
meta_bell_notify_frame_destroy (MetaFrame *frame)
......
/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
/**
* \file bell.h Ring the bell or flash the screen
*
* Sometimes, X programs "ring the bell", whatever that means. Mutter lets
* the user configure the bell to be audible or visible (aka visual), and
* if it's visual it can be configured to be frame-flash or fullscreen-flash.
* We never get told about audible bells; X handles them just fine by itself.
*
* The visual bell was the result of a discussion in Bugzilla here:
* <http://bugzilla.gnome.org/show_bug.cgi?id=99886>.
*/
/*
* Copyright (C) 2002 Sun Microsystems Inc.
*
......
......@@ -25,9 +25,10 @@
*/
/**
* \file display.c Handles operations on an X display.
* SECTION:MetaDisplay
* @short_description: Handles operations on an X display.
*
* The display is represented as a MetaDisplay struct.
* The display is represented as a #MetaDisplay struct.
*/
#define _XOPEN_SOURCE 600 /* for gethostname() */
......@@ -87,7 +88,7 @@
g == META_GRAB_OP_KEYBOARD_ESCAPING_GROUP)
/**
* \defgroup pings Pings
* SECTION:pings
*
* Sometimes we want to see whether a window is responding,
* so we send it a "ping" message and see whether it sends us back a "pong"
......@@ -102,13 +103,13 @@
*/
/**
* MetaPingData:
*
* Describes a ping on a window. When we send a ping to a window, we build
* one of these structs, and it eventually gets passed to the timeout function
* or to the function which handles the response from the window. If the window
* does or doesn't respond to the ping, we use this information to deal with
* these facts; we have a handler function for each.
*
* \ingroup pings
*/
typedef struct
{
......@@ -150,7 +151,7 @@ enum {
static guint display_signals [LAST_SIGNAL] = { 0 };
/**
/*
* The display we're managing. This is a singleton object. (Historically,
* this was a list of displays, but there was never any way to add more
* than one element to it.) The goofy name is because we don't want it
......@@ -185,7 +186,7 @@ static void prefs_changed_callback (MetaPreference pref,
static void sanity_check_timestamps (MetaDisplay *display,
guint32 known_good_timestamp);
MetaGroup* get_focussed_group (MetaDisplay *display);
static void
......@@ -295,10 +296,10 @@ meta_display_class_init (MetaDisplayClass *klass)
/**
* Destructor for MetaPingData structs. Will destroy the
* event source for the struct as well.
* ping_data_free:
*
* \ingroup pings
* Destructor for #MetaPingData structs. Will destroy the
* event source for the struct as well.
*/
static void
ping_data_free (MetaPingData *ping_data)
......@@ -311,14 +312,12 @@ ping_data_free (MetaPingData *ping_data)
}
/**
* remove_pending_pings_for_window:
* @display: The display the window appears on
* @xwindow: The X ID of the window whose pings we should remove
*
* Frees every pending ping structure for the given X window on the
* given display. This means that we also destroy the timeouts.
*
* \param display The display the window appears on
* \param xwindow The X ID of the window whose pings we should remove
*
* \ingroup pings
*
*/
static void
remove_pending_pings_for_window (MetaDisplay *display, Window xwindow)
......@@ -417,14 +416,14 @@ meta_display_init (MetaDisplay *disp)
}
/**
* meta_display_open:
*
* Opens a new display, sets it up, initialises all the X extensions
* we will need, and adds it to the list of displays.
*
* \return True if the display was opened successfully, and False
* Returns: %TRUE if the display was opened successfully, and %FALSE
* otherwise-- that is, if the display doesn't exist or it already
* has a window manager.
*
* \ingroup main
*/
gboolean
meta_display_open (void)
......@@ -1168,14 +1167,16 @@ meta_display_ungrab (MetaDisplay *display)
}
/**
* Returns the singleton MetaDisplay if "xdisplay" matches the X display it's
* managing; otherwise gives a warning and returns NULL. When we were claiming
* meta_display_for_x_display:
* @xdisplay: An X display
*
* Returns the singleton MetaDisplay if @xdisplay matches the X display it's
* managing; otherwise gives a warning and returns %NULL. When we were claiming
* to be able to manage multiple displays, this was supposed to find the
* display out of the list which matched that display. Now it's merely an
* extra sanity check.
*
* \param xdisplay An X display
* \return The singleton X display, or NULL if "xdisplay" isn't the one
* Returns: The singleton X display, or %NULL if @xdisplay isn't the one
* we're managing.
*/
MetaDisplay*
......@@ -1191,9 +1192,11 @@ meta_display_for_x_display (Display *xdisplay)
}
/**
* meta_get_display:
*
* Accessor for the singleton MetaDisplay.
*
* \return The only MetaDisplay there is. This can be NULL, but only
* Returns: The only #MetaDisplay there is. This can be %NULL, but only
* during startup.
*/
MetaDisplay*
......@@ -1601,19 +1604,18 @@ handle_net_restack_window (MetaDisplay* display,
#endif
/**
* event_callback:
* @event: The event that just happened
* @data: The #MetaDisplay that events are coming from, cast to a gpointer
* so that it can be sent to a callback
*
* This is the most important function in the whole program. It is the heart,
* it is the nexus, it is the Grand Central Station of Mutter's world.
* When we create a MetaDisplay, we ask GDK to pass *all* events for *all*
* When we create a #MetaDisplay, we ask GDK to pass *all* events for *all*
* windows to this function. So every time anything happens that we might
* want to know about, this function gets called. You see why it gets a bit
* busy around here. Most of this function is a ginormous switch statement
* dealing with all the kinds of events that might turn up.
*
* \param event The event that just happened
* \param data The MetaDisplay that events are coming from, cast to a gpointer
* so that it can be sent to a callback
*
* \ingroup main
*/
static gboolean
event_callback (XEvent *event,
......@@ -4197,21 +4199,23 @@ meta_display_set_cursor_theme (const char *theme,
#endif
}
/**
/*
* Stores whether syncing is currently enabled.
*/
static gboolean is_syncing = FALSE;
/**
* Returns whether X synchronisation is currently enabled.
* meta_is_syncing:
*
* \return true if we must wait for events whenever we send X requests;
* false otherwise.
* Returns whether X synchronisation is currently enabled.
*
* \bug This is *only* called by meta_display_open, but by that time
* FIXME: This is *only* called by meta_display_open(), but by that time
* we have already turned syncing on or off on startup, and we don't
* have any way to do so while Mutter is running, so it's rather
* pointless.
*
* Returns: %TRUE if we must wait for events whenever we send X requests;
* %FALSE otherwise.
*/
gboolean
meta_is_syncing (void)
......@@ -4220,10 +4224,9 @@ meta_is_syncing (void)
}
/**
* A handy way to turn on synchronisation on or off for every display.
* meta_set_syncing:
*
* \bug Of course there is only one display ever anyway, so this can
* be rather hugely simplified.
* A handy way to turn on synchronisation on or off for every display.
*/
void
meta_set_syncing (gboolean setting)
......@@ -4236,26 +4239,25 @@ meta_set_syncing (gboolean setting)
}
}
/**
/*
* How long, in milliseconds, we should wait after pinging a window
* before deciding it's not going to get back to us.
*/
#define PING_TIMEOUT_DELAY 5000
/**
* meta_display_ping_timeout:
* @data: All the information about this ping. It is a #MetaPingData
* cast to a #gpointer in order to be passable to a timeout function.
* This function will also free this parameter.
*
* Does whatever it is we decided to do when a window didn't respond
* to a ping. We also remove the ping from the display's list of
* pending pings. This function is called by the event loop when the timeout
* times out which we created at the start of the ping.
*
* \param data All the information about this ping. It is a MetaPingData
* cast to a void* in order to be passable to a timeout function.
* This function will also free this parameter.
*
* \return Always returns false, because this function is called as a
* timeout and we don't want to run the timer again.
*
* \ingroup pings
* Returns: Always returns %FALSE, because this function is called as a
* timeout and we don't want to run the timer again.
*/
static gboolean
meta_display_ping_timeout (gpointer data)
......@@ -4282,6 +4284,17 @@ meta_display_ping_timeout (gpointer data)
}
/**
* meta_display_ping_window:
* @display: The #MetaDisplay that the window is on
* @window: The #MetaWindow to send the ping to
* @timestamp: The timestamp of the ping. Used for uniqueness.
* Cannot be CurrentTime; use a real timestamp!
* @ping_reply_func: The callback to call if we get a response.
* @ping_timeout_func: The callback to call if we don't get a response.
* @user_data: Arbitrary data that will be passed to the callback
* function. (In practice it's often a pointer to
* the window.)
*
* Sends a ping request to a window. The window must respond to
* the request within a certain amount of time. If it does, we
* will call one callback; if the time passes and we haven't had
......@@ -4291,20 +4304,9 @@ meta_display_ping_timeout (gpointer data)
* This function returns straight away after setting things up;
* the callbacks will be called from the event loop.
*
* \param display The MetaDisplay that the window is on
* \param window The MetaWindow to send the ping to
* \param timestamp The timestamp of the ping. Used for uniqueness.
* Cannot be CurrentTime; use a real timestamp!
* \param ping_reply_func The callback to call if we get a response.
* \param ping_timeout_func The callback to call if we don't get a response.
* \param user_data Arbitrary data that will be passed to the callback
* function. (In practice it's often a pointer to
* the window.)
*
* \bug This should probably be a method on windows, rather than displays
* for one of their windows.
* FIXME: This should probably be a method on windows, rather than displays
* for one of their windows.
*
* \ingroup pings
*/
void
meta_display_ping_window (MetaDisplay *display,
......@@ -4412,16 +4414,15 @@ process_request_frame_extents (MetaDisplay *display,
}
/**
* process_pong_message:
* @display: the display we got the pong from
* @event: the #XEvent which is a pong; we can tell which
* ping it corresponds to because it bears the
* same timestamp.
*
* Process the pong (the response message) from the ping we sent
* to the window. This involves removing the timeout, calling the
* reply handler function, and freeing memory.
*
* \param display the display we got the pong from
* \param event the XEvent which is a pong; we can tell which
* ping it corresponds to because it bears the
* same timestamp.
*
* \ingroup pings
*/
static void
process_pong_message (MetaDisplay *display,
......@@ -4468,18 +4469,17 @@ process_pong_message (MetaDisplay *display,
}
/**
* Finds whether a window has any pings waiting on it.
* meta_display_window_has_pending_pings:
* @display: The #MetaDisplay of the window.
* @window: The #MetaWindow whose pings we want to know about.
*
* \param display The MetaDisplay of the window.
* \param window The MetaWindow whose pings we want to know about.
*
* \return True if there is at least one ping which has been sent
* to the window without getting a response; false otherwise.
* Finds whether a window has any pings waiting on it.
*
* \bug This should probably be a method on windows, rather than displays
* for one of their windows.
* FIXME: This should probably be a method on windows, rather than displays
* for one of their windows.
*
* \ingroup pings
* Returns: %TRUE if there is at least one ping which has been sent
* to the window without getting a response; %FALSE otherwise.
*/
gboolean
meta_display_window_has_pending_pings (MetaDisplay *display,
......
......@@ -23,18 +23,19 @@
*/
/**
* \file
* Program startup.
* SECTION:main
* @short_description: Program startup.
*
* Functions which parse the command-line arguments, create the display,
* kick everything off and then close down Mutter when it's time to go.
*/
/**
* \mainpage
*
*
*
* Mutter - a boring window manager for the adult in you
*
* Many window managers are like Marshmallow Froot Loops; Mutter
* is like Cheerios.
* is like Frosted Flakes: it's still plain old corn, but dusted
* with some sugar.
*
* The best way to get a handle on how the whole system fits together
* is discussed in doc/code-overview.txt; if you're looking for functions
......@@ -77,12 +78,12 @@
#include <girepository.h>
#endif
/**
/*
* The exit code we'll return to our parent process when we eventually die.
*/
static MetaExitCode meta_exit_code = META_EXIT_SUCCESS;
/**
/*
* Handle on the main loop, so that we have an easy way of shutting Mutter
* down.
*/
......@@ -92,14 +93,15 @@ static void prefs_changed_callback (MetaPreference pref,
gpointer data);
/**
* log_handler:
* @log_domain: the domain the error occurred in (we ignore this)
* @log_level: the log level so that we can filter out less
* important messages
* @message: the message to log
* @user_data: arbitrary data (we ignore this)
*
* Prints log messages. If Mutter was compiled with backtrace support,
* also prints a backtrace (see meta_print_backtrace()).
*
* \param log_domain the domain the error occurred in (we ignore this)
* \param log_level the log level so that we can filter out less
* important messages
* \param message the message to log
* \param user_data arbitrary data (we ignore this)
*/
static void
log_handler (const gchar *log_domain,
......@@ -112,10 +114,12 @@ log_handler (const gchar *log_domain,
}
/**
* meta_print_compilation_info:
*
* Prints a list of which configure script options were used to
* build this copy of Mutter. This is actually always called
* on startup, but it's all no-op unless we're in verbose mode
* (see meta_set_verbose).
* (see meta_set_verbose()).
*/
static void
meta_print_compilation_info (void)
......@@ -158,12 +162,14 @@ meta_print_compilation_info (void)
}
/**
* meta_print_self_identity:
*
* Prints the version number, the current timestamp (not the
* build date), the locale, the character encoding, and a list
* of configure script options that were used to build this
* copy of Mutter. This is actually always called
* on startup, but it's all no-op unless we're in verbose mode
* (see meta_set_verbose).
* (see meta_set_verbose()).
*/
static void
meta_print_self_identity (void)
......@@ -188,7 +194,7 @@ meta_print_self_identity (void)
meta_print_compilation_info ();
}
/**
/*
* The set of possible options that can be set on Mutter's
* command line.
*/
......@@ -327,10 +333,12 @@ meta_clutter_init (void)
}
/**
* meta_select_display:
*
* Selects which display Mutter should use. It first tries to use
* display_name as the display. If display_name is NULL then
* @display_name as the display. If @display_name is %NULL then
* try to use the environment variable MUTTER_DISPLAY. If that
* also is NULL, use the default - :0.0
* also is %NULL, use the default - :0.0
*/
static void
meta_select_display (gchar *display_name)
......@@ -560,13 +568,14 @@ meta_run (void)
}
/**
* meta_quit:
* @code: The success or failure code to return to the calling process.
*
* Stops Mutter. This tells the event loop to stop processing; it is
* rather dangerous to use this because this will leave the user with
* no window manager. We generally do this only if, for example, the
* session manager asks us to; we assume the session manager knows
* what it's talking about.
*
* \param code The success or failure code to return to the calling process.
*/
void
meta_quit (MetaExitCode code)
......@@ -579,13 +588,14 @@ meta_quit (MetaExitCode code)
}
/**
* Called on pref changes. (One of several functions of its kind and purpose.)
* prefs_changed_callback:
* @pref Which preference has changed
* @data Arbitrary data (which we ignore)
*
* \bug Why are these particular prefs handled in main.c and not others?
* Should they be?
* Called on pref changes. (One of several functions of its kind and purpose.)
*
* \param pref Which preference has changed
* \param data Arbitrary data (which we ignore)
* FIXME: Why are these particular prefs handled in main.c and not others?
* Should they be?
*/