Re: [g-a-devel] mag.py and Compiz' Enhanced Zoom

["Kristian Lyngstøl" <kristian bohemians org>]

On 8/20/07, Willie Walker <William Walker sun com> wrote:
> > I've more or less finished the Enhanced Zoom plugin for Compiz, and it
> > is able to do much of what orca already does.
>
> Yeah!  Do you have a pointer for where I can grab an eZoom to play with
> on Gutsy?  In addition, do you have a user base that you've been working
> with?  I'd like to read the archives to get a better understanding of
> what their questions/requirements are.

It is already in gutsy, in the compiz-fusion-plugins-main package.
This would, obviously, require a working compiz setup.

So far my userbase have been somewhat limited to traditional Compiz
Fusion users. I have gotten input on my blog [1] and on the ubuntu
forums [2] but the majority of ideas were defined in the original
project plan for the summer of code project or found during my
meetings with Henrik Omma, with some significant ideas given to me
over IRC from other Compiz Fusion developers.

The majority of ideas have been related to the mouse code which is
tricky with fullscreen magnification when there is no input
redirection (I did not want to use xevie or similar in anticipation of
"real" input redirection/transformation). Be it mouse panning
(present), restraining (present), centering, scaling or the XFixes
related bugs.

> > I was testing out the dbus interface with orca and realized that the
> > way orca handles text-caret events is somewhat less than optimal for
> > ezoom.
>
> Do you have a pointer to the DBUS interface?

I haven't actually documented it properly yet outside the source code,
which should be pretty good (in my eyes, I do like documentation more
than most Compiz Fusion developers).

It uses Compiz' dbus plugin which means a DBus interface is granted
for free, so to speak. There is some extremely limited information on
the Compiz web pages [3], but not really worth reading. However, the
interface doesn't consist of dark magic, it's fairly straight forward.

I've used a script like this to test:

#!/bin/bash
dbus-send --type=method_call --dest=org.freedesktop.compiz
/org/freedesktop/compiz/$1/allscreens/$2
org.freedesktop.compiz.activate string:'root' int32:`xwininfo -root |
grep id: | awk '{ print $4 }'` $3 $4 $5 $6 $7 $8 $9 ${10} ${11} ${12}
${13} ${14}

And call it with

 ./dsend.sh ezoom ensure_visibility string:x1 int32:10 string:y1 int32:15

for example. Similar feats can be done in any language that has DBus
bindings. This will make sure the point (10,15) on the screen is
visible by adjusting the current zoom translations, regardless of the
zoom level in effect.

I did have an API file, but it seemed a bit strange given the very
limited amount of functions and that it grew out of date and
duplicated information in the source. I do intend to recreate this
when I am somewhat certain that the interface is stable. And when
Compiz Fusion FINALLY has a wiki/web page of it's own. The
documentation from ezoom.c on ensure_visibility reads:

/* Ensure visibility of an area defined by x1->x2/y1->y2
 * int:x1: left X coordinate
 * int:x2: right X Coordinate
 * int:y1: top Y coordinate
 * int:y2: bottom Y coordinate
 * bool:scale: zoom out if necesarry to ensure visibility
 * bool:restrain: Restrain the mouse cursor
 * int:margin: The margin to use (default: 0)
 * if x2/y2 is omitted, it is ignored.
 */

At the moment I have been refining the details of the implementation
to add gravity. A similar interface for setting the center or actual
zoom area is available set_zoom_area:

/* Set the zoom area
 * This is an interface for scripting.
 * int32:x1: left x coordiante
 * int32:y1: top y coordinate
 * int32:x2: right x
 * int32:y2: bottom y
 * x2 and y2 can be omitted to assume x2==x1+1 y2==y1+1
 * boolean:scale: True if we should modify the zoom level, false to just
 *                adjust the movement/translation.
 * boolean:restrain: True to warp the pointer so it's visible.
 */

This would allow you to set the center by simply omitting x2/y2.

As these two interfaces are not yet in active use, it makes sense to
adjust them to the need. Technically there are more ways of sending
information to the plugin, but this is because every key binding is
available over DBus (like pan_left, zoom_in, etc).

> > With mouse events, everything works perfectly. You can use orca
> > instead of the built in mouse panning to control ezoom over dbus. It's
> > dead on. However, text caret events are not.
>
> If eZoom is getting all that it needs via the AT-SPI, I'm thinking Orca
> should only reserve communicating with eZoom for things that cannot be
> gleaned via AT-SPI events.  These include things such as Orca's flat
> review mechanism and SayAll support.

eZoom actually doesn't use AT-SPI at all at the moment, but is able to
get information about mouse movements by polling  (it's not pretty,
but it's is somewhat intermediary until the long-awaited input
transformation in x.org) and XFixes. Focus is of course pretty easy to
track for a window manager. My tests indicate that polling the mouse
isn't really an issue for the time being, it is how things was done in
Beryl's inputzoom too, and I haven't seen a single complaint about the
performance.

> > Ezoom uses a rather simple interface for this: ensure_visibility. The
> > idea is to pass it exactly what you want to make sure is visible,
> > nothing more or less. An x1/y1 and an x2/y2 pair in screen
> > coordinates. Ezoom will calculate how much it needs to move and in
> > which direction by it self. You can also pass "scale: true" to make it
> > adjust the zoom level (this is somewhat untested except the most basic
> > technical test).
>
> Without having observed what it happening, I'm guessing this seems to go
> on the principle of least movement.  We've had end users request certain
> behaviors depending upon what they are doing.  For example, when typing,
> some users want the caret to stay in the middle of the magnified region.

You are probably right. I do think we can accommodate this by using
either ensure_visiblity, which by nature is based on the principle of
least movement, or set_zoom_area if the user prefers to center the
zoomed area on the caret. This will require some testing, of course.

> I suspect they will want the same for the character-by-character
> movement of flat review.  Handling this might require a bit more of a
> sophisticated communication mechanism between Orca and eZoom.  One thing
> I was thinking about was a more general purpose DBUS broadcast mechanism
> that clients such as Orca can use to announce where it is listening and
> why.  This would allow plugins such as eZoom to make informed choices
> about where to move the magnifier.

What sort of information would be transmitted over this system, and
who do you imagine to be listeners except screen magnifiers?

[1] http://dev.beryl-project.org/~kristian/category/summer-of-code/
[2] http://ubuntuforums.org/showthread.php?t=508946
[3] http://compiz.org/Scripting_Compiz

- Kristian