constraints_experiments is ready

[Elijah Newren <newren gmail com>]

Hi everyone,

I know you're probably all sick of hearing from me but, but I believe the
code on the constraints_experiments branch is ready to merge to head.  I
thought I'd send out a little email summarizing its state and the things
that have changed for those that want to know more about it.  Testing
welcome, especially any extra testing that will assist Havoc in reviewing
these gargantuan changes.  To test:

   cvs -d :pserver:anonymous anoncvs gnome org:/cvs/gnome \
     checkout -r constraints_experiments -d metacity-constraints metacity
   cd metacity-constraints
   ./autogen.sh && make
   ./src/metacity --replace

Cheers,
Elijah


THE DETAILS:
----------------------------------------------------------------------

Testing/Feedback
  - I've been running with it for about a month; I think it works great.  I
    did some of my own usability testing by convincing my wife (typical
    non-expert computer user) to try it out; this helped make sure things
    were sane.  Don't know how much that counts (especially since I have no
    usability training), but hey, it's an extra data point.
  - Olav has been running for a couple days and didn't run across any
    problems -- until less than a minute before I was about to hit send on
    this email.  I'm sending anyway but will look into the issue.
  - Ray tried it out and reported one bug which has been fixed.
  - Bryan responded to my request for usability feedback.  He used it for a
    couple days and reported that "everything seems fine" at this point
    (though he also mentioned that there is some additional testing that
    could be done).
  - Rob and also Soeren did an awesome job of grilling me on some of the
    internals recently; many of their questions/comments helped me refine
    the documentation that I wrote the last couple days.
  - Others may have tried it out but haven't reported back to me yet, and I
    haven't tracked them down and done the requisite feedback extraction.
  - Further testing welcome, especially for xinerama related stuff.  :)

Bugs fixed
  unfiled - constraints.c is overly complicated[1]
  unfiled - constraints.c is not robust when all constraints cannot
            simultaneously be met (constraints need to be prioritized)
  unfiled - keep-titlebar-onscreen constraint is decoration unaware (since
            get_outermost_onscreen_positions() forgets to include
            decorations)
  unfiled - keyboard snap-moving and snap-resizing snap to hidden edges
  109553  - gravity w/ simultaneous move & resize doesn't work
  113601  - maximize vertical and horizontal should toggle and be constrained
  122196  - windows show up under vertical panels
  122670  - jerky/random resizing of window via keyboard[2]
  124582  - keyboard and mouse snap-resizing and snap-moving erroneously
            moves the window multidimensionally
  136307  - don't allow apps to resize themselves off the screen (*cough*
            filechooser *cough*)
  142016, 143784 - windows should not span multiple xineramas unless placed
            there by the user
  143145  - clamp new windows to screensize and force them onscreen, if
            they'll fit
  144126  - Handle pathological strut lists sanely[3]
  149867  - fixed aspect ratio windows are difficult to resize[4]
  152898  - make screen edges consistent; allow easy slamming of windows
            into the left, right, and bottom edges of the screen too.
  154706  - bouncing weirdness at screen edge with keyboard moving or resizing
  156699  - avoid struts when placing windows, if possible (nasty a11y blocker)
  302456  - dragging offscreen too restrictive[5]
  308521  - make uni-directional resizing easier with alt-middle-drag and
            prevent the occasional super annoying resize-the-wrong-side(s)
            behavior
  312007  - snap-resize moves windows with a minimum size constraint
  312104  - resizing the top of a window can cause the bottom to grow
  319351  - don't instantly snap on mouse-move-snapping, remove
            braindeadedness of having order of releasing shift and
            releasing button press matter so much

New feature
   81704 - edge resistance for user move and resize operations; in
           particular 3 different kinds of resistance are implemented:
             Pixel-Distance: window movement is resisted when it aligns
               with an edge unless the movement is greater than a threshold
               number of pixels
             Timeout: window movement past an edge is prevented until a
               certain amount of time has elapsed during the operation
               since the first request to move it past that edge
             Keyboard-Buildup: when moving or resizing with the keyboard,
               once a window is aligned with a certain edge it cannot move
               past until the correct direction has been pressed enough
               times (e.g. 2 or 3 times)

New documentation:
  I have added some documentation, doc/how-constraints-works.txt, to
  supplement inline comments and try to provide a bigger picture view of
  how and why things work to assist others who may want to modify the
  constraints code.

Known issues/questions:
  - I don't know whether XRandR events cause
    workspace.c:meta_workspace_invalidate_work_area() and
    workspace.c:ensure_work_areas_validated() to be called.  I have assumed
    that it does--if it doesn't, my stuff won't work (though I don't think
    the old constraints.c stuff would either).
  - XMMS and other I-wanna-be-my-own-window-manager apps have some issues.
    I can fix the important bits up, just haven't gotten to it yet.
  - Apps can be auto vertically-maximized or auto horizontally-maximized if
    they are too large when initially placed.  Users who aren't aware of
    the separate maximization states *might* find this confusing and try to
    resize from the edge, and then find they are unable.  Should I just
    make them maximal size in the appropriate direction instead and only do
    the auto-maximization if it's needed for both directions?

Other stuff:
  *boxes.[ch]
    A number of low-level error-prone operations (for both constraints and
    edge-resistance) were split out into boxes.[ch].  This makes reading
    code elsewhere much easier and further facilitated the creation of a
    fairly comprehensive testsuite for these operations, testboxes.c (which
    automatically gets compiled into a testboxes program, much like
    testasyncgetprop and testgradient).
  statistics
    According to David Wheeler's sloccount program, the
    constraints_experiments branch has 2865 more lines of code than the
    constraints_experiments branchpoint.  However, edge-resistance.[ch],
    the parts of boxes.c related to edge resistance, and testboxes.c (all
    of which I count exclusively as new stuff) account for 2500 lines.  So,
    I was able to get all those bug fixes in with only adding 365 lines of
    code overall[6].  Wahoo!.


[1] Well, at least I hope so, but I may be biased towards the new
framework.  I think the separation of many operations into boxes.[ch] with
the testcases in testboxes.c helps as well.

[2] Actually, not totally fixed (just annoying instead of almost completely
unusable). Matthias had a suggestion on metacity-devel-list (see
http://tinyurl.com/bwzuu) that may fix the remainder of the problems.

[3] This bug was originally about not-quite-so-pathological cases but was
left open for the worse cases. The code on the branch handles the remainder
of the cases mentioned in this bug.

[4] There's still some bugs with it, namely (A) a slight drift that's only
noticeable after lots of resizing, and (B) nasty interaction with onscreen
constraints. Neither of those are quite so common, though, so I've punted
handling those, and in any event things are *way* nicer on the branch.

[5] Though I've done virtually no testing so I'm not sure if my new simple
formula is too lenient or still too strict. However, any further adjustment
to get it in the right range should be trivial.  Usability feedback
welcome.

[6] The actual numbers are 51,474 lines of code for
CONSTRAINTS_EXPERIMENTS_BRANCHPOINT, and 54,339 constraints_experiments
(running sloccount from under the src/ subdirectory of a clean checkout in
both cases).  Note, though, that a lot of cleanups were enabled by some of
my changes, so this "net change" in lines statistic may be misleading if
you try to use it as a measure of how much changed instead of how
big/complex metacity is now.  In particular, "cvs -q -z3 diff -puN -r
CONSTRAINTS_EXPERIMENTS_BRANCHPOINT | wc -l" run on a
constraints_experiments checkout reports a patch of 14332 lines in length.