summaryrefslogtreecommitdiffstats
path: root/ganv
diff options
context:
space:
mode:
Diffstat (limited to 'ganv')
-rw-r--r--ganv/canvas.h317
-rw-r--r--ganv/types.h7
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 */