DBus interface for magnifiers

[Joseph Scheuhammer <clown utoronto ca>]

All,

Joanie, Carlos, Will, and I have been discussing what the DBus API 
should be for a gnome magnifier service, as well as trying to figure the 
appropriate roles for DBus vs. GConf (or, GSettings, in the future).

The following is my thoughts as a reply to both Joanie and Carlos.  At 
last week's gnome #a11y irc meeting, it was suggested that I submit this 
to the gnome a11y interest list for broader input.

First, a bit of background:  there are two magnifiers on the horizon.  
Carlos is porting the current CORBA based gnome-mag service to DBus.  I 
am adding patches to GnomeShell to provide magnification functionality 
withing GnomeShell itself -- let's call it GS-mag.  As part of the 
GS-mag effort, I am providing a DBus interface so that processes outside 
of GnomeShell (e.g., Orca), can make use of GS-mag in the same way it 
would make use of gnome-mag.

Also, all of gnome-mag's user preferences are handled and persisted by 
Orca, currently.  That is, Orca provides a dialog for setting things 
like magnification factor, mouse tracking modes, and so on.  It uses 
DBus to request that gnome-mag configure itself appropriately.  When 
Orca quits, it stores all of the magnifier preferences within some Orca 
preferences document such that when the magnifier is re-launched, Orca 
sets it back to what it was.

Magnifier DBus Methods (General)
--------- ---- ------- ---------

Joanie wrote:
> > Joseph wrote:
> > >  (3) Methods.
> > >  At the moment, GS-mag implements only a subset of what gnome-mag
> > >  provides.  There are a number of issues here:
> > >  - What methods should a magnifier DBus service provide?  Or, should we
> > >  just maintain the status quo as defined by the old CORBA
> > >  implementation?  Carlos has contacted me with the same question.
> >
> >  Good question.... I'll toss out the following for your consideration:
> >
> >  * If it is a command that an AT like Orca can execute, and
> >  * If that command exists in either GS-mag or gnome-mag or both
> >
> >  the DBus service should provide it as a method. If a given magnifier
> >  doesn't implement that functionality, then that magnifier's method can
> >  return a value that communicates this to the caller.
> >
> >  Once we examine the proposed list of methods, we might want to add some
> >  functionality that doesn't (yet) exist in either magnifier but which we
> >  suspect might be implemented in at least one down the road (i.e. 
> > because
> >  it's the sort of thing that users coming from other platforms have
> >  indicated a need or desire for).
Fair enough.

The Proposed shiftContentsTo(x,y) DBus Method
--- -------- -------------------- ---- ------
I wrote:

>  A related, detailed aside:  Will made a specific request for a Dbus
>  method that, given a point on the desktop, centres the magnified view on
>  that point.  The signature in pseudo C is : void shiftContentsTo (int x,
>  int y);  Or, in JSON/Dbus:  { name: "shiftContentsTo", inSignature:
>  "ii", outSignature: "" }.  There was such a method in GS-mag's Dbus
>  implementation at one point, but I removed it to be in sync with
>  gnome-mag.  It would be trivial to put back into gs-mag, but it might be
>  tricky for gnome-mag.  Carlos would have a better idea here.

Joanie replied:
> I think that functionality would be good to have, ideally in both, but
> if it's only doable in one so be it. Please put it back in GS-mag. If
> it's tricky or impossible to implement in gnome-mag, gnome-mag could
> always add a stub method which returns NULL or False.
>    

I vote for it to return True/False.

About shiftContentsTo(), Carlos asked:
> It's possible in gnome-mag. How it must be implemented, the magnified
> area must center to the x and y values passed?
It's sort of the flip of setRoi().  For setRoi(), Orca passes a 
rectangle in screen coordinates that defines the region on the desktop 
to magnify, and the magnifier places that rectangle in the magnified view.

shiftContentsTo() takes a coordinate that is the centre of the 
region-of-interest.   The magnifier shifts the contents in the magnified 
view such that the given point is now centred within it.  As a 
consequence, the (left, top, width, height) of the magnified view is the 
new roi.  Note that the actual roi is not calculated, it simply follows 
from the size of the magnified view.


GConf/GSettings and On-the-fly Changes
--------------- --- ---------- -------
Joanie wrote:
> but what about "on the fly" changes? For instance, a
>  user might prefer 3x magnification with inversed brightness. These
>  settings would presumably be saved in GConf. Then along comes this web
>  page with fixed, and very tiny white text on a black background. 3x is
>  not enough magnification to read it comfortably and inversing the page's
>  inversed colors makes the content hard to read at any size. If I'm
>  following what you propose above, when this user gives the Orca command
>  to increase the magnification factor and turn off inversed brightness,
>  these functionally-temporary values are going to be changed in GConf
>  becoming the new, stored settings. This is not desirable as it requires
>  either the user or the app to store the original values before making
>  any changes on the fly and then restore them all in the end. I'm all for
>  using GConf, but I **think** that we'll need DBus methods for these 
> sorts
>  of things as well. 
Okay... from this I conclude that "on the fly" changes are to be done 
using DBus, whereas persistent changes are done with GConf.  As a point 
of reference, GS-mag is already sensitive to some user preferences via 
GConf -- magnification factor is one of them.  GS-mag is listening for 
changes in these GConf settings.  Thus, if any app changes a GConf 
setting, the magnifier will react as appropriate.  Concrete example:  if 
the GConf setting for magnification factor changes, then the magnifier 
live-updates appropriately.  But... GS-mag is also supporting changes to 
some of these preferences via DBus.  Again, magnification factor is one 
of them.

