include/graphviz/gvc.h

0001 /**
0002  * @file
0003  * @brief Graphviz context library
0004  * @ingroup gvc_api
0005  *
0006  * **libgvc** provides a context for applications wishing to manipulate
0007  * and render graphs. It provides command line parsing,
0008  * common rendering code, and a plugin mechanism for renderers.
0009  *
0010  * [man 3 gvc](https://graphviz.org/pdf/gvc.3.pdf)
0011  *
0012  */
0013
0014 /*************************************************************************
0015  * Copyright (c) 2011 AT&T Intellectual Property
0016  * All rights reserved. This program and the accompanying materials
0017  * are made available under the terms of the Eclipse Public License v1.0
0018  * which accompanies this distribution, and is available at
0019  * https://www.eclipse.org/legal/epl-v10.html
0020  *
0021  * Contributors: Details at https://graphviz.org
0022  *************************************************************************/
0023
0024 #pragma once
0025
0026 #include <stdbool.h>
0027 #include <stddef.h>
0028
0029 #include "types.h"
0030 #include "gvplugin.h"
0031
0032 #ifdef __cplusplus
0033 extern "C" {
0034 #endif
0035
0036 #ifdef GVDLL
0037 #ifdef GVC_EXPORTS
0038 #define GVC_API __declspec(dllexport)
0039 #else
0040 #define GVC_API __declspec(dllimport)
0041 #endif
0042 #endif
0043
0044 #ifndef GVC_API
0045 #define GVC_API /* nothing */
0046 #endif
0047
0048 /// @defgroup gvc_api Graphviz context library (GVC) API
0049 /// @ingroup public_apis
0050 /// @{
0051
0052 #define LAYOUT_DONE(g) (agbindrec(g, "Agraphinfo_t", 0, true) && GD_drawing(g))
0053
0054 /* misc */
0055 /* FIXME - this needs eliminating or renaming */
0056 GVC_API void gvToggle(int);
0057
0058 /* set up a graphviz context */
0059 GVC_API GVC_t *gvNEWcontext(const lt_symlist_t *builtins, int demand_loading);
0060
0061 /*  set up a graphviz context - and init graph - retaining old API */
0062 GVC_API GVC_t *gvContext(void);
0063 /*  set up a graphviz context - and init graph - with builtins */
0064 GVC_API GVC_t *gvContextPlugins(const lt_symlist_t *builtins, int demand_loading);
0065
0066 /* get information associated with a graphviz context */
0067 GVC_API char **gvcInfo(GVC_t*);
0068 GVC_API char *gvcVersion(GVC_t*);
0069 GVC_API char *gvcBuildDate(GVC_t*);
0070
0071 /* parse command line args - minimally argv[0] sets layout engine */
0072 GVC_API int gvParseArgs(GVC_t *gvc, int argc, char **argv);
0073 GVC_API graph_t *gvNextInputGraph(GVC_t *gvc);
0074 GVC_API graph_t *gvPluginsGraph(GVC_t *gvc);
0075
0076 /* Compute a layout using a specified engine */
0077 GVC_API int gvLayout(GVC_t *gvc, graph_t *g, const char *engine);
0078
0079 /* Compute a layout using layout engine from command line args */
0080 GVC_API int gvLayoutJobs(GVC_t *gvc, graph_t *g);
0081
0082 /* Check if a layout has been done */
0083 GVC_API bool gvLayoutDone(graph_t *g);
0084
0085 /* Render layout into string attributes of the graph */
0086 GVC_API void attach_attrs(graph_t *g);
0087
0088 /* Render layout in a specified format to an open FILE */
0089 GVC_API int gvRender(GVC_t *gvc, graph_t *g, const char *format, FILE *out);
0090
0091 /* Render layout in a specified format to a file with the given name */
0092 GVC_API int gvRenderFilename(GVC_t *gvc, graph_t *g, const char *format, const char *filename);
0093
0094 /* Render layout in a specified format to an GVC_APIal context */
0095 GVC_API int gvRenderContext(GVC_t *gvc, graph_t *g, const char *format, void *context);
0096
0097 /* Render layout in a specified format to a malloc'ed string */
0098 GVC_API int gvRenderData(GVC_t *gvc, graph_t *g, const char *format,
0099                          char **result, size_t *length);
0100
0101 /* Free memory allocated and pointed to by *result in gvRenderData */
0102 GVC_API void gvFreeRenderData (char* data);
0103
0104 /* Render layout according to -T and -o options found by gvParseArgs */
0105 GVC_API int gvRenderJobs(GVC_t *gvc, graph_t *g);
0106
0107 /* Clean up layout data structures - layouts are not nestable (yet) */
0108 GVC_API int gvFreeLayout(GVC_t *gvc, graph_t *g);
0109
0110 /* Clean up graphviz context */
0111 GVC_API void gvFinalize(GVC_t *gvc);
0112 GVC_API int gvFreeContext(GVC_t *gvc);
0113
0114 /* Return list of plugins of type kind.
0115  * kind would normally be "render" "layout" "textlayout" "device" "loadimage"
0116  * The size of the list is stored in sz.
0117  * The caller is responsible for freeing the storage. This involves
0118  * freeing each item, then the list.
0119  * Returns NULL on error, or if there are no plugins.
0120  * In the former case, sz is unchanged; in the latter, sz = 0.
0121  */
0122 GVC_API char **gvPluginList(GVC_t *gvc, const char *kind, int *sz);
0123
0124 /** Add a library from your user application
0125  * @param gvc Graphviz context to add library to
0126  * @param lib library to add
0127  */
0128 GVC_API void gvAddLibrary(GVC_t *gvc, gvplugin_library_t *lib);
0129
0130 /** Perform a Transitive Reduction on a graph
0131  * @param g  graph to be transformed.
0132  */
0133 GVC_API int gvToolTred(graph_t *g);
0134
0135 /// @}
0136
0137 #undef GVC_API
0138
0139 #ifdef __cplusplus
0140 }
0141 #endif