Package org.gnome.gdk

Interface Paintable

All Superinterfaces:

Proxy

All Known Subinterfaces:

SymbolicPaintable

All Known Implementing Classes:

DmabufTexture, GLTexture, IconPaintable, MediaFile, MediaFile.MediaFile$Impl, MediaStream, MediaStream.MediaStream$Impl, MemoryTexture, Paintable.Paintable$Impl, SpinnerPaintable, SymbolicPaintable.SymbolicPaintable$Impl, Texture, Texture.Texture$Impl, WidgetPaintable

@Generated("io.github.jwharm.JavaGI")
public interface Paintable
extends Proxy

An interface for 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, HTML/CSS Paint Sources, or SVG Paint Servers.

A GdkPaintable can be snapshot at any time and size using snapshot(org.gnome.gdk.Snapshot, double, double). 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 Snapshot 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 invalidateContents() which will emit the Gdk.Paintable::invalidate-contents signal. If a paintable is known to never change its contents, it will set the PaintableFlags.CONTENTS flag. If a consumer cannot deal with changing contents, it may call getCurrentImage() 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 invalidateSize() which will emit the Gdk.Paintable::invalidate-size signal. And just like for contents, if a paintable is known to never change its size, it will set the PaintableFlags.SIZE flag.

Besides API for applications, there are some functions that are only useful for implementing subclasses and should not be used by applications: invalidateContents(), invalidateSize(), newEmpty(int, int).

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Paintable.InvalidateContentsCallback	Functional interface declaration of the InvalidateContentsCallback callback.
static interface	Paintable.InvalidateSizeCallback	Functional interface declaration of the InvalidateSizeCallback callback.
static class	Paintable.Paintable$Impl	The Paintable$Impl type represents a native instance of the Paintable interface.
static class	Paintable.PaintableInterface	The list of functions that can be implemented for the GdkPaintable interface.

Method Summary

Modifier and Type	Method	Description
default void	computeConcreteSize(double specifiedWidth, double specifiedHeight, double defaultWidth, double defaultHeight, Out<Double> concreteWidth, Out<Double> concreteHeight)	Compute a concrete size for the GdkPaintable.
default void	emitInvalidateContents()	Emits the "invalidate-contents" signal.
default void	emitInvalidateSize()	Emits the "invalidate-size" signal.
default Paintable	getCurrentImage()	Gets an immutable paintable for the current contents displayed by paintable.
default Set<PaintableFlags>	getFlags()	Get flags for the paintable.
default double	getIntrinsicAspectRatio()	Gets the preferred aspect ratio the this Paintable would like to be displayed at.
default int	getIntrinsicHeight()	Gets the preferred height the this Paintable would like to be displayed at.
default int	getIntrinsicWidth()	Gets the preferred width the this Paintable would like to be displayed at.
static @Nullable Type	getType()	Get the GType of the Paintable class
default void	invalidateContents()	Called by implementations of GdkPaintable to invalidate their contents.
default void	invalidateSize()	Called by implementations of GdkPaintable to invalidate their size.
static Paintable	newEmpty(int intrinsicWidth, int intrinsicHeight)	Returns a paintable that has the given intrinsic size and draws nothing.
default SignalConnection<Paintable.InvalidateContentsCallback>	onInvalidateContents(Paintable.InvalidateContentsCallback handler)	Emitted when the contents of the paintable change.
default SignalConnection<Paintable.InvalidateSizeCallback>	onInvalidateSize(Paintable.InvalidateSizeCallback handler)	Emitted when the intrinsic size of the paintable changes.
default void	snapshot(Snapshot snapshot, double width, double height)	Snapshots the given paintable with the given width and height.

Methods inherited from interface org.javagi.base.Proxy

handle

Method Details

getType

static @Nullable Type getType()

Get the GType of the Paintable class

Returns:

the GType

newEmpty

static Paintable newEmpty(int intrinsicWidth,
 int intrinsicHeight)

Returns a paintable that has the given intrinsic size and draws nothing.

This is often useful for implementing the getCurrentImage() virtual function when the paintable is in an incomplete state (like a GtkMediaStream before receiving the first frame).

Parameters:

intrinsicWidth - The intrinsic width to report. Can be 0 for no width.

