diff options
Diffstat (limited to 'ganv')
| -rw-r--r-- | ganv/canvas.h | 317 | ||||
| -rw-r--r-- | ganv/types.h | 7 |
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 */ |