Some refactoring, simplifying, and commenting of the non-composited

2008-06-28  Thomas Thurman  <tthurman@gnome.org>

        Some refactoring, simplifying, and commenting of the non-composited
        effects code.  effects.c could still do with some polish, which will
        come along later.

        * src/core/effects.h (meta_push_effect_handler): removed since it's
          never used and does nothing very useful.
        * src/core/effects.h (meta_pop_effect_handler): removed since its
          only effect is to crash the program.
        * src/core/effects.h (META_MINIMIZE_ANIMATION_LENGTH,
          META_SHADE_ANIMATION_LENGTH): move to effects.c because they're used
          nowhere else.
        * src/core/effects.c: there were three versions of the box-zoom effect.
          Remove the one which was never used, and make only the ones which
          are used with certain configure settings be compiled.
        * src/core/effects.h (meta_effect_end): move to effects.c, make static,
          and rename to effect_free.
        * src/core/effects.h (meta_effects_draw_box_animation): move to
          effects.c, make static, and rename to draw_box_animation.
        * src/core/effects.h (MetaEffectType): remove the values which weren't
          used.
        * src/core/window.c (meta_window_shade): remove commented-out code to
          call effect for shading.
        * src/core/effects.h (MetaEffectFinish): remove useless MetaEffect
          parameter.
        * src/core/window.c (finish_minimize): remove MetaEffect parameter.


svn path=/trunk/; revision=3771

4 files changed, 360 insertions, 408 deletions

diff --git a/ChangeLog b/ChangeLog
index 73f86178..3e1ca88d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,30 @@
-        * src/core/stack.c (stack_sync_to_server): lose meta prefix
-          since it's static. 
-
+2008-06-28  Thomas Thurman  <tthurman@gnome.org>
+
+        Some refactoring, simplifying, and commenting of the non-composited
+        effects code.  effects.c could still do with some polish, which will
+        come along later.
+
+        * src/core/effects.h (meta_push_effect_handler): removed since it's
+          never used and does nothing very useful.
+        * src/core/effects.h (meta_pop_effect_handler): removed since its
+          only effect is to crash the program.
+        * src/core/effects.h (META_MINIMIZE_ANIMATION_LENGTH,
+          META_SHADE_ANIMATION_LENGTH): move to effects.c because they're used
+          nowhere else.
+        * src/core/effects.c: there were three versions of the box-zoom effect.
+          Remove the one which was never used, and make only the ones which
+          are used with certain configure settings be compiled.
+        * src/core/effects.h (meta_effect_end): move to effects.c, make static,
+          and rename to effect_free.
+        * src/core/effects.h (meta_effects_draw_box_animation): move to
+          effects.c, make static, and rename to draw_box_animation.
+        * src/core/effects.h (MetaEffectType): remove the values which weren't
+          used.
+        * src/core/window.c (meta_window_shade): remove commented-out code to
+          call effect for shading.
+        * src/core/effects.h (MetaEffectFinish): remove useless MetaEffect
+          parameter.
+        * src/core/window.c (finish_minimize): remove MetaEffect parameter.
 
 2008-06-27  Thomas Thurman  <tthurman@gnome.org>
 
diff --git a/src/core/effects.c b/src/core/effects.c
index 05ccfe08..bbb5cb9a 100644
--- a/src/core/effects.c
+++ b/src/core/effects.c
@@ -1,6 +1,40 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Metacity animation effects */
+/**
+ * \file effects.c "Special effects" other than compositor effects.
+ * 
+ * Before we had a serious compositor, we supported swooping
+ * rectangles for minimising and so on.  These are still supported
+ * today, even when the compositor is enabled.  The file contains two
+ * parts:
+ *
+ *  1) A set of functions, each of which implements a special effect.
+ *     (Only the minimize function does anything interesting; we should
+ *      probably get rid of the rest.)
+ *
+ *  2) A set of functions for moving a highlighted wireframe box around
+ *     the screen, optionally with height and width shown in the middle.
+ *     This is used for moving and resizing when reduced_resources is set.
+ *
+ * There was formerly a system which allowed callers to drop in their
+ * own handlers for various things; it was never used (people who want
+ * their own handlers can just modify this file, after all) and it added
+ * a good deal of extra complexity, so it has been removed.  If you want it,
+ * it can be found in svn r3769.
+ *
+ * Once upon a time there were three different ways of drawing the box
+ * animation: window wireframe, window opaque, and root. People who had
+ * the shape extension theoretically had the choice of all three, and
+ * people who didn't weren't given the choice of the wireframe option.
+ * In practice, though, the opaque animation was never perfect, so it came
+ * down to the wireframe option for those who had the extension and
+ * the root option for those who didn't; there was actually no way of choosing
+ * any other option anyway.  Work on the opaque animation stopped in 2002;
+ * anyone who wants something like that these days will be using the
+ * compositor anyway.
+ *
+ * In svn r3769 this was made explicit.
+ */
 
 /* 
  * Copyright (C) 2001 Anders Carlsson, Havoc Pennington
@@ -21,16 +55,6 @@
  * 02111-1307, USA.
  */
 
