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 30 G_BEGIN_DECLS 31 32 #define GDK_TYPE_PAINTABLE (gdk_paintable_get_type ()) 33 34 GDK_AVAILABLE_IN_ALL 35 G_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 */ 50 typedef 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 */ 87 struct _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 111 GDK_AVAILABLE_IN_ALL 112 void gdk_paintable_snapshot (GdkPaintable *paintable, 113 GdkSnapshot *snapshot, 114 double width, 115 double height); 116 GDK_AVAILABLE_IN_ALL 117 GdkPaintable * gdk_paintable_get_current_image (GdkPaintable *paintable); 118 119 GDK_AVAILABLE_IN_ALL 120 GdkPaintableFlags 121 gdk_paintable_get_flags (GdkPaintable *paintable); 122 GDK_AVAILABLE_IN_ALL 123 int gdk_paintable_get_intrinsic_width (GdkPaintable *paintable); 124 GDK_AVAILABLE_IN_ALL 125 int gdk_paintable_get_intrinsic_height (GdkPaintable *paintable); 126 GDK_AVAILABLE_IN_ALL 127 double gdk_paintable_get_intrinsic_aspect_ratio(GdkPaintable *paintable); 128 129 GDK_AVAILABLE_IN_ALL 130 void 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 */ 138 GDK_AVAILABLE_IN_ALL 139 void gdk_paintable_invalidate_contents (GdkPaintable *paintable); 140 GDK_AVAILABLE_IN_ALL 141 void gdk_paintable_invalidate_size (GdkPaintable *paintable); 142 GDK_AVAILABLE_IN_ALL 143 GdkPaintable * gdk_paintable_new_empty (int intrinsic_width, 144 int intrinsic_height); 145 146 147 G_END_DECLS 148 149 #endif /* __GDK_PAINTABLE_H__ */ 150