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

    enum ColorBlindFilter {
	    COLORBLIND_FILTER_T_NO_FILTER,
	    COLORBLIND_FILTER_T_SELECTIVE_SATURATE_RED,
	    COLORBLIND_FILTER_T_SELECTIVE_SATURATE_GREEN,
	    COLORBLIND_FILTER_T_SELECTIVE_SATURATE_BLUE,
	    COLORBLIND_FILTER_T_SELECTIVE_DESSATURATE_RED,
	    COLORBLIND_FILTER_T_SELECTIVE_DESSATURATE_GREEN,
	    COLORBLIND_FILTER_T_SELECTIVE_DESSATURATE_BLUE,
	    COLORBLIND_FILTER_T_HUE_SHIFT_POSITIVE,
	    COLORBLIND_FILTER_T_HUE_SHIFT_NEGATIVE,
	    COLORBLIND_FILTER_T_SELECTIVE_SATURATE,
	    COLORBLIND_FILTER_T_SELECTIVE_DESSATURATE,
	    COLORBLIND_FILTER_T_MONOCHRONE_OTHERS
    };

    /**
     * Set 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.
     * @param magX the magnification factor in the x direction for the specified region. 
     * @param 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);

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

    /**
     * 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 ();

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

    /**
     * Update the pointer image.
     * @note This was added due the need to the Magnifier object signalize all
     * ZoomRegion objects about a pointer image update.
     **/
    void updatePointer ();

    /**
     * Mark the zoom region or a sub-region 'dirty' and in need of updating.
     * @note This region will be clipped to the area currently visible in 
     * the target region.
     * @param dirtyRegion: the bounding box of the dirty region.
     **/
    void markDirty (in RectBounds dirtyRegion);

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

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

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

    /**
     * Set the position where the mouse pointer is to be drawn
     * in this zoom-region, in screen coordinates.
     * @param mouse_x: the x screen coordinate of the pointer hotspot
     * @param mouse_y: the y screen coordinate of the pointer hotspot
     **/
    oneway void setPointerPos (in long mouse_x, in long mouse_y);

    /**
     * Set the zoom region image contrast.
     * Set the contrast applied to each image component (red, green and blue).
     * The input for each component must be in the range -1 and 1, otherwise
     * they will be clamped to this interval. The value -1 means reduce 100%
     * the contrast, resulting in a gray image. The value 1 means increase 100%
     * the contrast, resulting in the R, G and B values being black or white.
     * The value 0 means no change in contrast.
     * @param R the amount of red in the contrasted image.
     * @param G the amount of green in the contrasted image.
     * @param B the amount of green in the contrasted image.
     **/
    void setContrast (in float R, in float G, in float B);

    /**
     * Get the zoom region image contrast.
     * Get the contrast applied to each image component (red, green and blue).
     * @param R the amount of red in the contrasted image.
     * @param G the amount of green in the contrasted image.
     * @param B the amount of green in the contrasted image.
     **/
    void getContrast (out float R, out float G, out float B);

     /**
     * Set the zoom region image brightness.
     * Set the brightness applied to each image component (reg, green and
     * blue). The input for each component must be in the range between -1 and
     * 1, if the are bigger or lower then this range, the value will be clamped
     * to the interval. The value -1 means reduce 100% the brightness,
     * resulting in a black image. The value 1 means increase 100% the
     * brightness, resulting in a white image.
     * @param R the brightness applied to the red component.
     * @param G the brightness applied to the green component.
     * @param B the brightness applied to the blue component.
     **/
    void setBrightness (in float R, in float G, in float B);

    /**
     * Get the zoom region image brightness.
     * Get the brightness applied to each image component (red, green and
     * blue).
     * @param R the brightness applied to the red component.
     * @param G the brightness applied to the green component.
     * @param B the brightness applied to the blue component.
     **/
    void getBrightness (out float R, out float G, out float B);

    };

    typedef sequence<ZoomRegion> ZoomRegionList;
  
    interface Magnifier : Bonobo::Unknown {

    /**
     * a \c string specifying the name of the display and screen
     * (on X Windows systems, as used by XOpenDisplay) on which the "source"
     * pixels (e.g. unmagnified image) are located.
     **/
    attribute string SourceDisplay;

    /**
     * a \c string specifying the name of the display and screen
     * onto which the magnified image is to be placed.
     **/
    attribute string TargetDisplay;

    /**
     * Get 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 ();

    /**
     * Consult if the Magnifier can magnify in full-screen mode.
     * @returns TRUE if it can or FALSE otherwise.
     **/
    boolean fullScreenCapable ();

    /**
     * Hide the original cursor.
     **/

    void hideCursor ();

    /**
     * Show the original cursor.
     **/

    void showCursor ();

    /**
     * Consult if the Magnifier can apply colorblind image filters.
     * @returns TRUE if it can or FALSE otherwise.
     **/
    boolean supportColorblindFilters ();

    /**
     * Create a new zoom region for the magnifier.
     * The new region is initially 'unmanaged'; that is, it is not associated with
     * a particular sub-region of the "source" display.
     * @param zx: the scale factor in the x direction for the new zoom region
     * @param zy: the scale factor in the y direction for the new zoom region
     * @param ROI: the initial ROI of the zoom region.  RectBounds of negative width/height
     *          indicates that the zoom region has no initial ROI.
     * @param viewport: the initial bounds of the ZoomRegion's viewport, in 
     *          the target display coordinate system.
     * @returns the newly created ZoomRegion.
     **/
    ZoomRegion createZoomRegion (in float zx, in float zy,
				 in RectBounds ROI,
				 in RectBounds viewport);

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

    /**
     * Add a new ZoomRegion to the list of currently defined ZoomRegions 
     * for this Magnifier instance.
     * @returns \c True if successful, \c False if the ZoomRegion cannot be added.
     **/
    boolean addZoomRegion (in ZoomRegion region);

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

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

    };
  };
};

#endif

