1/*
2 * Copyright © 2018 Benjamin Otte
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16 *
17 * Authors: Benjamin Otte <otte@gnome.org>
18 */
19
20#ifndef __GDK_PAINTABLE_H__
21#define __GDK_PAINTABLE_H__
22
23#if !defined (__GDK_H_INSIDE__) && !defined (GTK_COMPILATION)
24#error "Only <gdk/gdk.h> can be included directly."
25#endif
26
27#include <gdk/gdktypes.h>
28#include <gdk/gdkversionmacros.h>
29
30G_BEGIN_DECLS
31
32#define GDK_TYPE_PAINTABLE (gdk_paintable_get_type ())
33
34GDK_AVAILABLE_IN_ALL
35G_DECLARE_INTERFACE (GdkPaintable, gdk_paintable, GDK, PAINTABLE, GObject)
36
37/**
38 * GdkPaintableFlags:
39 * @GDK_PAINTABLE_STATIC_SIZE: The size is immutable.
40 * The [signal@GdkPaintable::invalidate-size] signal will never be
41 * emitted.
42 * @GDK_PAINTABLE_STATIC_CONTENTS: The content is immutable.
43 * The [signal@GdkPaintable::invalidate-contents] signal will never be
44 * emitted.
45 *
46 * Flags about a paintable object.
47 *
48 * Implementations use these for optimizations such as caching.
49 */
50typedef enum {
51 GDK_PAINTABLE_STATIC_SIZE = 1 << 0,
52 GDK_PAINTABLE_STATIC_CONTENTS = 1 << 1
53} GdkPaintableFlags;
54
55/**
56 * GdkPaintableInterface:
57 * @snapshot: Snapshot the paintable. The given @width and @height are
58 * guaranteed to be larger than 0.0. The resulting snapshot must modify
59 * only the area in the rectangle from (0,0) to (width, height).
60 * This is the only function that must be implemented for this interface.
61 * @get_current_image: return a `GdkPaintable` that does not change over
62 * time. This means the `GDK_PAINTABLE_STATIC_SIZE` and
63 * `GDK_PAINTABLE_STATIC_CONTENTS` flag are set.
64 * @get_flags: Get the flags for this instance. See [enum@Gdk.PaintableFlags]
65 * for details.
66 * @get_intrinsic_width: The preferred width for this object to be
67 * snapshot at or 0 if none. This is purely a hint. The object must still
68 * be able to render at any size.
69 * @get_intrinsic_height: The preferred height for this object to be
70 * snapshot at or 0 if none. This is purely a hint. The object must still
71 * be able to render at any size.
72 * @get_intrinsic_aspect_ratio: The preferred aspect ratio for this object
73 * or 0 if none. If both [vfunc@Gdk.Paintable.get_intrinsic_width]
74 * and [vfunc@Gdk.Paintable.get_intrinsic_height] return non-zero
75 * values, this function should return the aspect ratio computed from those.
76 *
77 * The list of functions that can be implemented for the `GdkPaintable`
78 * interface.
79 *
80 * Note that apart from the [vfunc@Gdk.Paintable.snapshot] function,
81 * no virtual function of this interface is mandatory to implement, though it
82 * is a good idea to implement [vfunc@Gdk.Paintable.get_current_image]
83 * for non-static paintables and [vfunc@Gdk.Paintable.get_flags] if the
84 * image is not dynamic as the default implementation returns no flags and
85 * that will make the implementation likely quite slow.
86 */
87struct _GdkPaintableInterface
88{
89 /*< private >*/
90 GTypeInterface g_iface;
91
92 /*< public >*/
93 /* draw to 0,0 with the given width and height */
94 void (* snapshot) (GdkPaintable *paintable,
95 GdkSnapshot *snapshot,
96 double width,
97 double height);
98 /* get the current contents in an immutable form (optional) */
99 GdkPaintable * (* get_current_image) (GdkPaintable *paintable);
100
101 /* get flags for potential optimizations (optional) */
102 GdkPaintableFlags (* get_flags) (GdkPaintable *paintable);
103 /* preferred width of paintable or 0 if it has no width (optional) */
104 int (* get_intrinsic_width) (GdkPaintable *paintable);
105 /* preferred height of paintable or 0 if it has no height (optional) */
106 int (* get_intrinsic_height) (GdkPaintable *paintable);
107 /* aspect ratio (width / height) of paintable or 0 if it has no aspect ratio (optional) */
108 double (* get_intrinsic_aspect_ratio) (GdkPaintable *paintable);
109};
110
111GDK_AVAILABLE_IN_ALL
112void gdk_paintable_snapshot (GdkPaintable *paintable,
113 GdkSnapshot *snapshot,
114 double width,
115 double height);
116GDK_AVAILABLE_IN_ALL
117GdkPaintable * gdk_paintable_get_current_image (GdkPaintable *paintable);
118
119GDK_AVAILABLE_IN_ALL
120GdkPaintableFlags
121 gdk_paintable_get_flags (GdkPaintable *paintable);
122GDK_AVAILABLE_IN_ALL
123int gdk_paintable_get_intrinsic_width (GdkPaintable *paintable);
124GDK_AVAILABLE_IN_ALL
125int gdk_paintable_get_intrinsic_height (GdkPaintable *paintable);
126GDK_AVAILABLE_IN_ALL
127double gdk_paintable_get_intrinsic_aspect_ratio(GdkPaintable *paintable);
128
129GDK_AVAILABLE_IN_ALL
130void gdk_paintable_compute_concrete_size (GdkPaintable *paintable,
131 double specified_width,
132 double specified_height,
133 double default_width,
134 double default_height,
135 double *concrete_width,
136 double *concrete_height);
137/* for implementations only */
138GDK_AVAILABLE_IN_ALL
139void gdk_paintable_invalidate_contents (GdkPaintable *paintable);
140GDK_AVAILABLE_IN_ALL
141void gdk_paintable_invalidate_size (GdkPaintable *paintable);
142GDK_AVAILABLE_IN_ALL
143GdkPaintable * gdk_paintable_new_empty (int intrinsic_width,
144 int intrinsic_height);
145
146
147G_END_DECLS
148
149#endif /* __GDK_PAINTABLE_H__ */
150

source code of gtk/gdk/gdkpaintable.h