GNOME.org
 

[gtk+/wip/baedert/gtkimageview: 265/294] Docs

commit a982646266bea0cbf078ef9338a696baeced039a
Author: Timm Bäder <mail baedert org>
Date:   Fri Feb 12 10:42:44 2016 +0100

    Docs

 docs/reference/gtk/gtk3-sections.txt |    2 +
 gtk/gtkimageview.c                   |  120 +++++++++++++++++++--------------
 2 files changed, 71 insertions(+), 51 deletions(-)
---
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index 96331b1..a879494 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -2024,6 +2024,8 @@ gtk_image_view_get_rotatable
 gtk_image_view_set_zoomable
 gtk_image_view_get_zoomable
 gtk_image_view_get_scale_set
+gtk_image_view_set_transitions_enabled
+gtk_image_view_get_transitions_enabled
 <SUBSECTION Standard>
 GTK_IMAGE_VIEW
 GTK_IS_IMAGE_VIEW
diff --git a/gtk/gtkimageview.c b/gtk/gtkimageview.c
index 2294dd9..1e83659 100644
--- a/gtk/gtkimageview.c
+++ b/gtk/gtkimageview.c
@@ -44,19 +44,14 @@
 
 #include "config.h"
 #include "gtkimageview.h"
-#include "gtktypebuiltins.h"
 #include "gtkintl.h"
 #include "gtkprivate.h"
 #include "gtkrender.h"
-#include "gtkgesture.h"
 #include "gtkgesturerotate.h"
 #include "gtkgesturezoom.h"
 #include "gtkscrollable.h"
-#include "gtkmarshalers.h"
 #include "gtkadjustment.h"
 #include <gdk/gdkcairo.h>
-
-#include <cairo-gobject.h>
 #include <math.h>
 
 #define DEG_TO_RAD(x) (((x) / 360.0) * (2 * M_PI))
@@ -126,8 +121,8 @@ struct _GtkImageViewPrivate
   /* GtkScrollable stuff */
   GtkAdjustment       *hadjustment;
   GtkAdjustment       *vadjustment;
-  GtkScrollablePolicy  hscroll_policy;
-  GtkScrollablePolicy  vscroll_policy;
+  GtkScrollablePolicy  hscroll_policy : 1;
+  GtkScrollablePolicy  vscroll_policy : 1;
 
   gboolean                is_animation;
   GdkPixbufAnimation     *source_animation;
@@ -142,11 +137,12 @@ struct _GtkImageViewPrivate
   double transition_start_scale;
   gint64 scale_transition_start;
 
+  /* We cache the bounding box size so we don't have to
+   * recompute it at every draw() */
   double cached_width;
   double cached_height;
   double cached_scale;
 };
-// XXX Actually honour the scroll policies
 
 enum
 {
@@ -1079,9 +1075,6 @@ gtk_image_view_draw (GtkWidget *widget, cairo_t *ct)
       draw_y = (widget_height - image_height) / 2;
     }
 
-  cairo_save (ct);
-  /* XXX This is unnecessarily big */
-  /*cairo_rectangle (ct, draw_x, draw_y, draw_width, draw_height);*/
   cairo_rectangle (ct, 0, 0, widget_width, widget_height);
 
   if (priv->hadjustment && draw_width >= widget_width)
@@ -1112,7 +1105,6 @@ gtk_image_view_draw (GtkWidget *widget, cairo_t *ct)
                             draw_y / scale / priv->scale_factor);
   cairo_pattern_set_filter (cairo_get_source (ct), CAIRO_FILTER_FAST);
   cairo_fill (ct);
-  cairo_restore (ct);
 
   return GDK_EVENT_PROPAGATE;
 }
@@ -1200,7 +1192,6 @@ gtk_image_view_set_hscroll_policy (GtkImageView        *image_view,
     return;
 
   priv->hscroll_policy = hscroll_policy;
-  gtk_image_view_update_adjustments (image_view);
 }
 
 static void
