<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-atkimage">

  <refnamediv>
    <refname>atk.Image</refname>
      <refpurpose>the ATK Interface implemented by components that expose
      image or pixmap content on-screen.  </refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>atk.Image</classname></ooclass>
      <ooclass><classname>gobject.GInterface</classname></ooclass>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkimage--get-image-description">get_image_description</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkimage--get-image-size">get_image_size</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkimage--set-image-description">set_image_description</link></methodname>
        <methodparam><parameter role="keyword">description</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkimage--get-image-position">get_image_position</link></methodname>
        <methodparam><parameter role="keyword">coord_type</parameter></methodparam>
      </methodsynopsis>
</classsynopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para><link
    linkend="class-atkimage"><classname>atk.Image</classname></link> should
    be implemented by <link
    linkend="class-atkobject"><classname>atk.Object</classname></link>
    subtypes on behalf of components which display image/pixmap information
    onscreen, and which provide information (other than just widget borders,
    etc.) via that image content.  For instance, icons, buttons with icons,
    toolbar elements, and image viewing panes typically should implement
    <link
    linkend="class-atkimage"><classname>atk.Image</classname></link>.</para>

    <para><link
    linkend="class-atkimage"><classname>atk.Image</classname></link>
    primarily provides two types of information: coordinate information
    (useful for screen review mode of screenreaders, and for use by onscreen
    magnifiers), and descriptive information.  The descriptive information
    is provided for alternative, text-only presentation of the most
    significant information present in the image.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-atkimage--get-image-description">
      <title>atk.Image.get_image_description</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_image_description</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a string representing the image
          description</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Get a textual description of this image.</para>

    </refsect2>

    <refsect2 id="method-atkimage--get-image-size">
      <title>atk.Image.get_image_size</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_image_size</methodname>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a 2-tuple containing the width and height of
          the image</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Get the width and height in pixels for the specified image. The
      width and height are returned as -1 if the values cannot be
      obtained.</para>

    </refsect2>

    <refsect2 id="method-atkimage--set-image-description">
      <title>atk.Image.set_image_description</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_image_description</methodname>
        <methodparam><parameter role="keyword">description</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">description</parameter>&nbsp;:</term>
          <listitem><simpara>a string description to set for
          <parameter>image</parameter></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>True if operation could be
          completed.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Sets the textual description for this image.</para>

    </refsect2>

    <refsect2 id="method-atkimage--get-image-position">
      <title>atk.Image.get_image_position</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_image_position</methodname>
        <methodparam><parameter role="keyword">coord_type</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">coord_type</parameter>&nbsp;:</term>
          <listitem><simpara>specifies whether the coordinates are relative
          to the screen or to the components top level window - one of the
          <xref linkend="atk-coord-type-constants"
          endterm="atk-coord-type-constants-title"></xref></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a 2-tuple containing the x and y coordinates of
          the image</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Gets the position of the image in the form of a point specifying
      the images top-left corner.  The values of x and y are returned as -1
      if the values cannot be obtained.</para>

    </refsect2>

  </refsect1>

</refentry>
