.\" Copyright (c) 2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" 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 June 26, 2007
.Dt AG_GRAPH 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Graph
.Nd agar graph view widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
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.
.Pp
The
.Nm
widget will attempt to position the vertices in the view in order to minimize
the number of edges crossing each other, but this is a NP-complete problem.
The user can also move vertices manually, or they can be placed
programmatically.
.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.
The
.Fa flags
may include:
.Pp
.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 .
.El
.Pp
The
.Fn AG_GraphSizeHint
function requests an initial widget size in pixels.
.Pp
.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 *fmt" "..."
.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
The
.Fn AG_GraphVertexLabel
function changes the text label of the given vertex using the specified
format string.
.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_GraphEdgeFind "AG_Graph *graph" "void *userPtr"
.Pp
.Ft "void"
.Fn AG_GraphEdgeLabel "AG_GraphEdge *edge" "const char *fmt" "..."
.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_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 reacts to the following events:
.Pp
.Bl -tag -compact -width 25n
.It window-keydown
Pan (direction keys), or center around origin (0 key).
.It window-mousebuttondown
Select vertices or edges and start dragging (left), start panning (middle)
or trigger the popup menu (right).
.It window-keyup
Stop dragging/panning actions in progress.
.It window-mousemotion
Pan or move selected vertices.
.El
.Pp
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
.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.