Clean up public canvas interface.

git-svn-id: http://svn.drobilla.net/lad/trunk/ganv@5339 a436a847-0d15-0410-975c-d299462d15a1

2 files changed, 269 insertions, 55 deletions

diff --git a/ganv/canvas.h b/ganv/canvas.h
index f1bea92..b776b74 100644
--- a/ganv/canvas.h
+++ b/ganv/canvas.h
@@ -65,105 +65,317 @@ struct _GanvCanvasClass {
 
 GType ganv_canvas_get_type(void) G_GNUC_CONST;
 
-GanvCanvas* ganv_canvas_new(double width, double height);
+/**
+ * GanvEdgeFunc:
+ * A node function that takes a user data argument (for callbacks).
+ *
+ * Note that in the Gtk world it is considered safe to cast a function to a
+ * function with more arguments and call the resulting pointer, so functions
+ * like ganv_edge_select can safely be used where a GanvEdgeFunc is expected.
+ */
+typedef void (*GanvEdgeFunc)(GanvEdge* edge, void* data);
 
-GanvItem* ganv_canvas_root(GanvCanvas* canvas);
+/**
+ * GanvNodeFunc:
+ * A node function that takes a user data argument (for callbacks).
+ *
+ * Note that in the Gtk world it is considered safe to cast a function to a
+ * function with more arguments and call the resulting pointer, so functions
+ * like ganv_node_select can safely be used where a GanvNodeFunc is expected.
+ */
+typedef void (*GanvNodeFunc)(GanvNode* node, void* data);
 
-void ganv_canvas_set_scroll_region(GanvCanvas* canvas,
-                                   double x1, double y1, double x2, double y2);
+/**
+ * ganv_canvas_new:
+ *
+ * Return value: A newly-created canvas.
+ */
+GanvCanvas*
+ganv_canvas_new(double width, double height);
 
-void ganv_canvas_get_scroll_region(GanvCanvas* canvas,
-                                   double* x1, double* y1, double* x2, double* y2);
+/**
+ * ganv_canvas_root:
+ * @canvas: A canvas.
+ *
+ * Return value: (transfer none): The root group of the canvas.
+ */
+GanvItem*
+ganv_canvas_root(GanvCanvas* canvas);
 
-void ganv_canvas_set_center_scroll_region(GanvCanvas* canvas, gboolean center_scroll_region);
+/**
+ * ganv_canvas_set_scroll_region:
+ * @canvas: A canvas.
+ * @x1: Leftmost limit of the scrolling region.
+ * @y1: Upper limit of the scrolling region.
+ * @x2: Rightmost limit of the scrolling region.
+ * @y2: Lower limit of the scrolling region.
+ *
+ * Sets the scrolling region of a canvas to the specified rectangle.  The
+ * canvas will then be able to scroll only within this region.  The view of the
+ * canvas is adjusted as appropriate to display as much of the new region as
+ * possible.
+ */
+void
+ganv_canvas_set_scroll_region(GanvCanvas* canvas,
+                              double x1, double y1, double x2, double y2);
 
-gboolean ganv_canvas_get_center_scroll_region(GanvCanvas* canvas);
+/**
+ * ganv_canvas_get_scroll_region:
+ * @canvas: A canvas.
+ * @x1: Leftmost limit of the scrolling region (return value).
+ * @y1: Upper limit of the scrolling region (return value).
+ * @x2: Rightmost limit of the scrolling region (return value).
+ * @y2: Lower limit of the scrolling region (return value).
+ *
+ * Queries the scrolling region of a canvas.
+ */
+void
+ganv_canvas_get_scroll_region(GanvCanvas* canvas,
+                              double* x1, double* y1, double* x2, double* y2);
 
-void ganv_canvas_scroll_to(GanvCanvas* canvas, int cx, int cy);
+/**
+ * ganv_canvas_set_center_scroll_region:
+ * @canvas: A canvas.
+ * @center_scroll_region: Whether to center the scrolling region in the canvas
+ * window when it is smaller than the canvas' allocation.
+ *
+ * When the scrolling region of the canvas is smaller than the canvas window,
+ * e.g.  the allocation of the canvas, it can be either centered on the window
+ * or simply made to be on the upper-left corner on the window.  This function
+ * lets you configure this property.
+ */
+void
+ganv_canvas_set_center_scroll_region(GanvCanvas* canvas,
+                                     gboolean    center_scroll_region);
 
-void ganv_canvas_get_scroll_offsets(const GanvCanvas* canvas, int* cx, int* cy);
+/**
+ * ganv_canvas_get_center_scroll_region:
+ * @canvas: A canvas.
+ *
+ * Returns whether the canvas is set to center the scrolling region in the
+ * window if the former is smaller than the canvas' allocation.
+ *
+ * Returns: Whether the scroll region is being centered in the canvas window.
+ */
+gboolean
+ganv_canvas_get_center_scroll_region(GanvCanvas* canvas);
 
-GanvItem* ganv_canvas_get_item_at(GanvCanvas* canvas, double x, double y);
+/**
+ * ganv_canvas_scroll_to:
+ * @canvas: A canvas.
+ * @cx: Horizontal scrolling offset in canvas pixel units.
+ * @cy: Vertical scrolling offset in canvas pixel units.
+ *
+ * Makes a canvas scroll to the specified offsets, given in canvas pixel units.
+ * The canvas will adjust the view so that it is not outside the scrolling
+ * region.  This function is typically not used, as it is better to hook
+ * scrollbars to the canvas layout's scrolling adjusments.
+ */
+void
+ganv_canvas_scroll_to(GanvCanvas* canvas, int cx, int cy);
 
-void ganv_canvas_w2c_affine(GanvCanvas* canvas, cairo_matrix_t* matrix);
+/**
+ * ganv_canvas_get_scroll_offsets:
+ * @canvas: A canvas.
+ * @cx: Horizontal scrolling offset (return value).
+ * @cy: Vertical scrolling offset (return value).
+ *
+ * Queries the scrolling offsets of a canvas.  The values are returned in canvas
+ * pixel units.
+ */
+void
+ganv_canvas_get_scroll_offsets(const GanvCanvas* canvas, int* cx, int* cy);
 
-void ganv_canvas_w2c(GanvCanvas* canvas, double wx, double wy, int* cx, int* cy);
+/**
+ * ganv_canvas_get_item_at:
+ * @canvas: A canvas.
+ * @x: X position in world coordinates.
+ * @y: Y position in world coordinates.
+ *
+ * Looks for the item that is under the specified position, which must be
+ * specified in world coordinates.
+ *
+ * Returns: (transfer none): The sought item, or NULL if no item is at the
+ * specified coordinates.
+ */
+GanvItem*
+ganv_canvas_get_item_at(GanvCanvas* canvas, double x, double y);
 
-void ganv_canvas_w2c_d(GanvCanvas* canvas, double wx, double wy, double* cx, double* cy);
+/**
+ * ganv_canvas_w2c_affine:
+ * @canvas: A canvas.
+ * @matrix: An affine transformation matrix (return value).
+ *
+ * Gets the affine transform that converts from world coordinates to canvas
+ * pixel coordinates.
+ */
+void
+ganv_canvas_w2c_affine(GanvCanvas* canvas, cairo_matrix_t* matrix);
 
-void ganv_canvas_c2w(GanvCanvas* canvas, int cx, int cy, double* wx, double* wy);
+/**
+ * ganv_canvas_w2c:
+ * @canvas: A canvas.
+ * @wx: World X coordinate.
+ * @wy: World Y coordinate.
+ * @cx: X pixel coordinate (return value).
+ * @cy: Y pixel coordinate (return value).
+ *
+ * Converts world coordinates into canvas pixel coordinates.
+ */
+void
+ganv_canvas_w2c(GanvCanvas* canvas, double wx, double wy, int* cx, int* cy);
 
-void ganv_canvas_window_to_world(GanvCanvas* canvas,
-                                 double winx, double winy, double* worldx, double* worldy);
+/**
+ * ganv_canvas_w2c_d:
+ * @canvas: A canvas.
+ * @wx: World X coordinate.
+ * @wy: World Y coordinate.
+ * @cx: X pixel coordinate (return value).
+ * @cy: Y pixel coordinate (return value).
+ *
+ * Converts world coordinates into canvas pixel coordinates.  This version
+ * returns floating point coordinates, for greater precision.
+ */
+void
+ganv_canvas_w2c_d(GanvCanvas* canvas,
+                  double      wx,
+                  double      wy,
+                  double*     cx,
+                  double*     cy);
 
-void ganv_canvas_world_to_window(GanvCanvas* canvas,
-                                 double worldx, double worldy, double* winx, double* winy);
+/**
+ * ganv_canvas_c2w:
+ * @canvas: A canvas.
+ * @cx: Canvas pixel X coordinate.
+ * @cy: Canvas pixel Y coordinate.
+ * @wx: X world coordinate (return value).
+ * @wy: Y world coordinate (return value).
+ *
+ * Converts canvas pixel coordinates to world coordinates.
+ */
+void
+ganv_canvas_c2w(GanvCanvas* canvas, int cx, int cy, double* wx, double* wy);
 
+/**
+ * ganv_canvas_window_to_world:
+ * @canvas: A canvas.
+ * @winx: Window-relative X coordinate.
+ * @winy: Window-relative Y coordinate.
+ * @worldx: X world coordinate (return value).
+ * @worldy: Y world coordinate (return value).
+ *
+ * Converts window-relative coordinates into world coordinates.  You can use
+ * this when you need to convert mouse coordinates into world coordinates, for
+ * example.
+ */
 void
-ganv_canvas_resize(GanvCanvas* canvas, double width, double height);
+ganv_canvas_window_to_world(GanvCanvas* canvas,
+                            double      winx,
+                            double      winy,
+                            double*     worldx,
+                            double*     worldy);
 
+/**
+ * ganv_canvas_world_to_window:
+ * @canvas: A canvas.
+ * @worldx: World X coordinate.
+ * @worldy: World Y coordinate.
+ * @winx: X window-relative coordinate.
+ * @winy: Y window-relative coordinate.
+ *
+ * Converts world coordinates into window-relative coordinates.
+ */
 void
-ganv_canvas_add_node(GanvCanvas* canvas,
-                     GanvNode*   node);
+ganv_canvas_world_to_window(GanvCanvas* canvas,
+                            double      worldx,
+                            double      worldy,
+                            double*     winx,
+                            double*     winy);
 
+/**
+ * ganv_canvas_resize:
+ * Resize the canvas to the given dimensions.
+ */
 void
-ganv_canvas_remove_node(GanvCanvas* canvas,
-                        GanvNode*   node);
+ganv_canvas_resize(GanvCanvas* canvas, double width, double height);
 
+/**
+ * ganv_canvas_get_edge:
+ * Get the edge between two nodes, or NULL if none exists.
+ *
+ * Return value: (transfer none): The root group of @canvas.
+ */
 GanvEdge*
 ganv_canvas_get_edge(GanvCanvas* canvas,
                      GanvNode*   tail,
                      GanvNode*   head);
 
-void
-ganv_canvas_disconnect_edge(GanvCanvas* canvas,
-                            GanvEdge*   edge);
-
+/**
+ * ganv_canvas_remove_edge_between:
+ *
+ * Remove the edge from @tail to @head if one exists.
+ */
 void
 ganv_canvas_remove_edge_between(GanvCanvas* canvas,
                                 GanvNode*   tail,
                                 GanvNode*   head);
 
+/**
+ * ganv_canvas_get_default_font_size:
+ *
+ * Get the default font size in points.
+ */
 double
 ganv_canvas_get_default_font_size(const GanvCanvas* canvas);
 
+/**
+ * ganv_canvas_get_direction:
+ *
+ * Return the direction of signal flow.
+ */
 GanvDirection
 ganv_canvas_get_direction(GanvCanvas* canvas);
 
+/**
+ * ganv_canvas_set_direction:
+ *
+ * Set the direction of signal flow.
+ */
 void
 ganv_canvas_set_direction(GanvCanvas* canvas, GanvDirection dir);
 
+/**
+ * ganv_canvas_clear_selection:
+ *
+ * Deselect any selected items on the canvas.
+ */
 void
 ganv_canvas_clear_selection(GanvCanvas* canvas);
 
+/**
+ * ganv_canvas_arrange:
+ *
+ * Automatically arrange the canvas contents.
+ */
 void
 ganv_canvas_arrange(GanvCanvas* canvas);
 
-void
-ganv_canvas_export_dot(GanvCanvas* canvas, const char* filename);
-
-gboolean
-ganv_canvas_get_locked(GanvCanvas* canvas);
-
 /**
- * GanvEdgeFunc:
- * A node function that takes a user data argument (for callbacks).
+ * ganv_canvas_export_dot:
  *
- * Note that in the Gtk world it is considered safe to cast a function to a
- * function with more arguments and call the resulting pointer, so functions
- * like ganv_edge_select can safely be used where a GanvEdgeFunc is expected.
+ * Write a Graphviz DOT description of the canvas to a file.
  */
-typedef void (*GanvEdgeFunc)(GanvEdge* edge, void* data);
+void
+ganv_canvas_export_dot(GanvCanvas* canvas, const char* filename);
+
 
 /**
- * GanvNodeFunc:
- * A node function that takes a user data argument (for callbacks).
+ * ganv_canvas_get_locked:
  *
- * Note that in the Gtk world it is considered safe to cast a function to a
- * function with more arguments and call the resulting pointer, so functions
- * like ganv_node_select can safely be used where a GanvNodeFunc is expected.
+ * Return true iff the canvas is locked and nodes may not move.
  */
-typedef void (*GanvNodeFunc)(GanvNode* node, void* data);
+gboolean
+ganv_canvas_get_locked(GanvCanvas* canvas);
 
 /**
  * ganv_canvas_for_each_node:
@@ -189,7 +401,7 @@ ganv_canvas_for_each_selected_node(GanvCanvas*  canvas,
 
 /**
  * ganv_canvas_empty:
-
+ *
  * Return value: True if there are no items on the canvas.
  */
 gboolean
@@ -276,7 +488,16 @@ ganv_canvas_get_zoom(GanvCanvas* canvas);
 
 /**
  * ganv_canvas_set_zoom:
- * Set the current zoom factor (pixels per unit).
+ * @canvas: A canvas.
+ * @zoom: The number of pixels that correspond to one canvas unit.
+ *
+ * The anchor point for zooming, i.e. the point that stays fixed and all others
+ * zoom inwards or outwards from it, depends on whether the canvas is set to
+ * center the scrolling region or not.  You can control this using the
+ * ganv_canvas_set_center_scroll_region() function.  If the canvas is set to
+ * center the scroll region, then the center of the canvas window is used as
+ * the anchor point for zooming.  Otherwise, the upper-left corner of the
+ * canvas window is used as the anchor point.
  */
 void
 ganv_canvas_set_zoom(GanvCanvas* canvas, double zoom);
diff --git a/ganv/types.h b/ganv/types.h
index 677cb06..10b6a90 100644
--- a/ganv/types.h
+++ b/ganv/types.h
@@ -23,12 +23,5 @@ typedef struct _GanvNode   GanvNode;
 typedef struct _GanvPort   GanvPort;
 typedef struct _GanvBox    GanvBox;
 
-#ifdef GANV_FDGL
-typedef struct {
-	double x;
-	double y;
-} Vector;
-#endif  // GANV_FDGL
-
 #endif  /* GANV_TYPES_H */