Thus, there are two ways to make GS-mag change:  via GConf, and via 
DBus.  Given that, and your "on the fly" example, it follows that if 
Orca wants to make a persistent change in magnification factor, it 
should call upon GConf.  If Orca wants to make an on-the-fly change to 
magnification factor, it uses the DBus method.  Similarly for any other 
setting.  That sounds like there is complete duplication between GConf 
and DBus -- the only difference is their intended use:  on-the-fly vs. 
persistent.  If this is what follows, I can provide both.

Still, an issue is how Orca knows when it's "on-the-fly" vs. 
persistent?  But, I guess that's Orca's problem :-).

Aside:  for what it's worth, specifically for magnification factor, I 
think one handles "on-the-fly" changes with a quick gesture, like a 
keystroke, or some form of mouse wheel event.  If it's that easy for the 
user to quickly change magnification factor -- no dialog required -- 
then using GConf for it is fine since the user can rapidly switch back 
and forth.  Alas, I doubt one can do that for all the preferences since 
(1) one would run out of keystrokes, (2) some changes are more complex 
that just a change in a number.

Proposed DBus Methods
-------- ---- -------
Carlos wrote:
> Methods that I think are irrelevant for GS-mag or can be removed:
> {get,set}TargetDisplay
> {get,set}SourceDisplay
I'm not sure.  Does this have anything to do with multiple displays?  
GS-mag has to handle the case where users configure the magnifier 
differently on different displays.  They might have to remain for that; 
I don't know at this point.

> updatePointer - This have to be removed anyway, this was a hack due
> the use of CORBA, now with D-BUS this isn't necessary anymore.
Okay.
> markDirty
What does markDirty do?  I suspect it's not needed in GS-mag.
> {set,get}SmoothScroll - I think Orca don't use it anymore and I don't
> think it's still relevant for gnome-mag. Better performance can be
> achieved other ways. I guess that this code is related with old gtk+
> stuff, so remove it will be interesting from my POV.
Okay.
> {set,get}TestPattern
I don't have good feel for this one -- what was the purpose of the test 
pattern?  If that use case is still valid, then I'd vote to keep this.  
Otherwise, let's drop it.
> I guess that GS-mag already have some tracking mouse modes, I will
> also do it in gnome-mag. So we have a new method, can we call it
> {set,get}MouseTracking?
Interesting ... Orca has preferences in its magnifier tab for setting 
the mouse tracking mode.  How does it communicate that currently to the 
magnifier (if not by CORBA/DBus)?  This is one of the settings that 
GS-mag support via GConf, and only via GConf.  I could add it to the 
DBus interface for on-the-fly changes.
> Methods that I think can be removed with the include of the above 
> function:
> {get,set}Roi
For those who don't know, "setRoi()" means "set the region of 
interest".  GTK apps have some form of keyboard navigation and 
activation for users who don't use a mouse.  Orca has the ability to 
determine what GUI widget currently has keyboard focus, calculate a 
region-of-interest based on that, and then tell the magnifier to magnify 
that region.  This is done independent of where the mouse is, and, as 
the user tab-navigates the user interface, the magnified contents update 
to the currently focussed item.  In the case of text, the Roi includes 
the insertion, and it is followed as the user types.

By "the above function", do you mean the proposed "shiftContentsTo()"?  
I think you're right in terms of it replacing setRoi().  But I think 
getRoi() is still required, or something like it, since Orca may want to 
query the magnifier in terms of what is currently magnified.
> {set,get}PollMouse
Does this just change the frequency of mouse polling?  If so, okay.
> {set,get}DrawCursos - this is called by Orca when in full-screen mode,
> so the X cursor is disabled (not the cursor draw in the zoom-region).
> I think this can be an internal implementation like this: if (cursor
> over magnifier_screen) hide_it; else show_it;
GS-mag does this internally.  That is, it already knows where the X 
cursor is, and show/hides it as you describe.  If gnome-mag can do 
something similar, that would be great.

> {set,get}XAlign
> {set,get}YAlign
> {set,get}TimingTest
> {set,get}TimingOutput
> {set,get}TimingPanRate
>
> The methods {set,get}Managed don't have any effect in the actual
> implementation and I also don't know what they intended to be, so I
> think that they can be removed. 

I'm not sure what the above methods do, so I don't have an opinion 
regarding their removal.

> Joseph wrote:
> >>
> >>  GConf
> >>  - show/hide magnifier
>    
> GS-mag has a DBus interface to show/hide the magnifier? What is it signature?
>
>    

It's called setActive(), and takes a boolean.  Formally:
{ name: 'setActive', inSignature: 'b', outSignature: '' }.

Whew!  That's a lot of material.  Maybe we should start a Wiki page for 
this discussion?\

--
;;;;joseph

'Clown control to Mao Tse Tung.'
 - D. Bowie (misheard lyric) -