-
-/**
- * \file effects.c "Special effects" other than compositor effects.
- * 
- * Before we had a serious compositor, we supported swooping
- * rectangles for minimising and so on.  These are still supported
- * today, even when the compositor is enabled.
- */
-
-
 #include <config.h>
 #include "effects.h"
 #include "display-private.h"
@@ -41,15 +65,13 @@
 #include <X11/extensions/shape.h>
 #endif
 
-#include <string.h>
+#define META_MINIMIZE_ANIMATION_LENGTH 0.25
+#define META_SHADE_ANIMATION_LENGTH 0.2
 
-typedef enum
-{
-  META_ANIMATION_DRAW_ROOT,
-  META_ANIMATION_WINDOW_WIREFRAME,
-  META_ANIMATION_WINDOW_OPAQUE
+#include <string.h>
 
-} MetaAnimationStyle;
+typedef struct MetaEffect MetaEffect;
+typedef struct MetaEffectPriv MetaEffectPriv;
 
 typedef struct
 {
@@ -58,65 +80,85 @@ typedef struct
   double millisecs_duration;
   GTimeVal start_time;
 
-  gboolean first_time;
-
-  MetaRectangle start_rect;
-  MetaRectangle end_rect;
-
-  /* rect to erase */
+#ifdef HAVE_SHAPE
+  /** For wireframe window */
+  Window wireframe_xwindow;
+#else
+  /** Rectangle to erase */
   MetaRectangle last_rect;
 
-  /* used instead of the global flag, since
-   * we don't want to change midstream.
-   */
-  MetaAnimationStyle style;
-  
-  /* For wireframe drawn on root window */
-  GC gc;
+  /** First time we've plotted anything in this animation? */
+  gboolean first_time;
 
-  /* For wireframe window */
-  Window wireframe_xwindow;
-  
-  /* For opaque */
-  MetaImageWindow *image_window;
-  GdkPixbuf       *orig_pixbuf;
+  /** For wireframe drawn on root window */
+  GC gc;
+#endif
 
-  MetaBoxAnimType anim_type;
+  MetaRectangle start_rect;
+  MetaRectangle end_rect;
   
 } BoxAnimationContext;
 
+/**
+ * Information we need to know during a maximise or minimise effect.
+ */
+typedef struct
+{
+  /** This is the normal-size window. */
+  MetaRectangle window_rect;
+  /** This is the size of the window when it's an icon. */
+  MetaRectangle icon_rect;
+} MetaMinimizeEffect, MetaUnminimizeEffect;
+
 struct MetaEffectPriv
 {
   MetaEffectFinished finished;
-  gpointer	     finished_data;
+  gpointer           finished_data;
+};
+
+struct MetaEffect
+{
+  /** The window the effect is applied to. */
+  MetaWindow *window;
+  /** Which effect is happening here. */
+  MetaEffectType type;
+  /** The effect handler can hang data here. */
+  gpointer info;
+
+  union
+  {
+    MetaMinimizeEffect      minimize;
+    /* ... and theoretically anything else */
+  } u;
+  
+  MetaEffectPriv *priv;
 };
 
 static void run_default_effect_handler (MetaEffect *effect);
 static void run_handler (MetaEffect *effect);
+static void effect_free (MetaEffect *effect);
 
-static MetaEffectHandler effect_handler;
-static gpointer		 effect_handler_data;
-
-void
-meta_push_effect_handler (MetaEffectHandler   handler,
-			  gpointer            data)
-{
-    effect_handler = handler;
-    effect_handler_data = data;
-}
+static MetaEffect *
+create_effect (MetaEffectType      type,
+               MetaWindow         *window,
+               MetaEffectFinished  finished,
+               gpointer            finished_data);
 
-void
-meta_pop_effect_handler (void)
-{
-    /* FIXME: not implemented yet */
-    g_assert_not_reached ();
-}
+static void
+draw_box_animation (MetaScreen     *screen,
+                    MetaRectangle  *initial_rect,
+                    MetaRectangle  *destination_rect,
+                    double          seconds_duration);
 
