Class gtk-image

Package: gtk

Superclasses

gtk-misc, gtk-widget, gtk-buildable, g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

file

The file property of type :string (Read / Write)
The name of the file to load and display.
Default value: nil

gicon

The gicon property of type g-icon (Read / Write)
The icon displayed in the image. For themed icons, if the icon theme is changed, the image will be updated automatically.

icon-name

The icon-name property of type :string (Read / Write)
The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically.
Default value: nil

icon-set

The icon-set property of type gtk-icon-set (Read / Write)
The icon set to display.
Warning: The icon-set poperty has been deprecated since version 3.10 and should not be used in newly written code. Use the icon-name property instead.

icon-size

The icon-size property of type :int (Read / Write)
Symbolic size to use for a stock icon, icon set or named icon.
Allowed values: >= 0
Default value: 4

pixbuf

The pixbuf property of type gdk-pixbuf (Read / Write)
A pixbuf to display.

pixbuf-animation

The pixbuf-animation property of type gdk-pixbuf-animation (Read / Write)
The pixbuf animation to display.

pixel-size

The pixel-size property of type :int (Read / Write)
Can be used to specify a fixed size overriding the icon-size property for images of :icon-name type.
Allowed values: >= -1
Default value: -1

resource

The resource property of type :string (Read / Write)
A path to a resource file to display.
Default value: nil

stock

The stock property of type :string (Read / Write)
The stock ID for a stock image to display.
Warning: The stock property has been deprecated since version 3.10 and should not be used in newly written code. Use the icon-name property instead.
Default value: nil

storage-type

The storage-type property of type gtk-image-type (Read)
The representation being used for image data.
Default value: :empty

surface

The surface property of type cairo-surface (Read / Write)
A Cairo surface instance to display.

use-fallback

The use-fallback property of type :boolean (Read / Write)
Whether the icon displayed in the image will use standard icon names fallback. The value of this property is only relevant for images of :icon-name and :gicon type.
Default value: false

Details

The gtk-image widget displays an image. Various kinds of objects can be displayed as an image. Most typically, you would load a gdk-pixbuf object from a file, and then display that.

There is a convenience gtk-image-new-from-file function to do this, used as follows:

(let ((image (gtk-image-new-from-file "myfile.png")))
  ... )

If the file is not 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 the gdk-pixbuf-new-from-file function, then create the gtk-image widget with the gtk-image-new-from-pixbuf function.

The image file may contain an animation, if so the gtk-image widget will display a gdk-pixbuf-animation object instead of a static image.

The gtk-image class is a subclass of the gtk-misc class, which implies that you can align it (center, left, right) and add padding to it, using the gtk-misc methods.

The gtk-image widget is a "no window" widget (has no 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-event-box widget, then connect to the event signals on the event box.

Example

Handling button press events on a gtk-image widget.

(defun create-image ()
  (let ((image (gtk-image-new-from-file (rel-path "ducky.png")))
        (event-box (make-instance 'gtk-event-box)))
    ;; Set the event mask for the event box
    (setf (gtk-widget-events event-box) :button-press-mask)
    ;; Connect a signal to the event box
    (g-signal-connect event-box "button-press-event"
                      (lambda (box event)
                        (declare (ignore box))
                        (format t "Event box clicked at : ~6,2f, ~6,2f~%"
                                  (gdk-event-button-x event)
                                  (gdk-event-button-y event))
                        +gdk-event-stop+))
    ;; Add the image to the event box
    (gtk-container-add event-box image)
    ;; Return the event box with the image
    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 the gtk-misc class. 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.

CSS nodes

The gtk-image implementation has a single CSS node with the name image. The .icon-dropshadow and .lowres-icon style classes may appear on image CSS nodes.