Module gtkimageview :: Class ImageView
[frames] | no frames]

Class ImageView

Known Subclasses:

ImageView is a full-featured general purpose image viewer widget for GTK. It provides a scrollable, zoomable pane in which a pixbuf can be displayed.

Keybindings

When focused, GtkImageView responds to the following keybindings:

Keys Corresponding function Description
GDK_KP_Add, GDK_equal, GDK_plus zoom_in() Causes the widget to zoom in one step
GDK_KP_Subtract, GDK_minus zoom_out() Causes the widget to zoom out one step
GDK_1 set_zoom() Sets zoom to 100%
GDK_2 set_zoom() Sets zoom to 200%
GDK_3 set_zoom() Sets zoom to 300%
GDK_x set_fitting() Sets fitting to True
GDK_Page_Up, GDK_Up + GDK_SHIFT_MASK n/a Scroll the view half a page upwards
GDK_Page_Down, GDK_Down + GDK_SHIFT_MASK n/a Scroll the view half a page downwards
GDK_Left + GDK_SHIFT_MASK n/a Scroll the view half a page leftwards
GDK_Right + GDK_SHIFT_MASK n/a Scroll the view half a page rightwards

Mouse actions

When focused, ImageView responds to the following mouse actions:

Mouse gesture Description
Mouse wheel scroll + GDK_CONTROL_MASK Increase or decrease the zoom of the view

Coordinate systems

Operations on ImageView are executed in three different 2d coordinate systems:

Settings

ImageView has a few settings that can be configured by users of the library. For example, when showing transparent images it may in certain cases be better to draw alpha transparent parts using the widgets background color instead of the default checkerboard:

view.set_transp(gtkimageview.TRANSP_BACKGROUND)

When the window that is showing the widget is fullscreened, other settings has to be tweaked to make the view look as good as possible:

view.set_show_cursor(False)
view.set_show_frame(False)
view.set_black_bg(True)

Naturally, you should reset these settings again when the view leaves fullscreen mode.

Updating the image data

ImageView aggresively caches the scaled image data. This behaviour is most often beneficial and makes the widget very fast. For a concrete example, try opening a very large image (4000x2000 pixels or so) in ImageView. The widget will spend some time bilinearly downsampling the image. Then try minimizing and unminimizing the window. The image will reappear immedately because the view has cached it.

However, this feature means that a client application must signal to the view when it changes the pixels on the pixbuf that the view shows. The right way to do that is to use ImageView.damage_pixels(). Code that merely tries to update the view by requesting that it should be redrawn will not work.

# Do some operation on the pixbuf data here..
view.queue_draw_area(10, 10, 50, 50)     # Incorrect!

Example

This is the minimal code needed for using ImageView:

import gtk
import gtk.gdk
import gtkimageview

win = gtk.Window()
view = gtkimageview.ImageView()
pixbuf = gtk.gdk.pixbuf_new_from_file("tests/gnome_logo.jpg")
view.set_pixbuf(pixbuf)
win.add(view)
win.show_all()
gtk.main()

Note that because the example doesn't use ImageScrollWin many nice features aren't available.

ImageView is a subclass of gtk.Widget.

Instance Methods
 
__init__(self)
Creates a new image view with default values.
    Signals
 
sig_pixbuf_changed(cls)
The pixbuf-changed signal is emitted when the pixbuf the image view shows or its image data is changed.
 
sig_zoom_changed(cls)
The zoom-changed signal is emitted when the zoom factor of the view changes.
    Read-only properties
 
get_viewport(self)
Returns a gtk.gdk.Rectangle with the current viewport.
 
get_draw_rect(self)
Returns the rectangle in the widget where the pixbuf is painted.
 
get_check_colors(self)
Returns a tuple with the two colors used to draw transparent parts of images with an alpha channel.
    Write-only properties
 
set_offset(self, x, y, invalidate=False)
Sets the offset of where in the image the image viewer should begin displaying image data.
 
