xmlns:its="http://www.w3.org/2005/11/its"

      xmlns:xi="http://www.w3.org/2001/XInclude"

      type="guide" style="task"

      id="image.py">

  <info>

    <title type="text">Image (Python)</title>

    <link type="guide" xref="beginner.py#display-widgets"/>

    <link type="seealso" xref="properties.py" />

    <link type="next" xref="strings.py"/>

    <revision version="0.2" date="2012-06-14" status="draft"/>

    <credit type="author copyright">

      <name>Marta Maria Casetti</name>

      <email its:translate="no">mmcasetti@gmail.com</email>

      <years>2012</years>

    </credit>

    <credit type="editor">

      <name>Sindhu S</name>

      <email its:translate="no">sindhus@live.in</email>

      <years>2014</years>

    </credit>

    <desc>A widget displaying an image</desc>

  </info>

  <title>Image</title>

  <media type="image" mime="image/png" src="media/image.png"/>

  
This GtkApplication displays an image file from the current directory.

  <note>

    If the image file is not loaded successfully, the image will contain a

    "broken image" icon. <file>filename.png</file> needs to be in the

    current directory for this code to work.

  
</note>

  <links type="section"/>

  <section id="code">

  <title>Code used to generate this example</title>

  <xi:include href="samples/image.py" parse="text"><xi:fallback/></xi:include>

  
Another way to obtain what we have in the example is to create the image as

  an instance of another class and add it to the instance of

  MyWindow in the do_activate(self) method:

    # a class to create a window

    class MyWindow(Gtk.ApplicationWindow):

    def __init__(self, app):

        Gtk.Window.__init__(self, title="Welcome to GNOME", application=app)

        self.set_default_size(300, 300)

    # a class to create an image

    class MyImage(Gtk.Image):

    def __init__(self):

        Gtk.Image.__init__(self)

        self.set_from_file("gnome-image.png")

    class MyApplication(Gtk.Application):

    def __init__(self):

        Gtk.Application.__init__(self)

    def do_activate(self):

        # create an instance of MyWindow

        win = MyWindow(self)

        # create an instance of MyImage and add it to the window

        win.add(MyImage())

        # show the window and everything on it

        win.show_all()

  <note>

    
To use this code snippet, you will need to add the code that imports

    Gtk and GdkPixbuf from gi.repository

    and lines that instantiate the MyApplication window.

  </note>

  </section>

  <section id="methods">

  <title>Useful methods for an Image widget</title>

  <list>

    <item>

      
To load an image over a network use

      set_from_pixbuf(pixbuf), where pixbuf is a

      <link href="https://developer.gnome.org/gdk-pixbuf/unstable/index.html">

      GdkPixbuf</link>.

        from gi.repository import Gtk

        from gi.repository import GdkPixbuf

        import sys

        class MyWindow(Gtk.ApplicationWindow):

            # create a window

            def __init__(self, app):

                Gtk.Window.__init__(self, title="Welcome to GNOME", application=app)

                self.set_default_size(300, 300)

                # create a pixbuf from file filename="gnome-image.png", with width=32

                # and height=64 amd boolean preserve_aspect_ratio=False.

                pixbuf = GdkPixbuf.Pixbuf.new_from_file_at_scale("gnome-image.png", 64, 128, False)

                # create an image

                image = Gtk.Image()

                # set the content of the image as the pixbuf

                image.set_from_pixbuf(pixbuf)

                # add the image to the window

                self.add(image)

        
If preserve_aspect_ratio=True we can use

        new_from_file_at_size(filename, width, height). If

        width or height is -1, it is

        not constrained.

        
For loading from an input stream, see new_from_stream()

        and new_from_stream_at_scale() in the documentation.

    </item>

  </list>

  </section>

  <section id="references">

    <title>API References</title>

    
In this sample we used the following:

    <list>

      <item>

        
<link href="https://developer.gnome.org/gtk3/unstable/GtkImage.html">

        GtkImage</link>

      </item>

      <item>

        
<link href="https://developer.gnome.org/gtk3/unstable/GtkWindow.html">

        GtkWindow</link>

      </item>

    </list>

  </section>

</page>