gobject:object, common-lisp:standard-object, common-lisp:t

gdk:dmabuf-texture, gdk:gl-texture, gdk:memory-texture, gdk:texture, gtk:icon-paintable, gtk:media-file, gtk:media-stream, gtk:widget-paintable

The gdk:paintable interface is a simple interface used by GDK and GTK to represent objects that can be painted anywhere at any size without requiring any sort of layout. The interface is inspired by similar concepts elsewhere, such as ClutterContent, HTML/CSS Paint Sources, or SVG Paint Servers.

A gdk:paintable object can be snapshot at any time and size using the gdk:paintable-snapshot function. How the paintable interprets that size and if it scales or centers itself into the given rectangle is implementation defined, though if you are implementing a gdk:paintable object and do not know what to do, it is suggested that you scale your paintable ignoring any potential aspect ratio.

The contents that a gdk:paintable object produces may depend on the gdk:snapshot object passed to it. For example, paintables may decide to use more detailed images on higher resolution screens or when OpenGL is available. A gdk:paintable object will however always produce the same output for the same snapshot.

A gdk:paintable object may change its contents, meaning that it will now produce a different output with the same snapshot. Once that happens, it will call the gdk:paintable-invalidate-contents function which will emit the "invalidate-contents" signal. If a paintable is known to never change its contents, it will set the :static-contents flag. If a consumer cannot deal with changing contents, it may call the gdk:paintable-current-image function which will return a static paintable and use that.

A paintable can report an intrinsic (or preferred) size or aspect ratio it wishes to be rendered at, though it does not have to. Consumers of the interface can use this information to layout thepaintable appropriately. Just like the contents, the size of a paintable can change. A paintable will indicate this by calling the gdk:paintable-invalidate-size function which will emit the "invalidate-size" signal. And just like for contents, if a paintable is known to never change its size, it will set the :static-size flag.

Besides API for applications, there are some functions that are only useful for implementing subclasses and should not be used by applications: gdk:paintable-invalidate-contents, gdk:paintable-invalidate-size, gdk:paintable-new-empty.

(gobject:define-vtable ("GdkPaintable" paintable)
  (:skip parent-instance (:struct g:type-interface))
  ;; Methods of the GdkPaintable interface
  (snapshot (:void (paintable (g:object paintable))
                   (snapshot (g:object snapshot))
                   (width :double)
                   (height :double)))
  (get-current-image ((g:object paintable) (paintable (g:object paintable))))
  (get-flags (paintable-flags (paintable (g:object paintable))))
  (get-intrinsic-width (:int (paintable (g:object paintable))))
  (get-intrinsic-height (:int (paintable (g:object paintable))))
  (get-intrinsic-aspect-ratio (:double (paintable (g:object paintable)))))    

The list of functions that can be implemented for the gdk:paintable interface. The following methods are provided and can be specialized for a subclass which derives from the gdk:paintable interface:

gdk:paintable-snapshot-impl

Method called from the gdk:paintable-snapshot function.

gdk:paintable-get-current-image-impl

Method called from the gdk:paintable-current-image function.

gdk:paintable-get-flags-impl

Method called from the gdk:paintable-flags function.

gdk:paintable-get-intrinsic-width-impl

Method called from the gdk:paintable-intrinsic-with function.

gdk:paintable-get-intrinsic-height-impl

Method called from the gdk:paintable-intrinsic-height function.

gdk:paintable-get-intrinsic-aspect-ratio-impl

Method called from the gdk:paintable-intrinsic-aspect-ratio function.

Note that apart from the gdk:paintable-snapshot-impl method, no method of this interface is mandatory to implement, though it is a good idea to implement the gdk:paintable-get-current-image-impl method for non-static paintables and the gdk:paintable-get-flags-impl method if the paintable is not dynamic as the default implementation returns no flags and that will make the implementation likely quite slow. This is a complete example for the implementation of a subclass which implements the gdk:paintable interface.

;; Implementation of a NUCLEAR-ICON subclass
(gobject:define-gobject-subclass "GdkNuclearIcon" nuclear-icon
  (:superclass g:object
   :export t
   :interfaces ("GdkPaintable"))
  ((rotation
    nuclear-icon-rotation
    "rotation" "gdouble" t t)))


;; This is the function that draws the actual icon
(defun nuclear-snapshot (snapshot foreground background width height rotation)
  (let ((size (min width height))
        (radius 0.3)
        (cr nil))
    (graphene:with-rects ((rect1 0 0 width height)
                          (rect2 (/ (- width size) 2.0)
                                 (/ (- height size) 2.0)
                                 size size))
      (gtk:snapshot-append-color snapshot background rect1)
      (setf cr (gtk:snapshot-append-cairo snapshot rect2))
      (cairo-set-source-rgba cr foreground)
      (cairo:translate cr (/ width 2.0) (/ height 2.0))
      (cairo:scale cr size size)
      (cairo:rotate cr rotation)
      (cairo:arc cr 0 0 0.1 (- pi) pi)
      (cairo:fill cr)
      (setf (cairo:line-width cr) radius)
      (setf (cairo:dash cr 0.0) (list (/ (* radius pi) 3)))
      (cairo:arc cr 0 0 radius (- pi) pi)
      (cairo:stroke cr)
      (cairo:destroy cr))))


;; Here, we implement the methods required by the GdkPaintable interface
(defmethod paintable-snapshot-impl ((paintable nuclear-icon)
                                    snapshot width height)
  (nuclear-snapshot snapshot
                    (rgba-new :red 0 :green 0 :blue 0 :alpha 1)
                    (rgba-new :red 0.9 :green 0.75 :blue 0.15 :alpha 1)
                    width
                    height
                    (nuclear-icon-rotation paintable)))


(defmethod paintable-get-flags-impl ((paintable nuclear-icon))
  (list :static-contents :static-size))    

The "invalidate-contents" signal

lambda (paintable)    :run-last      

paintable

The gdk:paintable object.

Emitted when the contents of the paintable change. Examples for such an event would be videos changing to the next frame or the icon theme for an icon changing.

The "invalidate-size" signal

lambda (paintable)    :run-last      

paintable

The gdk:paintable object.

Emitted when the intrinsic size of the paintable changes. This means the values reported by at least one of the gdk:paintable-intrinsic-width, gdk:paintable-intrinsic-height or gdk:paintable-intrinsic-aspect-ratio function has changed. Examples for such an event would be a paintable displaying the contents of a toplevel surface being resized.