set_transp(self, transp, transp_color=0)
Sets how the view should draw transparent parts of images with an alpha channel.
    Read-write properties
 
get_pixbuf(self)
Returns the pixbuf this view shows.
 
set_pixbuf(self, pixbuf, reset_fit=True)
Sets the pixbuf to display, or None to not display any pixbuf.
 
get_zoom(self)
Get the current zoom factor of the view.
 
set_zoom(self, zoom)
Sets the zoom of the view.
 
get_fitting(self)
Returns the fitting setting of the view.
 
set_fitting(self, fitting)
Sets whether to fit or not.
 
get_black_bg(self)
Returns whether the view renders the widget on a black background or not.
 
set_black_bg(self, black_bg)
If True, the view uses a black background.
 
get_tool(self)
Returns views tool which is an instance of a IImageTool.
 
set_tool(self, tool)
Set the image tool to use.
 
get_interpolation(self)
Returns the current interpolation mode of the view.
 
set_interpolation(self, interp)
Sets the interpolation mode of how the view.
 
get_show_cursor(self)
Returns whether to show the mouse cursor when the mouse is over the widget or not.
 
set_show_cursor(self, show_cursor)
Sets whether to show the mouse cursor when the mouse is over the widget or not.
 
get_show_frame(self)
Returns whether a one pixel frame is drawn around the pixbuf or not.
 
set_show_frame(self, show_frame)
Sets whether to draw a frame around the image or not.
    Actions
 
zoom_in(self)
Zoom in the view one step.
 
zoom_out(self)
Zoom in the view one step.
 
damage_pixels(self, rect)
Mark the pixels in the rectangle as damaged.
 
image_to_widget_rect(self, rect)
Converts a rectangle in image space coordinates to widget space coordinates.
Method Details

__init__(self)
(Constructor)

 

Creates a new image view with default values. The default values are:

  • black bg : False
  • fitting : True
  • image tool : an ImageToolDragger object
  • interpolation mode : gtk.gdk.INTERP_BILINEAR
  • offset : (0, 0)
  • pixbuf : None
  • show cursor : True
  • show frame : True
  • transp : TRANSP_GRID

sig_pixbuf_changed(cls)

 

The pixbuf-changed signal is emitted when the pixbuf the image view shows or its image data is changed. Listening to this signal is useful if you, for example, have a label that displays the width and height of the pixbuf in the view.

def pixbuf_cb(view, label):
    new_pb = view.get_pixbuf()
    if not new_pb:
        # Emtpy label if no pixbuf
        label.set_text('')
        return
    label.set_text('%d, %s' % (new_pb.get_width(), new_pb.get_height()))
...
label = gtk.Label('')
view.connect('pixbuf-changed', pixbuf_cb, label)

sig_zoom_changed(cls)

 

The zoom-changed signal is emitted when the zoom factor of the view changes. Listening to this signal is useful if, for example, you have a label that displays the zoom factor of the view. Use get_zoom() to retrieve the value. For example:

def zoom_cb(view, label):
    zoom = view.get_zoom()
    label.set_text("%d%%" % int(zoom * 100))
...
label = gtk.Label('100%')
view.connect('zoom-changed', zoom_cb, label)

zoom_in(self)

 
Zoom in the view one step. Calling this method causes the widget to immediately repaint itself.

zoom_out(self)

 
Zoom in the view one step. The widget is immediately repainted.

damage_pixels(self, rect)

 

Mark the pixels in the rectangle as damaged. That the pixels are damaged, means that they have been modified and that the view must redraw them to ensure that the visible part of the image corresponds to the pixels in that image.

Damaging first causes the IImageTool.pixbuf_changed() to be called which allows the tool to, for example, update its cache of the pixbuf if it has one.

The signal sig_pixbuf_changed is emitted which enables interested listeners to update their view of the pixbuf. And finally is the visible part of the damaged rectangle queued for redraw.

Parameters:
  • rect - the gtk.gdk.Rectangle in image space coordinates to mark as dirty.