intrinsicHeight - The intrinsic height to report. Can be 0 for no height.

Returns:

a GdkPaintable

computeConcreteSize

default void computeConcreteSize(double specifiedWidth,
 double specifiedHeight,
 double defaultWidth,
 double defaultHeight,
 Out<Double> concreteWidth,
 Out<Double> concreteHeight)

Compute a concrete size for the GdkPaintable.

Applies the sizing algorithm outlined in the CSS Image spec to the given paintable. See that link for more details.

It is not necessary to call this function when both specifiedWidth and specifiedHeight are known, but it is useful to call this function in GtkWidget:measure implementations to compute the other dimension when only one dimension is given.

Parameters:

specifiedWidth - the width this Paintable could be drawn into or 0.0 if unknown

specifiedHeight - the height this Paintable could be drawn into or 0.0 if unknown

defaultWidth - the width this Paintable would be drawn into if no other constraints were given

defaultHeight - the height this Paintable would be drawn into if no other constraints were given

concreteWidth - will be set to the concrete width computed

concreteHeight - will be set to the concrete height computed

getCurrentImage

default 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 this Paintable is already immutable, it will return itself.

Returns:

An immutable paintable for the current contents of this Paintable

getFlags

default Set<PaintableFlags> getFlags()

Get flags for the paintable.

This is oftentimes useful for optimizations.

See Gdk.PaintableFlags for the flags and what they mean.

Returns:

The GdkPaintableFlags for this paintable

getIntrinsicAspectRatio

default double getIntrinsicAspectRatio()

Gets the preferred aspect ratio the this 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 this 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 snapshot(org.gnome.gdk.Snapshot, double, double).

Usually when a this Paintable returns nonzero values from getIntrinsicWidth() and getIntrinsicHeight() the aspect ratio should conform to those values, though that is not required.

If the this Paintable does not have a preferred aspect ratio, it returns 0. Negative values are never returned.

Returns:

the intrinsic aspect ratio of this Paintable or 0 if none.

getIntrinsicHeight

default int getIntrinsicHeight()

Gets the preferred height the this 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 snapshot(org.gnome.gdk.Snapshot, double, double).

If the this Paintable does not have a preferred height, it returns 0. Negative values are never returned.

Returns:

the intrinsic height of this Paintable or 0 if none.

getIntrinsicWidth

default int getIntrinsicWidth()

Gets the preferred width the this 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 snapshot(org.gnome.gdk.Snapshot, double, double).

If the this Paintable does not have a preferred width, it returns 0. Negative values are never returned.

Returns:

the intrinsic width of this Paintable or 0 if none.

invalidateContents

default void invalidateContents()

Called by implementations of GdkPaintable to invalidate their contents.

Unless the contents are invalidated, implementations must guarantee that multiple calls of snapshot(org.gnome.gdk.Snapshot, double, double) produce the same output.

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

If a this Paintable reports the PaintableFlags.CONTENTS flag, it must not call this function.

invalidateSize

default void invalidateSize()

Called by implementations of GdkPaintable to invalidate their size.

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

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

If a this Paintable reports the PaintableFlags.SIZE flag, it must not call this function.

snapshot

default void snapshot(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

default SignalConnection<Paintable.InvalidateContentsCallback> onInvalidateContents(Paintable.InvalidateContentsCallback handler)

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.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Paintable.InvalidateContentsCallback.run()

emitInvalidateContents

default void emitInvalidateContents()

Emits the "invalidate-contents" signal. See onInvalidateContents(org.gnome.gdk.Paintable.InvalidateContentsCallback).

onInvalidateSize

default SignalConnection<Paintable.InvalidateSizeCallback> onInvalidateSize(Paintable.InvalidateSizeCallback handler)

Emitted when the intrinsic size of the paintable changes.

This means the values reported by at least one of getIntrinsicWidth(), getIntrinsicHeight() or getIntrinsicAspectRatio() has changed.

Examples for such an event would be a paintable displaying the contents of a toplevel surface being resized.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Paintable.InvalidateSizeCallback.run()

emitInvalidateSize

default void emitInvalidateSize()

Emits the "invalidate-size" signal. See onInvalidateSize(org.gnome.gdk.Paintable.InvalidateSizeCallback).