-static MetaEffect *
+/**
+ * Creates an effect.
+ *
+ */
+static MetaEffect*
 create_effect (MetaEffectType      type,
-	       MetaWindow         *window,
-	       MetaEffectFinished  finished,
-	       gpointer		   finished_data)
+               MetaWindow         *window,
+               MetaEffectFinished  finished,
+               gpointer            finished_data)
 {
     MetaEffect *effect = g_new (MetaEffect, 1);
 
@@ -129,14 +171,20 @@ create_effect (MetaEffectType      type,
     return effect;
 }
 
-void
-meta_effect_end (MetaEffect         *effect)
+/**
+ * Destroys an effect.  If the effect has a "finished" hook, it will be
+ * called before cleanup.
+ *
+ * \param effect  The effect.
+ */
+static void
+effect_free (MetaEffect *effect)
 {
-    if (effect->priv->finished)
-	effect->priv->finished (effect, effect->priv->finished_data);
+  if (effect->priv->finished)
+    effect->priv->finished (effect->priv->finished_data);
     
-    g_free (effect->priv);
-    g_free (effect);
+  g_free (effect->priv);
+  g_free (effect);
 }
 
 void
@@ -155,12 +203,13 @@ meta_effect_run_focus (MetaWindow	    *window,
 
 void
 meta_effect_run_minimize (MetaWindow         *window,
-			  MetaRectangle      *window_rect,
-			  MetaRectangle	     *icon_rect,
-			  MetaEffectFinished  finished,
-			  gpointer            data)
+                          MetaRectangle      *window_rect,
+                          MetaRectangle      *icon_rect,
+                          MetaEffectFinished  finished,
+                          gpointer            data)
 {
     MetaEffect *effect;
+    meta_warning ("Well, here we aren't.\n");
 
     g_return_if_fail (window != NULL);
     g_return_if_fail (icon_rect != NULL);
@@ -175,10 +224,10 @@ meta_effect_run_minimize (MetaWindow         *window,
 
 void
 meta_effect_run_unminimize (MetaWindow         *window,
-			    MetaRectangle      *window_rect,
-			    MetaRectangle      *icon_rect,
-			    MetaEffectFinished  finished,
-			    gpointer            data)
+                            MetaRectangle      *window_rect,
+                            MetaRectangle      *icon_rect,
+                            MetaEffectFinished  finished,
+                            gpointer            data)
 {
     MetaEffect *effect;
 
@@ -203,7 +252,7 @@ meta_effect_run_close (MetaWindow         *window,
     g_return_if_fail (window != NULL);
 
     effect = create_effect (META_EFFECT_CLOSE, window,
-			    finished, data);
+                            finished, data);
 
     run_handler (effect);
 }
@@ -211,6 +260,7 @@ meta_effect_run_close (MetaWindow         *window,
 
 /* old ugly minimization effect */
 
+#ifdef HAVE_SHAPE  
 static void
 update_wireframe_window (MetaDisplay         *display,
                          Window               xwindow,
@@ -221,8 +271,6 @@ update_wireframe_window (MetaDisplay         *display,
                      rect->x, rect->y,
                      rect->width, rect->height);
 
-#ifdef HAVE_SHAPE  
-
 #define OUTLINE_WIDTH 3
   
   if (rect->width > OUTLINE_WIDTH * 2 &&
@@ -263,8 +311,8 @@ update_wireframe_window (MetaDisplay         *display,
       XShapeCombineMask (display->xdisplay, xwindow,
                          ShapeBounding, 0, 0, None, ShapeSet);
     }
-#endif
 }
+#endif
 
 /**
  * A hack to force the X server to synchronize with the
@@ -276,9 +324,9 @@ graphics_sync (BoxAnimationContext *context)
   XImage *image;
   
   image = XGetImage (context->screen->display->xdisplay,
-		     context->screen->xroot,
-		     0, 0, 1, 1,
-		     AllPlanes, ZPixmap);
+                     context->screen->xroot,
+                     0, 0, 1, 1,
+                     AllPlanes, ZPixmap);
 
   XDestroyImage (image);
 }
@@ -291,20 +339,20 @@ effects_draw_box_animation_timeout (BoxAnimationContext *context)
   MetaRectangle draw_rect;
   double fraction;
   
+#ifndef HAVE_SHAPE
   if (!context->first_time)
     {
-      if (context->style == META_ANIMATION_DRAW_ROOT)
-        {
-          /* Restore the previously drawn background */
-          XDrawRectangle (context->screen->display->xdisplay,
-                          context->screen->xroot,
-                          context->gc,
-                          context->last_rect.x, context->last_rect.y,
-                          context->last_rect.width, context->last_rect.height);
-        }
+       /* Restore the previously drawn background */
+       XDrawRectangle (context->screen->display->xdisplay,
+                       context->screen->xroot,
+                       context->gc,
+                       context->last_rect.x, context->last_rect.y,
+                       context->last_rect.width, context->last_rect.height);
     }
+  else
+    context->first_time = FALSE;
 
-  context->first_time = FALSE;
+#endif /* !HAVE_SHAPE */
 
   g_get_current_time (&current_time);
   
@@ -323,23 +371,15 @@ effects_draw_box_animation_timeout (BoxAnimationContext *context)
   if (elapsed > context->millisecs_duration)
     {
       /* All done */
-      if (context->style == META_ANIMATION_WINDOW_OPAQUE)
-        {
-          g_object_unref (G_OBJECT (context->orig_pixbuf));
-          meta_image_window_free (context->image_window);
-        }
-      else if (context->style == META_ANIMATION_DRAW_ROOT)
-        {
-          meta_display_ungrab (context->screen->display);
-          meta_ui_pop_delay_exposes (context->screen->ui);
-          XFreeGC (context->screen->display->xdisplay,
-                   context->gc);
-        }
-      else if (context->style == META_ANIMATION_WINDOW_WIREFRAME)
-        {
-          XDestroyWindow (context->screen->display->xdisplay,
+#ifdef HAVE_SHAPE
+        XDestroyWindow (context->screen->display->xdisplay,
                           context->wireframe_xwindow);
-        }
+#else
+        meta_display_ungrab (context->screen->display);
+        meta_ui_pop_delay_exposes (context->screen->ui);
+        XFreeGC (context->screen->display->xdisplay,
+                 context->gc);
+#endif /* !HAVE_SHAPE */
 
       graphics_sync (context);
       
@@ -363,195 +403,99 @@ effects_draw_box_animation_timeout (BoxAnimationContext *context)
     draw_rect.width = 1;
   if (draw_rect.height < 1)
     draw_rect.height = 1;
-  
-  context->last_rect = draw_rect;
 
-  if (context->style == META_ANIMATION_WINDOW_OPAQUE)
-    {
-      GdkPixbuf *scaled;
-
-      scaled = NULL;
-      switch (context->anim_type)
-        {
-        case META_BOX_ANIM_SCALE:
-          scaled = gdk_pixbuf_scale_simple (context->orig_pixbuf,
-                                            draw_rect.width,
-                                            draw_rect.height,
-                                            GDK_INTERP_BILINEAR);
-          break;
-        case META_BOX_ANIM_SLIDE_UP:
-          {
-            int x, y;
-
-            x = context->start_rect.width - draw_rect.width;
-            y = context->start_rect.height - draw_rect.height;
-
-            /* paranoia */
-            if (x < 0)
-              x = 0;
-            if (y < 0)
-              y = 0;
-            
-            scaled = gdk_pixbuf_new_subpixbuf (context->orig_pixbuf,
-                                               x, y,
-                                               draw_rect.width,
-                                               draw_rect.height);
-          }
-          break;
-        }
+#ifdef HAVE_SHAPE
+  update_wireframe_window (context->screen->display,
+                           context->wireframe_xwindow,
+                           &draw_rect);
+#else
+  context->last_rect = draw_rect;
 
-      /* handle out-of-memory */
-      if (scaled != NULL)
-        {
-          meta_image_window_set (context->image_window,
-                                 scaled,
-                                 draw_rect.x, draw_rect.y);
-          
-          g_object_unref (G_OBJECT (scaled));
-        }
-    }
-  else if (context->style == META_ANIMATION_DRAW_ROOT)
-    {
-      /* Draw the rectangle */
-      XDrawRectangle (context->screen->display->xdisplay,
-                      context->screen->xroot,
-                      context->gc,
-                      draw_rect.x, draw_rect.y,
-                      draw_rect.width, draw_rect.height);
-    }
-  else if (context->style == META_ANIMATION_WINDOW_WIREFRAME)
-    {
-      update_wireframe_window (context->screen->display,
-                               context->wireframe_xwindow,
-                               &draw_rect);
-    }
+  /* Draw the rectangle */
+  XDrawRectangle (context->screen->display->xdisplay,
+                  context->screen->xroot,
+                  context->gc,
+                  draw_rect.x, draw_rect.y,
+                  draw_rect.width, draw_rect.height);
+    
+#endif /* !HAVE_SHAPE */
 
   /* kick changes onto the server */
   graphics_sync (context);
   
   return TRUE;
 }
-
-
-/* I really don't want this to be a configuration option, but I think
- * the wireframe is sucky from a UI standpoint (more confusing than
- * opaque), but the opaque is definitely still too slow on some
- * systems, and also doesn't look quite right due to the mapping
- * and unmapping of windows that's going on.
- */
  
-static MetaAnimationStyle animation_style = META_ANIMATION_WINDOW_WIREFRAME;
-
 void
-meta_effects_draw_box_animation (MetaScreen     *screen,
-                                 MetaRectangle  *initial_rect,
-                                 MetaRectangle  *destination_rect,
-                                 double          seconds_duration,
-                                 MetaBoxAnimType anim_type)
+draw_box_animation (MetaScreen     *screen,
+                    MetaRectangle  *initial_rect,
+                    MetaRectangle  *destination_rect,
+                    double          seconds_duration)
 {
   BoxAnimationContext *context;
 
+#ifdef HAVE_SHAPE
+  XSetWindowAttributes attrs;
+#else
+  XGCValues gc_values;
+#endif
+    
   g_return_if_fail (seconds_duration > 0.0);
 
   if (g_getenv ("METACITY_DEBUG_EFFECTS"))
     seconds_duration *= 10; /* slow things down */
   
   /* Create the animation context */
-  context = g_new0 (BoxAnimationContext, 1);	
+  context = g_new0 (BoxAnimationContext, 1);
 
   context->screen = screen;
 
   context->millisecs_duration = seconds_duration * 1000.0;
-  context->first_time = TRUE;
+
   context->start_rect = *initial_rect;
   context->end_rect = *destination_rect;
-  context->anim_type = anim_type;
 
-  context->style = animation_style;
+#ifdef HAVE_SHAPE
 
-#ifndef HAVE_SHAPE
-  if (context->style == META_ANIMATION_WINDOW_WIREFRAME)
-    context->style = META_ANIMATION_DRAW_ROOT;
-#endif
-  
-  if (context->style == META_ANIMATION_WINDOW_OPAQUE)
-    {
-      GdkPixbuf *pix;
-      
-      pix = meta_gdk_pixbuf_get_from_window (NULL,
-                                             screen->xroot,
-                                             initial_rect->x,
-                                             initial_rect->y,
-                                             0, 0,
-                                             initial_rect->width,
-                                             initial_rect->height);
-
-      if (pix == NULL)
-        {
-          /* Fall back to wireframe */
-          context->style = META_ANIMATION_WINDOW_WIREFRAME;
-        }
-      else
-        {
-          context->image_window = meta_image_window_new (screen->display->xdisplay,
-                                                         screen->number,
-                                                         initial_rect->width,
-                                                         initial_rect->height);
-          context->orig_pixbuf = pix;
-          meta_image_window_set (context->image_window,
-                                 context->orig_pixbuf,
-                                 initial_rect->x,
-                                 initial_rect->y);
-          meta_image_window_set_showing (context->image_window, TRUE);
-        }
-    }
+  attrs.override_redirect = True;
+  attrs.background_pixel = BlackPixel (screen->display->xdisplay,
+                                       screen->number);
 
-  /* Not an else, so that fallback works */
-  if (context->style == META_ANIMATION_WINDOW_WIREFRAME)
-    {
-      XSetWindowAttributes attrs;
-
-      attrs.override_redirect = True;
-      attrs.background_pixel = BlackPixel (screen->display->xdisplay,
-                                           screen->number);
-
-      context->wireframe_xwindow = XCreateWindow (screen->display->xdisplay,
-                                                  screen->xroot,
-                                                  initial_rect->x,
-                                                  initial_rect->y,
-                                                  initial_rect->width,
-                                                  initial_rect->height,
-                                                  0,
-                                                  CopyFromParent,
-                                                  CopyFromParent,
-                                                  (Visual *)CopyFromParent,
-                                                  CWOverrideRedirect | CWBackPixel,
-                                                  &attrs);
-
-      update_wireframe_window (screen->display,
-                               context->wireframe_xwindow,
-                               initial_rect);
-
-      XMapWindow (screen->display->xdisplay,
-                  context->wireframe_xwindow);
-    }
-  
-  if (context->style == META_ANIMATION_DRAW_ROOT)
-    {
-      XGCValues gc_values;
-      
-      gc_values.subwindow_mode = IncludeInferiors;
-      gc_values.function = GXinvert;
+  context->wireframe_xwindow = XCreateWindow (screen->display->xdisplay,
+                                              screen->xroot,
+                                              initial_rect->x,
+                                              initial_rect->y,
+                                              initial_rect->width,
+                                              initial_rect->height,
+                                              0,
+                                              CopyFromParent,
+                                              CopyFromParent,
+                                              (Visual *)CopyFromParent,
+                                              CWOverrideRedirect | CWBackPixel,
+                                              &attrs);
 
-      context->gc = XCreateGC (screen->display->xdisplay,
-                               screen->xroot,
-                               GCSubwindowMode | GCFunction,
-                               &gc_values);
+  update_wireframe_window (screen->display,
+                           context->wireframe_xwindow,
+                           initial_rect);
+
+  XMapWindow (screen->display->xdisplay,
+              context->wireframe_xwindow);
+
+#else /* !HAVE_SHAPE */
+
+  context->first_time = TRUE;
+  gc_values.subwindow_mode = IncludeInferiors;
+  gc_values.function = GXinvert;
+
+  context->gc = XCreateGC (screen->display->xdisplay,
+                           screen->xroot,
+                           GCSubwindowMode | GCFunction,
+                           &gc_values);
       
-      /* Grab the X server to avoid screen dirt */
-      meta_display_grab (context->screen->display);
-      meta_ui_push_delay_exposes (context->screen->ui);
-    }
+  /* Grab the X server to avoid screen dirt */
+  meta_display_grab (context->screen->display);
+  meta_ui_push_delay_exposes (context->screen->ui);
+#endif
 
   /* Do this only after we get the pixbuf from the server,
    * so that the animation doesn't get truncated.
@@ -770,28 +714,20 @@ run_default_effect_handler (MetaEffect *effect)
     switch (effect->type)
     {
     case META_EFFECT_MINIMIZE:
-	meta_effects_draw_box_animation (effect->window->screen,
-					 &(effect->u.minimize.window_rect),
-					 &(effect->u.minimize.icon_rect),
-					 META_MINIMIZE_ANIMATION_LENGTH,
-					 META_BOX_ANIM_SCALE);
-	break;
+       draw_box_animation (effect->window->screen,
+                     &(effect->u.minimize.window_rect),
+                     &(effect->u.minimize.icon_rect),
+                     META_MINIMIZE_ANIMATION_LENGTH);
+       break;
 
     default:
-	break;
+       break;
     }
 }
 
 static void
 run_handler (MetaEffect *effect)
 {
-    if (effect_handler)
-    {
-	effect_handler (effect, effect_handler_data);
-    }
-    else
-    {
-	run_default_effect_handler (effect);
-	meta_effect_end (effect);
-    }
+  run_default_effect_handler (effect);
+  effect_free (effect);
 }
diff --git a/src/core/effects.h b/src/core/effects.h
index b72a7979..91d09e15 100644
--- a/src/core/effects.h
+++ b/src/core/effects.h
@@ -1,6 +1,27 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Metacity animation effects */
+/**
+ * \file effects.h "Special effects" other than compositor effects.
+ * 
+ * Before we had a serious compositor, we supported swooping
+ * rectangles for minimising and so on.  These are still supported
+ * today, even when the compositor is enabled.  The file contains two
+ * parts:
+ *
+ *  1) A set of functions, each of which implements a special effect.
+ *     (Only the minimize function does anything interesting; we should
+ *      probably get rid of the rest.)
+ *
+ *  2) A set of functions for moving a highlighted wireframe box around
+ *     the screen, optionally with height and width shown in the middle.
+ *     This is used for moving and resizing when reduced_resources is set.
+ *
+ * There was formerly a system which allowed callers to drop in their
+ * own handlers for various things; it was never used (people who want
+ * their own handlers can just modify this file, after all) and it added
+ * a good deal of extra complexity, so it has been removed.  If you want it,
+ * it can be found in svn r3769.
+ */
 
 /* 
  * Copyright (C) 2001 Anders Carlsson, Havoc Pennington
@@ -27,116 +48,104 @@
 #include "util.h"
 #include "screen-private.h"
 
-typedef struct MetaEffect MetaEffect;
-typedef struct MetaEffectPriv MetaEffectPriv;
-
-#define META_MINIMIZE_ANIMATION_LENGTH 0.25
-#define META_SHADE_ANIMATION_LENGTH 0.2
-
-typedef enum
-{
-  META_BOX_ANIM_SCALE,
-  META_BOX_ANIM_SLIDE_UP
-
-} MetaBoxAnimType;
-
 typedef enum
 {
   META_EFFECT_MINIMIZE,
   META_EFFECT_UNMINIMIZE,
-  META_EFFECT_MENU_MAP,
-  META_EFFECT_MENU_UNMAP,
-  META_EFFECT_DIALOG_MAP,
-  META_EFFECT_DIALOG_UNMAP,
-  META_EFFECT_TOPLEVEL_MAP,
-  META_EFFECT_TOPLEVEL_UNMAP,
-  META_EFFECT_WIREFRAME_BEGIN,
-  META_EFFECT_WIREFRAME_UPDATE,
-  META_EFFECT_WIREFRAME_END,
   META_EFFECT_FOCUS,
   META_EFFECT_CLOSE,
   META_NUM_EFFECTS
 } MetaEffectType;
 
-typedef void (* MetaEffectHandler) (MetaEffect *effect,
-				    gpointer    data);
-typedef void (* MetaEffectFinished) (const MetaEffect *effect,
-				     gpointer	      data);
-
-typedef struct
-{
-  MetaRectangle window_rect;
-  MetaRectangle icon_rect;
-} MetaMinimizeEffect, MetaUnminimizeEffect;
-
-#if 0
-/* Solaris abhors an empty struct. #397296. */
-typedef struct
-{
-    
-} MetaCloseEffect;
-
-typedef struct
-{
-} MetaFocusEffect;
-#endif
-
-struct MetaEffect
-{
-  MetaWindow *window;
-  MetaEffectType type;
-  gpointer info;		/* effect handler can hang data here */
-  
-  union
-  {
-    MetaMinimizeEffect	    minimize;
-    MetaUnminimizeEffect    unminimize;
-#if 0
-    /* These don't currently exist, so we aren't using them. #397296. */
-    MetaCloseEffect	    close;
-    MetaFocusEffect	    focus;
-#endif
-  } u;
-  
-  MetaEffectPriv *priv;
-};
-
-void        meta_push_effect_handler (MetaEffectHandler   handler,
-				      gpointer            data);
-void	    meta_pop_effect_handler  (void);
+/**
+ * A callback which will be called when the effect has finished.
+ */
+typedef void (* MetaEffectFinished) (gpointer    data);
 
+/**
+ * Performs the minimize effect.
+ *
+ * \param window       The window we're moving
+ * \param window_rect  Its current state
+ * \param target       Where it should end up
+ * \param finished     Callback for when it's finished
+ * \param data         Data for callback
+ */
 void        meta_effect_run_minimize     (MetaWindow         *window,
-					  MetaRectangle	     *window_rect,
-					  MetaRectangle	     *target,
-					  MetaEffectFinished  finished,
-					  gpointer            data);
+                                          MetaRectangle	     *window_rect,
+                                          MetaRectangle	     *target,
+                                          MetaEffectFinished  finished,
+                                          gpointer            data);
+
+/**
+ * Performs the unminimize effect.  There is no such effect.
+ * FIXME: delete this.
+ *
+ * \param window       The window we're moving
+ * \param icon_rect    Its current state
+ * \param window_rect  Where it should end up
+ * \param finished     Callback for when it's finished
+ * \param data         Data for callback
+ */
 void        meta_effect_run_unminimize (MetaWindow         *window,
-					MetaRectangle      *window_rect,
-					MetaRectangle	     *icon_rect,
-					MetaEffectFinished  finished,
-					gpointer            data);
+                                          MetaRectangle      *window_rect,
+                                          MetaRectangle      *icon_rect,
+                                          MetaEffectFinished  finished,
+                                          gpointer            data);
+
+/**
+ * Performs the close effect.  There is no such effect.
+ * FIXME: delete this.
+ *
+ * \param window       The window we're moving
+ * \param finished     Callback for when it's finished
+ * \param data         Data for callback
+ */
 void        meta_effect_run_close        (MetaWindow         *window,
-					  MetaEffectFinished  finished,
-					  gpointer            data);
-void        meta_effect_run_focus        (MetaWindow         *window,
-					  MetaEffectFinished  finished,
-					  gpointer            data);
-void        meta_effect_end              (MetaEffect         *effect);
-
-
-
-/* Stuff that should become static functions */
-
-void meta_effects_draw_box_animation (MetaScreen     *screen,
-                                      MetaRectangle  *initial_rect,
-                                      MetaRectangle  *destination_rect,
-                                      double          seconds_duration,
-                                      MetaBoxAnimType anim_type);
+                                          MetaEffectFinished  finished,
+                                          gpointer            data);
 
+/**
+ * Performs the focus effect.  There is no such effect.
+ * FIXME: delete this.
+ *
+ * \param window       The window we're moving
+ * \param finished     Callback for when it's finished
+ * \param data         Data for callback
+ */
+void        meta_effect_run_focus        (MetaWindow         *window,
+                                          MetaEffectFinished  finished,
+                                          gpointer            data);
+
+/**
+ * Grabs the server and paints a wireframe rectangle on the screen.
+ * Since this involves starting a grab, please be considerate of other
+ * users and don't keep the grab for long.  You may move the wireframe
+ * around using meta_effects_update_wireframe() and remove it, and undo
+ * the grab, using meta_effects_end_wireframe().
+ *
+ * \param screen  The screen to draw the rectangle on.
+ * \param rect    The size of the rectangle to draw.
+ * \param width   The width to display in the middle (or 0 not to)
+ * \param height  The width to display in the middle (or 0 not to)
+ */
 void meta_effects_begin_wireframe  (MetaScreen          *screen,
                                     const MetaRectangle *rect,
                                     int                  width,
                                     int                  height);
+
+/**
+ * Moves a wireframe rectangle around after its creation by
+ * meta_effects_begin_wireframe().  (Perhaps we ought to remember the old
+ * positions and not require people to pass them in?)
+ *
+ * \param old_rect  Where the rectangle is now
+ * \param old_width The width that was displayed on it (or 0 if there wasn't)
+ * \param old_height The height that was displayed on it (or 0 if there wasn't)
+ * \param new_rect  Where the rectangle is going
+ * \param new_width The width that will be displayed on it (or 0 not to)
+ * \param new_height The height that will be displayed on it (or 0 not to)
+ */
 void meta_effects_update_wireframe (MetaScreen          *screen,
                                     const MetaRectangle *old_rect,
                                     int                  old_width,
@@ -144,6 +153,15 @@ void meta_effects_update_wireframe (MetaScreen          *screen,
                                     const MetaRectangle *new_rect,
                                     int                  new_width,
                                     int                  new_height);
+
+/**
+ * Removes a wireframe rectangle from the screen and ends the grab started by
+ * meta_effects_begin_wireframe().
+ *
+ * \param old_rect  Where the rectangle is now
+ * \param old_width The width that was displayed on it (or 0 if there wasn't)
+ * \param old_height The height that was displayed on it (or 0 if there wasn't)
+ */
 void meta_effects_end_wireframe    (MetaScreen          *screen,
                                     const MetaRectangle *old_rect,
                                     int                  width,
diff --git a/src/core/window.c b/src/core/window.c
index 6d9d314f..b2e7300f 100644
--- a/src/core/window.c
+++ b/src/core/window.c
@@ -1412,8 +1412,7 @@ meta_window_should_be_showing (MetaWindow  *window)
 }
 
 static void
-finish_minimize (const MetaEffect *effect,
-		 gpointer	   data)
+finish_minimize (gpointer data)
 {
   MetaWindow *window = data;
   /* FIXME: It really sucks to put timestamp pinging here; it'd
@@ -1440,11 +1439,11 @@ implement_showing (MetaWindow *window,
   /* Actually show/hide the window */
   meta_verbose ("Implement showing = %d for window %s\n",
                 showing, window->desc);
-   
+    
   if (!showing)
     {
       gboolean on_workspace;
-      
+
       on_workspace = meta_window_located_on_workspace (window, 
                                                        window->screen->active_workspace);
       
@@ -1484,7 +1483,7 @@ implement_showing (MetaWindow *window,
         }
       else
         {
-          finish_minimize (NULL, window);
+          finish_minimize (window);
         }
     }
   else
@@ -2776,31 +2775,7 @@ meta_window_shade (MetaWindow  *window,
   meta_topic (META_DEBUG_WINDOW_OPS,
               "Shading %s\n", window->desc);
   if (!window->shaded)
-    {
-#if 0
-      if (window->mapped)
-        {
-          /* Animation */
-          MetaRectangle starting_size;
-          MetaRectangle titlebar_size;
-          
-          meta_window_get_outer_rect (window, &starting_size);
-          if (window->frame)
-            {
-              starting_size.y += window->frame->child_y;
-              starting_size.height -= window->frame->child_y;
-            }
-          titlebar_size = starting_size;
-          titlebar_size.height = 0;
-          
-          meta_effects_draw_box_animation (window->screen,
-                                           &starting_size,
-                                           &titlebar_size,
-                                           META_SHADE_ANIMATION_LENGTH,
-                                           META_BOX_ANIM_SLIDE_UP);
-        }
-#endif
-      
+    {      
       window->shaded = TRUE;
 
       meta_window_queue(window, META_QUEUE_MOVE_RESIZE | META_QUEUE_CALC_SHOWING);
@@ -3874,7 +3849,6 @@ meta_window_get_wireframe_geometry (MetaWindow    *window,
                                     int           *width,
                                     int           *height)
 {
-
   if (!window->display->grab_wireframe_active)
     return;