path: root/xml/spec.xml

<?xml version="1.0"?>
<tp:spec xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" xmlns:xi="http://www.w3.org/2001/XInclude">


<tp:version>0.01</tp:version>

<tp:docstring>
  Gnome Magnifier Interfaces and Subinterfaces
</tp:docstring>

<node name="/org/freedesktop/gnome/Magnifier">
  <interface name="org.freedesktop.gnome.Magnifier">
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>
        Properties and methods of Magnifier instance.
      </p>
    </tp:docstring>

    <!--    
    <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_dbus_magnifier"/>
    -->

    <!--
    <property name="SourceDisplay" type="s" access="readwrite">
      <tp:docstring>
        <p>
          a 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.
        </p>
      </tp:docstring>
    </property>

    <property name="TargetDisplay" type="s" access="readwrite">
       <tp:docstring>
        <p>
          a string specifying the name of the display and screen
          onto which the magnified image is to be placed.
        </p>
      </tp:docstring>
    </property>
    -->

    <!--
    <method name="getProperties">
      <tp:docstring>
        <p>
          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".
        </p>
      </tp:docstring>
      <arg type="a{ss}" name="propertyBag-ret" direction="out">
        <tp:docstring>
          a DBUS_TYPE_G_STRING_STRING_HASHTABLE containing the Magnifier's
          properties.
        </tp:docstring>
      </arg>
    </method>
    -->

    <method name="fullScreenCapable">
      <tp:docstring>
        <p>
          Consult if the Magnifier can magnify in full-screen mode.
        </p>
      </tp:docstring>
      <arg type="b" name="b-ret" direction="out">
      	<annotation name="org.freedesktop.DBus.GLib.ReturnVal" value=""/>
        <tp:docstring>TRUE if it can or FALSE otherwise.</tp:docstring>
      </arg>
    </method>

    <method name="hideCursor">
      <tp:docstring>
        <p>Hide the original cursor.</p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
    </method>

    <method name="showCursor">
      <tp:docstring>
        <p>Show the original cursor.</p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
    </method>

    <method name="supportColorblindFilters">
      <tp:docstring>
        <p>Consult if the Magnifier can apply colorblind image filters.</p>
      </tp:docstring>
      <arg type="b" name="b-ret" direction="out">
        <tp:docstring>TRUE if it can or FALSE otherwise.</tp:docstring>
      </arg>
    </method>

    <method name="createZoomRegion">
      <tp:docstring>
        <p>
          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.
        </p>
      </tp:docstring>
      <arg type="d" name="zx" direction="in">
        <tp:docstring>
          the scale factor in the x direction for the new zoom region
        </tp:docstring>
      </arg>
      <arg type="d" name="zy" direction="in">
        <tp:docstring>
          the scale factor in the y direction for the new zoom region
        </tp:docstring>
      </arg>
      <arg type="ai" name="ROI" tp:type="RectBounds" direction="in">
        <tp:docstring>
          the initial ROI (region of interest) of the zoom region.  RectBounds
          of negative  width/height indicates that the zoom region has no
          initial ROI.
        </tp:docstring>
      </arg>
    </method>

    <method name="getZoomRegions">
      <tp:docstring>
        <p>
          Return a list of ZoomRegion's for this Magnifier.
         </p>
      </tp:docstring>
      <arg type="ao" name="zoomRegionList-ret" direction="out">
        <tp:docstring>
          ZoomRegionList including all currently defined ZoomRegions for this
          Magnifier instance.
        </tp:docstring>
      </arg>
    </method>

    <method name="addZoomRegion">
      <tp:docstring>
        <p>
          Add a new ZoomRegion to the list of currently defined ZoomRegions 
          for this Magnifier instance.
        </p>
      </tp:docstring>
      <arg type="o" name="region" direction="in">
        <tp:docstring>ZoomRegion to add</tp:docstring>
      </arg>
      <arg type="b" name="b-ret" direction="out">
        <tp:docstring>
          returns True if successful, False if the ZoomRegion cannot be
          added.
        </tp:docstring>
      </arg>
   </method>
   
    <method name="clearAllZoomRegions">
      <tp:docstring>
        <p>
          Clears and destroys all currently defined zoom regions.
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
    </method>

    <method name="dispose">
      <tp:docstring>
        <p>
          Unmap the current magnifier from the display, destroy its resources,
          and exit.
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
    </method>
    
  </interface>  <!-- org.freedesktop.gnome.Magnifier -->