image_to_widget_rect(self, rect)

 

Converts a rectangle in image space coordinates to widget space coordinates. If the view is not realized, or if it contains no pixbuf, then the conversion cannot be done and None is returned.

Note that this method may return a rectangle that is not visible on the widget.

The size of the returned rectangle is ceiled. That means that if the image space rectangle occupies less than one widget space pixel it is rounded up to one.

A use for this method would be if you for example is implementing an IImageTool and want to return a special gtk.gdk.Cursor if the pointer is over a hotspot in the image:

def cursor_at_point(self, x, y):
    wid_rect = self.view.image_to_widget_rect(self.hotspot)
    # Use the default cursor if the the view isn't realized
    # or if the pointer isn't over the hotspot.
    if not wid_rect:
        return None
    if not (x >= wid_rect.x and x < wid_rect.x + wid_rect.width and
            y >= wid_rect.y and y < wid_rect.y + wid_rect.height):
        return None
    # Use the hotspot cursor if the pointer is over the hotspot.
    return self.hotspot_cursor
Parameters:
  • rect - a gtk.gdk.Rectangle in image space coordinates.
Returns:
a gtk.gdk.Rectangle of the widget space coordinates or None

get_viewport(self)

 

Returns a gtk.gdk.Rectangle with the current viewport. If pixbuf is None, there is no viewport and None is returned.

The current viewport is defined as the rectangle, in zoomspace coordinates as the area of the loaded pixbuf the image viewer is currently showing.

Returns:
a gtk.gdk.Rectangle with the current viewport or None

get_draw_rect(self)

 

Returns the rectangle in the widget where the pixbuf is painted.

For example, if the widgets allocated size is 100, 100 and the pixbufs size is 50, 50 and the zoom factor is 1.0, then the pixbuf will be drawn centered on the widget. The rectangle is then (25,25)-[50,50]. If the widget is unallocated or the pixbuf is None then None is returned instead.

This method is useful when converting from widget to image or zoom space coordinates.

Returns:
the rectangle in the widget where the pixbuf is drawn or None.

get_check_colors(self)

 

Returns a tuple with the two colors used to draw transparent parts of images with an alpha channel. Note that if the transparency setting of the view is TRANSP_BACKGROUND or TRANSP_COLOR, then both colors will be equal.

>>> view.get_check_colors()
(6710886, 10066329)
Returns:
a tuple containing two color values used to draw transparent parts.

set_offset(self, x, y, invalidate=False)

 

Sets the offset of where in the image the image viewer should begin displaying image data.

The offset is clamped so that it will never cause the image viewer to display pixels outside the pixbuf. Setting this attribute causes the widget to repaint itself if it is realized.

If invalidate is True, the views entire area will be invalidated instead of instantly redrawn. The view is then queued for redraw, which means that additional operations can be performed on it before it is redrawn.

The difference can sometimes be important like when you are overlaying data and get flicker or artifacts when setting the offset. If that happens, setting invalidate to True could fix the problem. See the source code for GtkImageToolSelector for an example.

Normally, invalidate should always be False because it is much faster to repaint immedately than invalidating.

Parameters:
  • x - x-component of the offset in zoom space coordinates
  • y - y-component of the offset in zoom space coordinates
  • invalidate - whether to invalidate the view or redraw immediately

set_transp(self, transp, transp_color=0)

 

Sets how the view should draw transparent parts of images with an alpha channel. If transp is TRANSP_COLOR, the specified transp_color will be used. Otherwise the transp_color argument is ignored. If it is TRANSP_BACKGROUND, the background color of the widget will be used. If it is TRANSP_GRID, then a grid with light and dark gray boxes will be drawn on the transparent parts.

Calling this method causes the widget to immediately repaint. It also causes the sig_pixbuf_changed signal to be emitted. This is done so that other widgets (such as ImageNav) will have a chance to render a view of the pixbuf with the new transparency settings.

The default values are:

Parameters:
  • transp - transparency type to use when drawing transparent images
  • transp_color - color to use when drawing transparent images.

get_pixbuf(self)

 
Returns the pixbuf this view shows.
Returns:
the pixbuf this view shows

set_pixbuf(self, pixbuf, reset_fit=True)

 

Sets the pixbuf to display, or None to not display any pixbuf.

Normally, reset_fit should be True which enables fitting. Which means that, initially, the whole pixbuf will be shown.

Sometimes, fitting should not be reset. For example, if ImageView is showing an animation, it would be bad to reset fitting for each new frame. The parameter should then be False which leaves the fit mode of the view untouched.

This method must also be used to signal to the view that the contents of the pixbuf it display has been changed. This is the right way to force the redraw:

view.set_pixbuf(view.get_pixbuf(), False)

If reset_fit is True, the sig_zoom_changed signal is emitted, otherwise not. The sig_pixbuf_changed signal is also emitted.

The default pixbuf is None.

Parameters:
  • pixbuf - the pixbuf to display
  • reset_fit - whether to set fitting or not

get_zoom(self)

 
Get the current zoom factor of the view.
Returns:
the current zoom factor

set_zoom(self, zoom)

 

Sets the zoom of the view.

Fitting is always disabled after this method has run. The sig_zoom_changed signal is unconditionally emitted.

Parameters:
  • zoom - the new zoom factor

get_fitting(self)

 
Returns the fitting setting of the view.
Returns:
True if the view is fitting the image, False otherwise

set_fitting(self, fitting)

 

Sets whether to fit or not. If True, then the view will adapt the zoom so that the whole pixbuf is visible.

Setting the fitting causes the widget to immediately repaint itself.

Fitting is by default True.

Parameters:
  • fitting - whether to fit the image or not

get_black_bg(self)

 
Returns whether the view renders the widget on a black background or not.
Returns:
True if a black background is used, otherwise False.

set_black_bg(self, black_bg)

 

If True, the view uses a black background. If False, the view uses the default (normally gray) background.

The default value is False.

Parameters:
  • black_bg - whether to use a black background or not

get_tool(self)

 
Returns views tool which is an instance of a IImageTool.
Returns:
the currently bound tool

set_tool(self, tool)

 
Set the image tool to use. If the new tool is the same as the current tool, then nothing will be done. Otherwise IImageTool.pixbuf_changed() is called so that the tool has a chance to generate initial data for the pixbuf.
Parameters:
  • tool - the image tool to use (must not be None)

get_interpolation(self)

 
Returns the current interpolation mode of the view.
Returns:
the interpolation

set_interpolation(self, interp)

 

Sets the interpolation mode of how the view. gtk.gdk.INTERP_HYPER is the slowest, but produces the best results. gtk.gdk.INTERP_NEAREST is the fastest, but provides bad rendering quality. gtk.gdk.INTERP_BILINEAR is a good compromise.

Setting the interpolation mode causes the widget to immediately repaint itself.

The default interpolation mode is gtk.gdk.INTERP_BILINEAR.

Parameters:
  • interp - the interpolation to use. A gtk.gdk.InterpType object.

get_show_cursor(self)

 
Returns whether to show the mouse cursor when the mouse is over the widget or not.
Returns:
True if the cursor is shown, otherwise False.

set_show_cursor(self, show_cursor)

 

Sets whether to show the mouse cursor when the mouse is over the widget or not. Hiding the cursor is useful when the widget is fullscreened.

The default value is True.

Parameters:
  • show_cursor - whether to show the cursor or not

get_show_frame(self)

 
Returns whether a one pixel frame is drawn around the pixbuf or not.
Returns:
True if a frame is drawn around the pixbuf, otherwise False

set_show_frame(self, show_frame)

 

Sets whether to draw a frame around the image or not. When True, a one pixel wide frame is shown around the image. Setting this attribute causes the widget to immediately repaint itself.

The default value is True.

Parameters:
  • show_frame - whether to show a frame around the pixbuf or not