@@ -1213,7 +1204,6 @@ gtk_image_view_set_vscroll_policy (GtkImageView        *image_view,
     return;
 
   priv->vscroll_policy = vscroll_policy;
-  gtk_image_view_update_adjustments (image_view);
 }
 
 /**
@@ -1232,6 +1222,12 @@ gtk_image_view_set_vscroll_policy (GtkImageView        *image_view,
  * interpolated between the old and the new scale, gtk_image_view_get_scale()
  * will report the one passed to gtk_image_view_set_scale() however.
  *
+ * When calling this function, #GtkImageView will try to keep the currently centered
+ * point of the image where it is, so visually it will "zoom" into the current
+ * center of the widget. Note that #GtkImageView is a #GtkScrollable, so the center
+ * of the image is also the center of the scrolled window in case it is packed into
+ * a #GtkScrolledWindow.
+ *
  * Since: 3.20
  */
 void
@@ -1293,7 +1289,7 @@ gtk_image_view_set_scale (GtkImageView *image_view,
  * gtk_image_view_get_scale:
  * @image_view: A #GtkImageView instance
  *
- * Returns: The current scale applied to the image.
+ * Returns: The current value of the #GtkImageView:scale property.
  *
  * Since: 3.20
  */
@@ -1315,6 +1311,13 @@ gtk_image_view_get_scale (GtkImageView *image_view)
  *   angle of 2, setting it to -2 will result in 358.
  *   Both 0 and 360 are possible.
  *
+ * Sets the value of the #GtkImageView:angle property. When calling this function,
+ * #GtkImageView will try to keep the currently centered point of the image where it is,
+ * so visually the image will not be rotated around its center, but around the current
+ * center of the widget. Note that #GtkImageView is a #GtkScrollable, so the center
+ * of the image is also the center of the scrolled window in case it is packed into
+ * a #GtkScrolledWindow.
+ *
  * Since: 3.20
  */
 void
@@ -1390,7 +1393,7 @@ gtk_image_view_get_angle (GtkImageView *image_view)
 /**
  * gtk_image_view_set_snap_angle:
  * @image_view: A #GtkImageView instance
- * @snap_angle: The new value of the #snap-angle property
+ * @snap_angle: The new value of the #GtkImageView:snap-angle property
  *
  * Setting #snap-angle to %TRUE will cause @image_view's  angle to
  * be snapped to 90° steps. Setting the #GtkImageView:angle property will cause it to
@@ -1444,7 +1447,7 @@ gtk_image_view_get_snap_angle (GtkImageView *image_view)
 /**
  * gtk_image_view_set_fit_allocation:
  * @image_view: A #GtkImageView instance
- * @fit_allocation: The new value of the #fit-allocation property.
+ * @fit_allocation: The new value of the #GtkImageView:fit-allocation property.
  *
  * Setting #GtkImageView:fit-allocation to %TRUE will cause the image to be scaled
  * to the widget's allocation, unless it would cause the image to be
@@ -1511,7 +1514,7 @@ gtk_image_view_get_fit_allocation (GtkImageView *image_view)
 /**
  * gtk_image_view_set_rotatable:
  * @image_view: A #GtkImageView instance
- * @rotatable: The new value of the rotatable property
+ * @rotatable: The new value of the #GtkImageView:rotatable property
  *
  * Sets the value of the #GtkImageView:rotatable property to @rotatable. This controls whether
  * the user can change the angle of the displayed image using a two-finger gesture.
@@ -1556,7 +1559,7 @@ gtk_image_view_get_rotatable (GtkImageView *image_view)
 /**
  * gtk_image_view_set_zoomable:
  * @image_view: A #GtkImageView instance
- * @zoomable: The new value of the #zoomable property
+ * @zoomable: The new value of the #GtkImageView:zoomable property
  *
  * Sets the new value of the #GtkImageView:zoomable property. This controls whether the user can
  * change the #GtkImageView:scale property using a two-finger gesture.
@@ -1601,9 +1604,11 @@ gtk_image_view_get_zoomable (GtkImageView *image_view)
 /**
  * gtk_image_view_set_transitions_enabled:
  * @image_view: A #GtkImageView instance
- * @transitions_enabled: The new value of the #transitions-enabled property
+ * @transitions_enabled: The new value of the #GtkImageView:transitions-enabled property
  *
  * Sets the new value of the #GtkImageView:transitions-enabled property.
+ * Note that even if #GtkImageView:transitions-enabled is %TRUE, transitions will
+ * not be used if #GtkSettings:gtk-enable-animations is %FALSE.
  *
  * Since: 3.20
  */
@@ -2010,9 +2015,9 @@ gtk_image_view_class_init (GtkImageViewClass *view_class)
   /**
    * GtkImageView:scale-set:
    * Whether or not the current value of the scale property was set by the user.
-   * This is to distringuish between scale values set by the GtkImageView itself,
-   * e.g. when fit-allocation is true, which will change the scale depeding on the
-   * widget allocation.
+   * This is to distringuish between scale values set by the #GtkImageView itself,
+   * e.g. when #GtkImageView:fit-allocation is true, which will change the scale
+   * depending on the widget allocation.
    *
    * Since: 3.20
    */
@@ -2048,7 +2053,8 @@ gtk_image_view_class_init (GtkImageViewClass *view_class)
                                                        GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 /**
    * GtkImageView:zoomable:
-   * Whether or not the image can be scaled using a two-finger zoom gesture.
+   * Whether or not the image can be scaled using a two-finger zoom gesture, as well as
+   * scrolling on the #GtkImageView.
    *
    * Since: 3.20
    */
@@ -2061,7 +2067,8 @@ gtk_image_view_class_init (GtkImageViewClass *view_class)
    * GtkImageView:snap-angle:
    * Whether or not the angle property snaps to 90° steps. If this is enabled
    * and the angle property gets set to a non-90° step, the new value will be
-   * set to the closest 90° step
+   * set to the closest 90° step. If #GtkImageView:transitions-enabled is %TRUE,
+   * the angle change from the current angle to the new angle will be interpolated.
    *
    * Since: 3.20
    */
@@ -2073,7 +2080,7 @@ gtk_image_view_class_init (GtkImageViewClass *view_class)
 
   /**
    * GtkImageView:fit-allocation:
-   * If this is TRUE, the scale the image will be drawn in will depend on the current
+   * If this is %TRUE, the scale the image will be drawn in will depend on the current
    * widget allocation. The image will be scaled down to fit into the widget allocation,
    * but never scaled up.
    *
@@ -2090,13 +2097,17 @@ gtk_image_view_class_init (GtkImageViewClass *view_class)
    *
    *  Whether or not certain property changes will be interpolated. This affects a variety
    *  of function calls on a #GtkImageView instance, e.g. setting the angle property, the
-   *  scale property, but also the angle snapping in case snap-angle is set.
+   *  scale property, but also the angle snapping in case #GtkImageView:snap-angle is set.
+   *
+   *  Note that the transitions in #GtkImageView never apply to the actual property values
+   *  set and instead interpolate between the visual angle/scale, so you cannot depend on
+   *  getting 60 notify signal emissions per second.
    *
    *  Since: 3.20
    */
   widget_props[PROP_TRANSITIONS_ENABLED] = g_param_spec_boolean ("transitions-enabled",
                                                                  P_("Transitions Enabled"),
-                                                                 P_("Wheter scale and angle changes get 
interpolated"),
+                                                                 P_("Whether scale and angle changes get 
interpolated"),
                                                                  TRUE,
                                                                  
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
@@ -2151,29 +2162,30 @@ gtk_image_view_update_surface (GtkImageView    *image_view,
                                int              scale_factor)
 {
   GtkImageViewPrivate *priv = gtk_image_view_get_instance_private (image_view);
-  /*int new_width    = gdk_pixbuf_get_width (frame);*/
-  /*int new_height   = gdk_pixbuf_get_height (frame);*/
-  /*int widget_scale = gtk_widget_get_scale_factor (GTK_WIDGET (image_view));*/
-  /*int real_width   = (new_width * scale_factor)  / widget_scale;*/
-  /*int real_height  = (new_height * scale_factor) / widget_scale;*/
   GdkWindow *window = gtk_widget_get_window (GTK_WIDGET (image_view));
   cairo_surface_t *new_surface;
+  gboolean size_changed = TRUE;
 
   new_surface = gdk_cairo_surface_create_from_pixbuf (frame,
                                                       scale_factor,
                                                       window);
 
+  if (priv->image_surface)
+    {
+      size_changed = (cairo_image_surface_get_width (priv->image_surface) !=
+                      cairo_image_surface_get_width (new_surface)) ||
+                     (cairo_image_surface_get_height (priv->image_surface) !=
+                      cairo_image_surface_get_height (new_surface));
+    }
+
   gtk_image_view_replace_surface (image_view,
                                   new_surface,
                                   scale_factor);
 
-  /* TODO: Strictly speaking, we don't need to queue a resize if the
-   * surface size doesn't change. */
-
-  if (!priv->fit_allocation)
-    gtk_widget_queue_resize (GTK_WIDGET (image_view));
-  else
+  if (priv->fit_allocation || !size_changed)
     gtk_widget_queue_draw (GTK_WIDGET (image_view));
+  else
+    gtk_widget_queue_resize (GTK_WIDGET (image_view));
 
   g_assert (priv->image_surface != NULL);
 }
@@ -2335,7 +2347,10 @@ gtk_image_view_load_from_file_async (GtkImageView        *image_view,
  * @result: A #GAsyncResult
  * @error: (nullable): Location to store error information in case the operation fails
  *
- * Returns: %TRUE if the operation succeeded, %FALSE otherwise.
+ * Finished an asynchronous operation started with gtk_image_view_load_from_file_async().
+ *
+ * Returns: %TRUE if the operation succeeded, %FALSE otherwise,
+ * in which case @error will be set.
  *
  * Since: 3.20
  */
@@ -2393,6 +2408,8 @@ gtk_image_view_load_from_stream_async (GtkImageView        *image_view,
  * @result: A #GAsyncResult
  * @error: (nullable): Location to store error information on failure
  *
+ * Finishes an asynchronous operation started by gtk_image_view_load_from_stream_async().
+ *
  * Returns: %TRUE if the operation finished successfully, %FALSE otherwise.
  *
  * Since: 3.20
@@ -2417,6 +2434,10 @@ gtk_image_view_load_from_stream_finish (GtkImageView  *image_view,
  *   factor is 2, and the screen's scale factor is also 2, the
  *   pixbuf won't be scaled up.
  *
+ * Sets the internal image to @pixbuf. @image_view will not take ownership of @pixbuf,
+ * so it will not unref or free it in any way. If you want to unset the internal
+ * image data, look at gtk_image_view_set_surface().
+ *
  * Since: 3.20
  */
 void
@@ -2446,8 +2467,10 @@ gtk_image_view_set_pixbuf (GtkImageView    *image_view,
  * gtk_image_view_set_surface:
  * @image_view: A #GtkImageView instance
  * @surface: (nullable) (transfer full): A #cairo_surface_t of type %CAIRO_SURFACE_TYPE_IMAGE, or
- *   %NULL to unset any internal image data. In case this is %NULL, the scale will
- *   be reset to 1.0.
+ *   %NULL to unset any internal image data.
+ *
+ * Sets the internal surface to @surface. @image_view will assume ownership of this surface.
+ * You can use this function to unset any internal image data by passing %NULL as @surface.
  *
  * Since: 3.20
  */
@@ -2469,15 +2492,6 @@ gtk_image_view_set_surface (GtkImageView    *image_view,
 
       g_return_if_fail (scale_x == scale_y);
     }
-  else
-    {
-      priv->scale = 1.0;
-      g_object_notify_by_pspec (G_OBJECT (image_view),
-                                widget_props[PROP_SCALE]);
-      priv->scale_set = FALSE;
-      g_object_notify_by_pspec (G_OBJECT (image_view),
-                                widget_props[PROP_SCALE_SET]);
-    }
 
   if (priv->is_animation)
     {
@@ -2508,6 +2522,10 @@ gtk_image_view_set_surface (GtkImageView    *image_view,
  *   factor is 2, and the screen's scale factor is also 2, the
  *   animation won't be scaled up.
  *
+ * Takes the given #GdkPixbufAnimation and sets the internal image to that
+ * animation. This will also automatically start the animation. If you want
+ * to unset the internal image data, look at gtk_image_view_set_surface().
+ *
  * Since: 3.20
  */
 void
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]