gtk.Image — A widget displaying an image
class gtk.Image(gtk.Misc): |
Functionsdef gtk.image_new_from_stock(
stock_id
,size
)def gtk.image_new_from_icon_set(
icon_set
,size
)def gtk.image_new_from_animation(
animation
)def gtk.image_new_from_icon_name(
icon_name
,size
)def gtk.image_new_from_pixmap(
pixmap
,mask
)def gtk.image_new_from_image(
image
,mask
)def gtk.image_new_from_file(
filename
)def gtk.image_new_from_pixbuf(
pixbuf
)def gtk.image_new_from_gicon(
gicon
,size
)
|
The gtk.Image
widget
displays an image. Various kinds of objects can be displayed as an image;
usually, you would load a gtk.gdk.Pixbuf
("pixel buffer") from a file, and then display it. The convenience method
set_from_file
()
will read the file and automatically create a pixbuf that is added to the
gtk.Image
widget. If the file isn't loaded successfully, the image will contain a
"broken image" icon similar to that used in many web browsers. If you want
to handle errors in loading the file yourself, for example by displaying an
error message, then load the image with gtk.gdk.pixbuf_new_from_file
(),
then add it to the gtk.Image
with the
set_from_pixbuf
()
method. The image file may contain an animation; if so, the gtk.Image
will
display an animation (gtk.gdk.PixbufAnimation
)
instead of a static image.
gtk.Image
is a
subclass of gtk.Misc
, which
implies that you can align it (center, left, right) and add padding to it,
using the gtk.Misc
methods.
gtk.Image
is a
"no window" widget (has no gtk.gdk.Window
of
its own), so by default does not receive events. If you want to receive
events on the image, such as button clicks, place the image inside a gtk.EventBox
, then
connect to the event signals on the event box.
When handling events on the event box, keep in mind that
coordinates in the image may be different from event box coordinates due to
the alignment and padding settings on the image (see gtk.Misc
). The
simplest way to solve this is to set the alignment to 0.0 (left/top), and
set the padding to zero. Then the origin of the image will be the same as
the origin of the event box.
Sometimes an application will want to avoid depending on external
data files, such as image files. GTK+ comes with a program to avoid this,
called gdk-pixbuf-csource. This program allows you to
convert an image into a C variable declaration, which can then be loaded
into a gtk.gdk.Pixbuf
using
the gtk.gdk.pixbuf_new_from_inline
()
function. This can also be used in PyGTK
by modifying the
output using an editor or the sed command as
follows:
gdk-pixbuf-csource imagefile | \ sed -n -e 's/{/[/' -e 's/};/]/' -e '/".*"/p' >outfile
You can edit outfile
into a Python file where
it will be evaluated to a list containing a string. The string can be used
directly with the gtk.gdk.pixbuf_new_from_inline
()
function to create a pixbuf that can be used in a gtk.Image
.
gtk.Image()
Returns : | a newly created gtk.Image
widget. |
Creates a new empty gtk.Image
widget.
def set_from_pixmap(pixmap
, mask
)
| a gtk.gdk.Pixmap |
| a bitmap gtk.gdk.Pixmap or
None |
The set_from_pixmap
() method sets the
image data from pixmap
using
mask
.
def set_from_image(gdk_image
, mask
)
| a gtk.gdk.Image or
None |
| a bitmap gtk.gdk.Pixmap or
None |
The set_from_image
() method sets the
image data from image
using
mask
. A gtk.gdk.Image
is a
client-side image buffer in the pixel format of the current display. If
image
is None
the current image
data will be removed.
def set_from_file(filename
)
| a filename or
None |
The set_from_file
() method sets the
image data from the contents of the file named
filename
. If the file isn't found or can't be loaded,
the resulting gtk.Image
will
display a "broken image" icon. This function never returns None, it always
returns a valid gtk.Image
widget. If
the file contains an animation, the image will contain an animation. If
filename
is None
the current image
data will be removed.
If you need to detect failures to load the file, use gtk.gdk.pixbuf_new_from_file
()
to load the file yourself, then create the gtk.Image
from the
pixbuf. (Or for animations, use the gtk.gdk.PixbufAnimation()
constructor.
def set_from_pixbuf(pixbuf
)
| a gtk.gdk.Pixbuf or
None |
The set_from_pixbuf
() method sets the
image data using pixbuf
. Note that this function just
creates an gtk.Image
from
pixbuf
. The gtk.Image
created
will not react to state changes. Should you want that, you should use the
set_from_icon_set
()
method If pixbuf
is None
the
current image data will be removed.
def set_from_stock(stock_id
, size
)
| a stock icon name |
| a stock icon size |
The set_from_stock
() method sets the
image data from the stock item identified by
stock_id
. Sample stock icon names are
gtk.STOCK_OPEN
and gtk.STOCK_OK
.
Stock icon sizes are gtk.ICON_SIZE_MENU
,
gtk.ICON_SIZE_SMALL_TOOLBAR
,
gtk.ICON_SIZE_LARGE_TOOLBAR
,
gtk.ICON_SIZE_BUTTON
,
gtk.ICON_SIZE_DND
and
gtk.ICON_SIZE_DIALOG
. If the stock icon name isn't known,
a "broken image" icon will be displayed instead. You can register your own
stock icon names, see the gtk.IconFactory.add_default
()
and gtk.IconFactory.add
()
methods.
The stock icons are described in the Stock Items reference.
def set_from_icon_set(icon_set
, size
)
| a gtk.IconSet |
| a stock icon size |
The set_from_icon_set
() method sets the
image data from icon_set with the size specified by
size
. Stock icon sizes are
gtk.ICON_SIZE_MENU
,
gtk.ICON_SIZE_SMALL_TOOLBAR
,
gtk.ICON_SIZE_LARGE_TOOLBAR
,
gtk.ICON_SIZE_BUTTON
,
gtk.ICON_SIZE_DND
and
gtk.ICON_SIZE_DIALOG
.
def set_from_animation(animation
)
| the gtk.gdk.PixbufAnimation |
The set_from_animation
() method sets
the image data from animation
.
def get_storage_type()
Returns : | the type of the image representation being used |
The get_storage_type
() method gets the
type of representation being used by the gtk.Image
to store
image data. If the gtk.Image
has no
image data, the return value will be gtk.IMAGE_EMPTY
. The
image type is one of: gtk.IMAGE_EMPTY
,
gtk.IMAGE_PIXMAP
, gtk.IMAGE_IMAGE
,
gtk.IMAGE_PIXBUF
, gtk.IMAGE_STOCK
,
gtk.IMAGE_ICON_SET
or
gtk.IMAGE_ANIMATION
.
def get_pixmap()
Returns : | a tuple containing the pixmap (or
None ) and the mask (or
None ) |
The get_pixmap
() method returns a tuple
containing the pixmap and mask being displayed by the gtk.Image
. Either or
both the pixmap and mask may be None
. If the storage type
of the image is not either gtk.IMAGE_EMPTY
or
gtk.IMAGE_PIXMAP
the ValueError exception will be
raised.
def get_image()
Returns : | a tuple containing a gtk.gdk.Image and a
mask bitmap |
The get_image
() method returns a tuple
containing the gtk.gdk.Image
and
mask being displayed by the gtk.Image
. One or
both of the gtk.gdk.Image
and
mask may be None
. If the storage type of the image is not
either of gtk.IMAGE_EMPTY
or
gtk.IMAGE_IMAGE
the ValueError exception will be
raised.
def get_pixbuf()
Returns : | the displayed pixbuf, or
None if the image is empty |
The get_pixbuf
() method gets the gtk.gdk.Pixbuf
being
displayed by the gtk.Image
. The return
value may be None if no image data is set. If the storage type of the image
is not either gtk.IMAGE_EMPTY
or
gtk.IMAGE_PIXBUF
the ValueError exception will be
raised.
def get_stock()
Returns : | a tuple containing the stock icon name and the stock icon size of the image data |
The get_stock
() method returns a tuple
containing the stock icon identifier (may be None
) and
size being displayed by the gtk.Image
. The size
will be one of: gtk.ICON_SIZE_MENU
,
gtk.ICON_SIZE_SMALL_TOOLBAR
,
gtk.ICON_SIZE_LARGE_TOOLBAR
,
gtk.ICON_SIZE_BUTTON
,
gtk.ICON_SIZE_DND
or
gtk.ICON_SIZE_DIALOG
. If the storage type of the image is
not either gtk.IMAGE_EMPTY
or
gtk.IMAGE_STOCK
the ValueError exception will be
raised.
def get_icon_set()
Returns : | a tuple containing a gtk.IconSet and a
stock icon size |
The get_icon_set
() method returns a
tuple containing the icon set (may be None
) and size
being displayed by the gtk.Image
. The size
will be one of: gtk.ICON_SIZE_MENU
,
gtk.ICON_SIZE_SMALL_TOOLBAR
,
gtk.ICON_SIZE_LARGE_TOOLBAR
,
gtk.ICON_SIZE_BUTTON
,
gtk.ICON_SIZE_DND
or
gtk.ICON_SIZE_DIALOG
. If the storage type of the image is
not either gtk.IMAGE_EMPTY
or
gtk.IMAGE_ICON_SET
the ValueError exception will be
raised.
def get_animation()
Returns : | the displayed animation, or
None if the image is empty |
The get_animation
() method gets the
gtk.gdk.PixbufAnimation
(may be None if there is no image data) being displayed by the gtk.Image
. If the
storage type of the image is not either gtk.IMAGE_EMPTY
or gtk.IMAGE_ANIMATION
the ValueError exception will be
raised.
def get_icon_name()
Returns : | a 2-tuple containing the name and size of the displayed icon. |
This method is available in PyGTK 2.6 and above.
The get_icon_name
() method returns a
2-tuple containing the values of the "icon-name" and "icon-size" properties
respectively if the "icon-name" property is not None
. If
the "icon-name" property is None
the 2-tuple returned
will be:
(None, <enum GTK_ICON_SIZE_INVALID of type GtkIconSize>)
def set_from_icon_name(icon_name
, size
)
| an icon name |
| a stock icon size |
This method is available in PyGTK 2.6 and above.
The set_from_icon_name
() method sets
the "icon-name" and "icon-size" properties to the values of
icon_name
and size
respectively. icon_name
should be the name of an icon
in the current icon theme. If icon_name
isn't known,
a "broken image" icon will be displayed instead. If the current icon theme
is changed, the icon will be updated appropriately.
def set_pixel_size(pixel_size
)
| the new pixel size to be used for named icons |
This method is available in PyGTK 2.6 and above.
The set_pixel_size
() method sets the
"pixel-size" property to the value specified by
pixel_size
. If the pixel size is set to a value != -1
the "pixel-size" property is used instead of the icon size set by the set_from_icon_name
()
method.
def get_pixel_size()
Returns : | the pixel size used for named icons. |
This method is available in PyGTK 2.6 and above.
The get_pixel_size
() method returns the
value of the "pixel-size" property which specifies the pixel size to be used
for named icons.
def clear()
This method is available in PyGTK 2.8 and above.
The clear
() method removes the current
image, if any, and resets the "storage-type", "mask" and "icon-size"
properties. One of the "file", "icon-name", "icon-set", "image", "pixbuf",
"pixbuf-animation", "pixmap" or "stock" will be reset if there was an
existing image.
def set_from_gicon(icon
, size
)
| an icon |
| an icon size |
This method is available in PyGTK 2.14 and above.
For the set_from_gicon
() method see
gtk.image_new_from_gicon
()
for details.
def gtk.image_new_from_stock(stock_id
, size
)
| a stock icon name |
| an integer representing an icon size |
Returns : | a new gtk.Image
displaying the stock icon |
The gtk.image_new_from_stock
() function
returns a new gtk.Image
displaying
the stock icon specified by stock_id
with the
specified size
. Sample stock icon names are
gtk.STOCK_OPEN
, gtk.STOCK_OK
- see the
set_from_stock
()
method for detailed information on the PyGTK
stock icons.
. Sample stock sizes are gtk.ICON_SIZE_MENU
,
gtk.ICON_SIZE_SMALL_TOOLBAR
- see the gtk.icon_size_lookup
() function for more detail. If the stock icon name isn't
known, a "broken image" icon will be displayed instead. You can register
your own stock icon names, see the gtk.IconFactory.add_default
()
and gtk.IconFactory.add
()
methods.
def gtk.image_new_from_icon_set(icon_set
, size
)
| a gtk.IconSet
object |
| an integer representing an icon size |
Returns : | a new gtk.Image
object |
The gtk.image_new_from_icon_set
() function
returns a new gtk.Image
created
from the gtk.IconSet
specified by icon_set
with the specified
size
. Sample stock sizes are
gtk.ICON_SIZE_MENU
,
gtk.ICON_SIZE_SMALL_TOOLBAR
- see the gtk.icon_size_lookup
()
function for more detail. Instead of using this function, usually it's
better to create a gtk.IconFactory
,
put your icon sets in the icon factory, add the icon factory to the list of
default factories with the add_default
()
method, and then use the gtk.image_new_from_stock
()
function. This will allow themes to override the icon you ship with your
application.
def gtk.image_new_from_animation(animation
)
| a gtk.gdk.PixbufAnimation
object |
Returns : | a new gtk.Image
object |
The gtk.image_new_from_animation
() function
returns a new gtk.Image
object
containing the gtk.gdk.PixbufAnimation
specified by animation
.
def gtk.image_new_from_icon_name(icon_name
, size
)
| an icon name |
| a stock icon size |
Returns : | a new gtk.Image
widget. |
This function is available in PyGTK 2.6 and above.
The gtk.image_new_from_icon_name
() function
returns a new gtk.Image
object
displaying the named theme icon specified by
icon_name
with the icon size specified by
size
. If the icon name isn't known, a "broken image"
icon will be displayed instead. If the current icon theme is changed, the
icon will be updated appropriately. The "icon-name" and "icon-size"
properties are also set by this function.
def gtk.image_new_from_pixmap(pixmap
, mask
)
| a gtk.gdk.Pixmap |
| the bitmap that is the transparency mask. |
Returns : | a new gtk.Image
widget. |
This function is available in PyGTK 2.12 and above.
The gtk.image_new_from_pixmap
() function
returns a new gtk.Image
object
displaying pixmap with a mask. A gtk.gdk.Pixmap
is a server-side image buffer in the pixel format of the current display.
def gtk.image_new_from_image(image
, mask
)
| a gtk.gdk.Image |
| the bitmap that is the transparency mask. |
Returns : | a new gtk.Image
widget. |
This function is available in PyGTK 2.12 and above.
The gtk.image_new_from_image
() function
returns a new gtk.Image
object
displaying an image with a mask. A gtk.gdk.Image
is a client-side image buffer in the pixel format of the current display.
def gtk.image_new_from_file(filename
)
| a filename |
Returns : | a new gtk.Image
widget. |
This function is available in PyGTK 2.12 and above.
The gtk.image_new_from_file
() function
returns a new gtk.Image
object
displaying the file filename. If the file isn't found or can't be loaded,
the resulting gtk.Image
will display a "broken image" icon. This function never returns None,
it always returns a valid gtk.Image
widget.
If the file contains an animation, the image will contain an animation.
If you need to detect failures to load the file, use gtk.gdk.pixbuf_new_from_file
to load the file yourself, then create the gtk.Image
from the pixbuf. (Or for animations, use gtk.gdk.PixbufAnimation.
The storage type (get_storage_type)
of the returned image is not defined, it will be whatever is appropriate
for displaying the file.
def gtk.image_new_from_pixbuf(pixbuf
)
| a gtk.gdk.Pixbuf
|
Returns : | a new gtk.Image
widget. |
This function is available in PyGTK 2.12 and above.
The gtk.image_new_from_pixbuf
() function
returns a new gtk.Image
object
displaying pixbuf
Note that this function just creates a gtk.Image
from the pixbuf. The
gtk.Image
created will not react to state changes. Should you want that, you should use
gtk.image_new_from_icon_set
def gtk.image_new_from_gicon(gicon
, size
)
| a gio.Icon |
| a stock icon size. |
Returns : | a new gtk.Image
displaying the themed icon. |
This function is available in PyGTK 2.14 and above.
The gtk.image_new_from_pixbuf
() function returns
a new gtk.Image
displaying an icon from the current icon theme. If the icon name isn't known,
a "broken image" icon will be displayed instead. If the current icon theme is
changed, the icon will be updated appropriately.