Package ch.bailu.gtk.gdk

Class Paintable

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.gobject.Object
ch.bailu.gtk.type.Interface
ch.bailu.gtk.gdk.Paintable
All Implemented Interfaces:
PointerInterface
public class Paintable extends Interface
`GdkPaintable` is a simple interface used by GTK to represent content that
can be painted.

The content of a `GdkPaintable` can be painted anywhere at any size
without requiring any sort of layout. The interface is inspired by
similar concepts elsewhere, such as
[ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html),
[HTML/CSS Paint Sources](https://www.w3.org/TR/css-images-4/#paint-source),
or [SVG Paint Servers](https://www.w3.org/TR/SVG2/pservers.html).

A `GdkPaintable` can be snapshot at any time and size using
[method@Gdk.Paintable.snapshot]. 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 `GdkPaintable` and don't know what
to do, it is suggested that you scale your paintable ignoring any potential
aspect ratio.

The contents that a `GdkPaintable` produces may depend on the [class@GdkSnapshot]
passed to it. For example, paintables may decide to use more detailed images
on higher resolution screens or when OpenGL is available. A `GdkPaintable`
will however always produce the same output for the same snapshot.

A `GdkPaintable` may change its contents, meaning that it will now produce
a different output with the same snapshot. Once that happens, it will call
[method@Gdk.Paintable.invalidate_contents] which will emit the
[signal@GdkPaintable::invalidate-contents] signal. If a paintable is known
to never change its contents, it will set the %GDK_PAINTABLE_STATIC_CONTENTS
flag. If a consumer cannot deal with changing contents, it may call
[method@Gdk.Paintable.get_current_image] 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 doesn't 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 [method@Gdk.Paintable.invalidate_size] which will emit the
[signal@GdkPaintable::invalidate-size] signal. And just like for contents,
if a paintable is known to never change its size, it will set the
%GDK_PAINTABLE_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:
[method@Gdk.Paintable.invalidate_contents],
[method@Gdk.Paintable.invalidate_size],
[func@Gdk.Paintable.new_empty].

https://docs.gtk.org/gdk4/iface.Paintable.html

  • Field Details

  • Constructor Details

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • getCurrentImage

      public Paintable getCurrentImage()
      Gets an immutable paintable for the current contents displayed by @paintable.

      This is useful when you want to retain the current state of an animation,
      for example to take a screenshot of a running animation.

      If the @paintable is already immutable, it will return itself.
      Returns:
      An immutable paintable for the current contents of @paintable

    • getFlags

      public int getFlags()
      Get flags for the paintable.

      This is oftentimes useful for optimizations.

      See [flags@Gdk.PaintableFlags] for the flags and what they mean.
      Returns:
      The `GdkPaintableFlags` for this paintable

    • getIntrinsicAspectRatio

      public double getIntrinsicAspectRatio()
      Gets the preferred aspect ratio the @paintable would like to be displayed at.

      The aspect ratio is the width divided by the height, so a value of 0.5
      means that the @paintable prefers to be displayed twice as high as it
      is wide. Consumers of this interface can use this to preserve aspect
      ratio when displaying the paintable.

      This is a purely informational value and does not in any way limit the
      values that may be passed to [method@Gdk.Paintable.snapshot].

      Usually when a @paintable returns nonzero values from
      [method@Gdk.Paintable.get_intrinsic_width] and
      [method@Gdk.Paintable.get_intrinsic_height] the aspect ratio
      should conform to those values, though that is not required.

      If the @paintable does not have a preferred aspect ratio,
      it returns 0. Negative values are never returned.
      Returns:
      the intrinsic aspect ratio of @paintable or 0 if none.

    • getIntrinsicHeight

      public int getIntrinsicHeight()
      Gets the preferred height the @paintable would like to be displayed at.

      Consumers of this interface can use this to reserve enough space to draw
      the paintable.

      This is a purely informational value and does not in any way limit the
      values that may be passed to [method@Gdk.Paintable.snapshot].

      If the @paintable does not have a preferred height, it returns 0.
      Negative values are never returned.
      Returns:
      the intrinsic height of @paintable or 0 if none.

    • getIntrinsicWidth

      public int getIntrinsicWidth()
      Gets the preferred width the @paintable would like to be displayed at.

      Consumers of this interface can use this to reserve enough space to draw
      the paintable.

      This is a purely informational value and does not in any way limit the
      values that may be passed to [method@Gdk.Paintable.snapshot].

      If the @paintable does not have a preferred width, it returns 0.
      Negative values are never returned.
      Returns:
      the intrinsic width of @paintable or 0 if none.

    • invalidateContents

      public void invalidateContents()
      Called by implementations of `GdkPaintable` to invalidate their contents.

      Unless the contents are invalidated, implementations must guarantee that
      multiple calls of [method@Gdk.Paintable.snapshot] produce the same output.

      This function will emit the [signal@Gdk.Paintable::invalidate-contents]
      signal.

      If a @paintable reports the %GDK_PAINTABLE_STATIC_CONTENTS flag,
      it must not call this function.

    • invalidateSize

      public void invalidateSize()
      Called by implementations of `GdkPaintable` to invalidate their size.

      As long as the size is not invalidated, @paintable must return the same
      values for its intrinsic width, height and aspect ratio.

      This function will emit the [signal@Gdk.Paintable::invalidate-size]
      signal.

      If a @paintable reports the %GDK_PAINTABLE_STATIC_SIZE flag,
      it must not call this function.

    • snapshot

      public void snapshot(@Nonnull Snapshot snapshot, double width, double height)
      Snapshots the given paintable with the given @width and @height.

      The paintable is drawn at the current (0,0) offset of the @snapshot.
      If @width and @height are not larger than zero, this function will
      do nothing.
      Parameters:
      snapshot - a `GdkSnapshot` to snapshot to
      width - width to snapshot in
      height - height to snapshot in

    • onInvalidateContents

      public SignalHandler onInvalidateContents(Paintable.OnInvalidateContents signal)
      Connect to signal "invalidate-contents".
      See Paintable.OnInvalidateContents.onInvalidateContents() for signal description.
      Field SIGNAL_ON_INVALIDATE_CONTENTS contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onInvalidateSize

      public SignalHandler onInvalidateSize(Paintable.OnInvalidateSize signal)
      Connect to signal "invalidate-size".
      See Paintable.OnInvalidateSize.onInvalidateSize() for signal description.
      Field SIGNAL_ON_INVALIDATE_SIZE contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • newEmpty

      public static Paintable newEmpty(int intrinsic_width, int intrinsic_height)
      Returns a paintable that has the given intrinsic size and draws nothing.

      This is often useful for implementing the
      [vfunc@Gdk.Paintable.get_current_image] virtual function
      when the paintable is in an incomplete state (like a
      [class@Gtk.MediaStream] before receiving the first frame).
      Parameters:
      intrinsic_width - The intrinsic width to report. Can be 0 for no width.
      intrinsic_height - The intrinsic height to report. Can be 0 for no height.
      Returns:
      a `GdkPaintable`

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()