/* 
 * 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 {
  module Magnifier {

    struct Point {
	    long x, y;
    };

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

    interface ZoomRegion : Bonobo::Unknown {

    enum AlignPolicy {
	    ALIGN_CENTER,
	    ALIGN_MIN,
	    ALIGN_MAX
    };

    enum ScrollingPolicy {
	    SCROLL_FASTEST,
	    SCROLL_FAST,
	    SCROLL_NORMAL,
	    SCROLL_SMOOTH,
	    SCROLL_SMOOTHEST
    };

    /**
     * boolean setMagFactor: sets the current x and y magnification ratio.
     * (Convenience method for setting mag-factor-x and mag-factor-y properties).
     * Note that if the zoom region's target hasn't yet been realized or mapped to the 
     * display, we will not be able to detect failure, so a return of %TRUE must
     * be taken on advisement if the operation is performed on a newly-created
     * zoom region.
     * @magX: the magnification factor in the x direction for the specified region. 
     * @magY: the magnification factor in the x direction for the specified region. 
     * Returns: %TRUE if operation succeeded, %FALSE if the requested mag factor cannot be set.  
     **/
    boolean 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.
     * Note that this region will be clipped to the area currently visible in 
     * the target region.
     * @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 moveResize:
     * Moves and 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 moveResize (in RectBounds bounds);

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

    };

    typedef sequence<ZoomRegion> ZoomRegionList;
  
    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-bounds", "source-display-size".
     * returns: a Bonobo::PropertyBag containing the Magnifier's properties.
     **/
    Bonobo::PropertyBag getProperties ();

    /**
     * ZoomRegion 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.
     **/
    ZoomRegion createZoomRegion (in float zx, in float zy,
				 in RectBounds ROI,
				 in RectBounds viewport);

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

    /**
     * boolean addZoomRegion: 
     * add a new ZoomRegion to the list of currently defined ZoomRegions 
     * for this Magnifier instance.
     * returns: #true if successful, #false if the ZoomRegion cannot be added.
     **/
    boolean addZoomRegion (in ZoomRegion region);

    /** 
     * 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

