.\" Copyright (c) 2007-2022 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 21, 2022 .Dt AG_GRAPH 3 .Os Agar 1.7 .Sh NAME .Nm AG_Graph .Nd agar graph view widget .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION .\" IMAGE(/widgets/AG_Graph.png, "The AG_Graph(3) widget") The .Nm widget displays a graph. A graph is composed of vertices (or .Sq nodes ) and edges that connect pairs of vertices. .Pp Edges may be either directed or undirected. Labels and colors can be associated with edges or vertices. .Sh INHERITANCE HIERARCHY .Xr AG_Object 3 -> .Xr AG_Widget 3 -> .Nm . .Sh INITIALIZATION .nr nS 1 .Ft "AG_Graph *" .Fn AG_GraphNew "AG_Widget *parent" "Uint flags" .Pp .Ft "void" .Fn AG_GraphSizeHint "AG_Graph *graph" "Uint width" "Uint height" .Pp .nr nS 0 The .Fn AG_GraphNew function allocates, initializes, and attaches a new .Nm widget. Acceptable .Fa flags include: .Bl -tag -width "AG_GRAPH_NO_SELECT " .It AG_GRAPH_NO_MOVE User cannot move vertices. .It AG_GRAPH_NO_SELECT User cannot select vertices. .It AG_GRAPH_NO_MENUS Disable popup menus. .It AG_GRAPH_READONLY Implies .Dv AG_GRAPH_NO_MOVE , .Dv AG_GRAPH_NO_SELECT and .Dv AG_GRAPH_NO_MENUS . .It AG_GRAPH_HFILL Expand horizontally in parent container. .It AG_GRAPH_VFILL Expand vertically in parent container. .It AG_GRAPH_EXPAND Shorthand for .Dv AG_GRAPH_HFILL | AG_GRAPH_VFILL . .El .Pp The .Fn AG_GraphSizeHint function requests an initial widget size in pixels. .Sh VERTICES .nr nS 1 .Ft "AG_GraphVertex *" .Fn AG_GraphVertexNew "AG_Graph *graph" "void *userPtr" .Pp .Ft "AG_GraphVertex *" .Fn AG_GraphVertexFind "AG_Graph *graph" "void *userPtr" .Pp .Ft "void" .Fn AG_GraphVertexLabel "AG_GraphVertex *vertex" "const char *format" "..." .Pp .Ft "void" .Fn AG_GraphVertexLabelS "AG_GraphVertex *vertex" "const char *text" .Pp .Ft "void" .Fn AG_GraphVertexColorLabel "AG_GraphVertex *vertex" "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft "void" .Fn AG_GraphVertexColorBG "AG_GraphVertex *vertex" "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft "void" .Fn AG_GraphVertexSize "AG_GraphVertex *vertex" "Uint width" "Uint height" .Pp .Ft "void" .Fn AG_GraphVertexPosition "AG_GraphVertex *vertex" "int x" "int y" .Pp .Ft "void" .Fn AG_GraphVertexPopupMenu "AG_GraphVertex *vertex" "AG_PopupMenu *pm" .Pp .nr nS 0 The .Fn AG_GraphVertexNew function creates a new vertex in the specified graph. .Fa userPtr is an optional user pointer to associate with the vertex. .Pp .Fn AG_GraphVertexFind returns the vertex matching the specified user pointer, or NULL if no match exists. .Pp .Fn AG_GraphVertexLabel sets the text label associated with a vertex. .Pp .Fn AG_GraphVertexColorLabel sets the color of the text label. .Fn AG_GraphVertexColorBG sets the background color for the node item. .Pp .Fn AG_GraphVertexSize changes the default size of the node item. .Pp .Fn AG_GraphVertexPosition moves the node item to the given position in the view. .Pp .Fn AG_GraphVertexPopupMenu arranges for the given popup menu to be displayed when the user right clicks on the vertex. .Sh EDGES .nr nS 1 .Ft "AG_GraphEdge *" .Fn AG_GraphEdgeNew "AG_Graph *graph" "AG_GraphVertex *v1" "AG_GraphVertex *v2" "void *userPtr" .Pp .Ft "AG_GraphEdge *" .Fn AG_DirectedGraphEdgeNew "AG_Graph *graph" "AG_GraphVertex *v1" "AG_GraphVertex *v2" "void *userPtr" .Pp .Ft "AG_GraphEdge *" .Fn AG_GraphEdgeFind "AG_Graph *graph" "void *userPtr" .Pp .Ft "void" .Fn AG_GraphEdgeLabel "AG_GraphEdge *edge" "const char *format" "..." .Pp .Ft "void" .Fn AG_GraphEdgeLabelS "AG_GraphEdge *edge" "const char *text" .Pp .Ft "void" .Fn AG_GraphEdgeColorLabel "AG_GraphEdge *edge" "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft "void" .Fn AG_GraphEdgeColor "AG_GraphEdge *edge" "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft "void" .Fn AG_GraphEdgePopupMenu "AG_GraphEdge *edge" "AG_PopupMenu *menu" .Pp .nr nS 0 The .Fn AG_GraphEdgeNew function creates a new edge connecting vertices .Fa v1 and .Fa v2 . If the two vertices are already connected by an edge, the function fails and returns NULL. .Fa userPtr is an optional user pointer to associated with the edge. .Pp .Fn AG_DirectedGraphEdgeNew identical to AG_GraphEdgeNew, but the edge is marked as being directed. Directed graph edges are assumed to point "to" .Fa v2. Directed graph edges are displayed with an arrowhead pointing towards .Fa v2 (only on systems with floating point support). .Pp .Fn AG_GraphEdgeFind returns the vertex matching the specified user pointer, or NULL if no match exists. .Pp The .Fn AG_GraphEdgeLabel sets the text label to display along the given edge. .Pp .Fn AG_GraphEdgeColorLabel sets the color of the text label. .Fn AG_GraphEdgeColor sets the color of the line representing the edge. .Fn AG_GraphEdgePopupMenu arranges for the given popup menu to be displayed when the user right clicks on the edge. .Sh EVENTS The .Nm widget generates the following events: .Pp .Bl -tag -compact -width 2n .It Fn graph-vertex-selected "AG_GraphVertex *vtx" The specified vertex is now selected. .It Fn graph-vertex-unselected "AG_GraphVertex *vtx" The specified vertex is no longer selected. .It Fn graph-edge-selected "AG_GraphEdge *edge" The specified edge is now selected. .It Fn graph-edge-unselected "AG_GraphEdge *edge" The specified edge is no longer selected. .El .Sh STRUCTURE DATA For the .Ft AG_Graph object: .Pp .Bl -tag -compact -width "int xOffs, yOffs " .It Ft int xOffs, yOffs Display offset in pixels. .It Ft Uint nVertices Vertex count (read-only). .It Ft Uint nEdges Edge count (read-only) .It Ft TAILQ vertices List of .Ft AG_GraphVertex items (read-only) .It Ft TAILQ edges List of .Ft AG_GraphEdge items (read-only). .El .Pp For the .Ft AG_GraphVertex structure: .Pp .Bl -tag -compact -width "void *userPtr " .It Ft int x, y Pixel coordinates of vertex in the graph. .It Ft Uint w, h Bounding box for graphical representation of the vertex. .It Ft void *userPtr Generic user pointer. .It Ft TAILQ edges List of .Xr AG_GraphEdge 3 objects connected to this vertex. .El .Pp For the .Ft AG_GraphEdge structure: .Pp .Bl -tag -compact -width "AG_GraphVertex *v1, *v2 " .It Ft AG_GraphVertex *v1, *v2 Vertices connected by edge .It Ft void *userPtr User pointer .It Ft enum ag_graph_edge_type type Either AG_GRAPH_EDGE_UNDIRECTED or AG_GRAPH_EDGE_DIRECTED to indicate an undirected or directed edge respectively .El .Sh SEE ALSO .Xr AG_Intro 3 , .Xr AG_Menu 3 , .Xr AG_Widget 3 , .Xr AG_Window 3 .Sh HISTORY The .Nm widget first appeared in Agar 1.3.4. Support for directed graphs appeared in Agar 1.6.0.