</node><!-- /org/freedesktop/gnome/Magnifier -->
<node name="/org/freedesktop/gnome/Magnifier/ZoomRegion">
  <!-- Structures and enums for the Magnifier's ZoomRegion object -->

  <!-- struct Point -->
  <tp:struct name="Point">
    <tp:member type="i" tp:name="x"/>
    <tp:member type="i" tp:name="y"/>
  </tp:struct>

  <!-- struct RectBounds -->
  <tp:struct name="RectBounds">
    <tp:member type="i" tp:name="x1"/>
    <tp:member type="i" tp:name="x2"/>
    <tp:member type="i" tp:name="y1"/>
    <tp:member type="i" tp:name="y2"/>
  </tp:struct>

  <!-- Align Policy constants -->
  <tp:enum name="AlignPolicy" type="u">
    <tp:enumvalue suffix="ALIGN_CENTER"/>
    <tp:enumvalue suffix="ALIGN_MIN" value="1"/>
    <tp:enumvalue suffix="ALIGN_MAX" value="2"/>
  </tp:enum>

  <!-- Scrolling Policy constants -->
  <tp:enum name="ScrollingPolicy" type="u">
    <tp:enumvalue suffix="SCROLL_FASTEST"/>
    <tp:enumvalue suffix="SCROLL_FAST" value="1"/>
    <tp:enumvalue suffix="SCROLL_NORMAL" value="2"/>
    <tp:enumvalue suffix="SCROLL_SMOOTH" value="3"/>
    <tp:enumvalue suffix="SCROLL_SMOOTHEST" value="4"/>
  </tp:enum>

  <!-- Colourblind Filter constants -->
  <tp:enum name="ColorBlindFilter" type="u">
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_NO_FILTER"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_SELECTIVE_SATURATE_RED" value="1"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_SELECTIVE_SATURATE_GREEN" value="2"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_SELECTIVE_SATURATE_BLUE" value="3"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_SELECTIVE_DESSATURATE_RED" value="4"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_SELECTIVE_DESSATURATE_GREEN" value="5"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_SELECTIVE_DESSATURATE_BLUE" value="6"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_HUE_SHIFT_POSITIVE" value="7"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_HUE_SHIFT_NEGATIVE" value="8"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_SELECTIVE_SATURATE" value="9"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_SELECTIVE_DESSATURATE" value="10"/>
    <tp:enumvalue suffix="COLORBLIND_FILTER_T_MONOCHRONE_OTHERS" value="11"/>
  </tp:enum>

  <!-- ZoomRegion object -->
  <interface name="org.freedesktop.gnome.Magnifier.ZoomRegion">
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>
        Properties and methods of the Magnifier's ZoomRegion object
      </p>
    </tp:docstring>
   
    <method name="setMagFactor">
      <tp:docstring>
        <p>
          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.
        </p>
      </tp:docstring>
      <arg type="d" name="magX" direction="in">
        <tp:docstring>
          the magnification factor in the x direction for the specified region.
        </tp:docstring>
      </arg>
      <arg type="d" name="magY" direction="in">
        <tp:docstring>
          the magnification factor in the x direction for the specified region. 
        </tp:docstring>
      </arg>
      <arg type="b" name="b_ret" direction="out">
        <tp:docstring>
          TRUE if operation succeeded, FALSE if the requested mag factor cannot
          be set. Returned in the 'b_ret' arg.
        </tp:docstring>
      </arg>
    </method>

    <method name="getMagFactor">
      <tp:docstring>
        <p>
          Get the current x and y magnification ratios. (Convenience method for
          getting mag-factor-x and mag-factor-y properties).
        </p>
       </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
      <arg type="d" name="magX" direction="out">
        <tp:docstring>
          the magnification factor in the x direction for the specified region.
        </tp:docstring>
      </arg>
      <arg type="d" name="magY" direction="out">
        <tp:docstring>
          the magnification factor in the x direction for the specified region.
        </tp:docstring>
      </arg>
    </method>

    <!--
    <method name="getProperties">
      <tp:docstring>
        <p>
          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".
        </p>
      </tp:docstring>
      <arg type="a{ss}" name="propertyBag-ret" direction="out">
        <tp:docstring>
          Returns a DBUS_TYPE_G_STRING_STRING_HASHTABLE containing the
          ZoomRegion's properties.
        </tp:docstring>
      </arg>
    </method>
    -->

    <method name="setRoi">
      <tp:docstring>
        <p>
          Set the region of interest for the magnifier.
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
      <arg type="(iiii)" name="Roi" tp:type="RectBounds" direction="in">
        <tp:docstring>
          the Roi (region of interest) bounding box
        </tp:docstring>
      </arg>
    </method>

    <method name="updatePointer">
      <tp:docstring>
        <p>
          Update the pointer image.  \note This was added due the need to the
          Magnifier object signalize all ZoomRegion objects about a pointer
          image update.
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
    </method>

    <method name="markDirty">
      <tp:docstring>
        <p>
          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.
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
      <!-- note that 'dirtyRegion' is a RectBounds -->
      <arg type="(iiii)" name="dirtyRegion" tp:type="RectBounds" direction="in">
        <tp:docstring>
          the bounding box of the dirty region.
        </tp:docstring>
      </arg>
    </method>

    <method name="getRoi">
      <tp:docstring>
        <p>
          Query a specific zoom region for its Roi.
        </p>
      </tp:docstring>
      <arg type="(iiii)" name="Roi-ret" tp:type="RectBounds" direction="out">
        <tp:docstring>
          Returns the RectBounds bounding box of the zoom Roi.
        </tp:docstring>
      </arg>
    </method>

    <method name="moveResize">
      <tp:docstring>
        <p>
          Move and resize the specified zoom region on the target display.
          (Convenience method for setting "viewport" property).
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
      <arg type="(iiii)" name="bounds" tp:type="RectBounds" direction="in">
        <tp:docstring>
          the bounding box, in target display coordinates, of the ZoomRegion's
          display viewport.
        </tp:docstring>
      </arg>
    </method>

    <method name="dispose">
      <tp:docstring>
        <p>
          Remove the specified zoom region from the magnifier and destroy it.
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
    </method>

    <method name="setPointerPos">
      <tp:docstring>
        <p>
          Set the position where the mouse pointer is to be drawn
          in this zoom-region, in screen coordinates.
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
      <arg type="i" name="mouse_x" direction="in">
        <tp:docstring>
          the x screen coordinate of the pointer hotspot
        </tp:docstring>
      </arg>
      <arg type="i" name="mouse_y" direction="in">
        <tp:docstring>
          the y screen coordinate of the pointer hotspot
        </tp:docstring>
      </arg>
    </method>

    <method name="setContrast">
      <tp:docstring>
        <p>
          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.
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
      <arg type="d" name="R" direction="in">
        <tp:docstring>
          the amount of red in the contrasted image
        </tp:docstring>
      </arg>
      <arg type="d" name="G" direction="in">
        <tp:docstring>
          the amount of green in the contrasted image
        </tp:docstring>
      </arg>
      <arg type="d" name="B" direction="in">
        <tp:docstring>
          the amount of blue in the contrasted image
        </tp:docstring>
      </arg>
    </method>

    <method name="getContrast">
      <tp:docstring>
        <p>
          Get the zoom region image contrast.
          Get the contrast applied to each image component (red, green and blue).
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
      <arg type="d" name="R" direction="out">
        <tp:docstring>
          the amount of red in the contrasted image
        </tp:docstring>
      </arg>
      <arg type="d" name="G" direction="out">
        <tp:docstring>
          the amount of green in the contrasted image
        </tp:docstring>
      </arg>
      <arg type="d" name="B" direction="out">
        <tp:docstring>
          the amount of blue in the contrasted image
        </tp:docstring>
      </arg>
    </method>

    <method name="setBrightness">
      <tp:docstring>
        <p>
          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.
        </p>
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>    
      <arg type="d" name="R" direction="in">
        <tp:docstring>
          the brightness applied to the red component.
        </tp:docstring>
      </arg>
      <arg type="d" name="G" direction="in">
        <tp:docstring>
          the brightness applied to the green component.
        </tp:docstring>
      </arg>
      <arg type="d" name="B" direction="in">
        <tp:docstring>
          the brightness applied to the blue component.
        </tp:docstring>
      </arg>
    </method>

    <!--
      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.
    -->
    <method name="getBrightness">
      <tp:docstring>
        <p>
          Get the zoom region image brightness.
          Get the brightness applied to each image component (red, green and
          blue).
        </p>        
      </tp:docstring>
      <annotation name="org.freedesktop.DBus.GLib.NoReply" value="true"/>
      <arg type="d" name="R" direction="out">
        <tp:docstring>
          the brightness applied to the red component.
        </tp:docstring>
      </arg>
      <arg type="d" name="G" direction="out">
        <tp:docstring>
          the brightness applied to the green component.
        </tp:docstring>
      </arg>
      <arg type="d" name="B" direction="out">
        <tp:docstring>
          the brightness applied to the blue component.
        </tp:docstring>
      </arg>
    </method>
    
  </interface>  <!-- org.freedesktop.gnome.Magnifier.ZoomRegion -->
</node><!-- /org/freedesktop/gnome/Magnifier/ZoomRegion -->

</tp:spec>