Re: [g-a-devel]gnome-mag IDL

[Bill Haneman <bill haneman sun com>]

On Mon, 2002-09-16 at 14:43, Bill Haneman wrote:
> On Mon, 2002-09-16 at 15:28, Michael Meeks wrote:
> 
> > 	First of all; I'd bin the 'out long x1, y1, x2, y2' business,
> > completely;
> > 
> > 	I would personally have a:
> > 
> > struct Dimensions {
> > 	long x, y;
> > 	long width, height;
> > };

Hi:

I attach what I hope is an acceptable IDL for gnome-mag; if you have
significant issues please let me know and we'll resolve them.  In the
meantime this is what I expect to be implementing in the next couple of
days, the first step being creation of the Bonobo objects for the
ZoomRegions.  From there it should be fairly straightforward to connect
this to the existing gnome-mag implementation code in
gnome-mag/magnifier.

One thing: I created a struct as above, but called it RectBounds.  It
appears to be in the GNOME namespace at the moment; 

Michael, does this seem OK or should I call it something like
MagRectBounds or MagLongBounds ?  Perhaps there is another way of
putting it in Magnifier's scope without colliding with some future GNOME
"RectBounds" struct...

regards,

Bill

/* 
 * AT-SPI - Assistive Technology Service Provider Interface 
 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
 *
 * Copyright 2001 Sun Microsystems Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#ifndef _GNOME_MAGNIFIER_IDL
#define _GNOME_MAGNIFIER_IDL

#include <Bonobo_Unknown.idl>
#include <Bonobo_Property.idl>

module GNOME {

  struct RectBounds {
	  long x1, y1, x2, y2;
  };

  
  interface ZoomRegion : Bonobo::Unknown {

    /**
     * void setMagFactor: sets the current x and y magnification ratio.
     * (Convenience method for setting mag-factor-x and mag-factor-y properties).
     * @magX: the magnification factor in the x direction for the specified region. 
     * @magY: the magnification factor in the x direction for the specified region. 
     **/
    void setMagFactor (in float magX, in float magY);

    /**
     * void getMagFactor: gets the current x and y magnification ratios.
     * (Convenience method for getting mag-factor-x and mag-factor-y properties).
     * @magX: the magnification factor in the x direction for the specified region. 
     * @magY: the magnification factor in the x direction for the specified region. 
     **/
    void getMagFactor (out float magX, out float magY);


    /**
     * PropertyBag getProperties: gets the current property settings for this ZoomRegion.
     * Properties managed by the ZoomRegion include "smoothing-type", "contrast",
     * "inverse-video", "border-size", "border-color", "x-alignment", "y-alignment", 
     * "is-managed", "viewport", "mag-factor-x", "mag-factor-y".
     * returns: a Bonobo::PropertyBag containing the ZoomRegion's properties.
     **/
    Bonobo::PropertyBag getProperties ();

    /**
     * oneway void setROI:
     * Sets the region of interest for the magnifier.
     * @bounds: the ROI bounding box
     **/
    oneway void setROI (in RectBounds bounds);

    /**
     * void markDirty:
     * Marks the zoom region or a sub-region 'dirty' and in need of updating.
     * @dirtyRegion: the bounding box of the dirty region.
     **/
    void markDirty (in RectBounds dirtyRegion);

    /**
     * RectBounds getROI:
     * Queries a specific zoom region for its ROI.
     * returns: the RectBounds bounding box of the zoom ROI.
     **/
    RectBounds getROI ();

    /**
     * void resize:
     * Resizes the specified zoom region on the target display.
     * (Convenience method for setting "viewport" property).
     * @bounds: the bounding box, in target display coordinates, of the ZoomRegion's
     *          display viewport.
     **/
    void resize (in RectBounds bounds);

    /** 
     * void dispose:
     * Remove the specified zoom region from the magnifier and destroy it.
     **/
    void dispose ();

  };

  interface Magnifier : Bonobo::Unknown {

    /**
     * #attribute SourceDisplay: a @string containing the X display name
     *                            containing the region to be magnified.
     **/
    attribute string SourceDisplay;

    /**
     * #attribute TargetDisplay: a @string containing the X display name
     *                           where the magnifier pixels are to be displayed.
     **/
    attribute string TargetDisplay;

    /**
     * PropertyBag getProperties: gets the current property settings for this Magnifier.
     * Properties managed by the magnifier include "cursor-set", "cursor-size", 
     * "cursor-mag-factor", "target-display-size", "source-display-size".
     * returns: a Bonobo::PropertyBag containing the Magnifier's properties.
     **/
    Bonobo::PropertyBag getProperties ();

    typedef sequence<ZoomRegion> ZoomRegionList;

    /**
     * ZoomRegionList getZoomRegions: 
     * returns a ZoomRegionList including all currently defined ZoomRegions 
     * for this Magnifier instance.
     **/
    ZoomRegionList getZoomRegions ();

    /**
     * boolean createZoomRegion:
     * Creates a new zoom region for the magnifier.
     * The new region is initially unmanaged'.
     * @zx: the scale factor in the x direction for the new zoom region
     * @zy: the scale factor in the y direction for the new zoom region
     * @ROI: the initial ROI of the zoom region.  RectBounds of negative width/height
     *          indicates that the zoom region has no initial ROI.
     * @viewport: the initial bounds of the ZoomRegion's viewport, in 
     *          the target display coordinate system.
     **/
    boolean createZoomRegion (in float zx, in float zy,
			      in RectBounds ROI,
			      in RectBounds viewport);

    /** 
     * void clearAllZoomRegions: 
     * Clears and destroys all currently defined zoom regions.
     **/
    void clearAllZoomRegions ();

    /** 
     * void dispose: 
     * Unmap the current magnifier from the display, destroy its resources, and exit.
     **/
    void dispose ();

  };

};

#endif