NAME

VG_View — agar VG visualization widget

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>
#include <agar/vg.h>

DESCRIPTION

The VG_View widget displays a VG(3) vector graphics object. VG_View also provides a simple "tool" registration interface which allows modular editors to be implemented quickly.

INHERITANCE HIERARCHY

AG_Object(3) -> AG_Widget(3) -> VG_View.

INTERFACE

VG_View *
VG_ViewNew(void *parent, VG *vg, Uint flags);

void
VG_ViewSetVG(VG_View *vv, VG *vg);

void
VG_ViewSetScale(VG_View *vv, float c);

void
VG_ViewSetScalePreset(VG_View *vv, int index);

void
VG_ViewSetScaleMin(VG_View *vv, float c);

void
VG_ViewSetScaleMax(VG_View *vv, float c);

void
VG_ViewSetSnapMode(VG_View *vv, enum vg_snap_mode mode);

void
VG_ViewSetGrid(VG_View *vv, int gridID, VG_GridType type, int interval, VG_Color color);

Uint
VG_AddEditArea(VG_View *vv, void *widget);

void
VG_ClearEditAreas(VG_View *vv);

void
VG_Status(VG_View *vv, const char *format, ...);

void
VG_StatusS(VG_View *vv, const char *text);

void
VG_EditNode(VG_View *vv, Uint editArea, VG_Node *vn);

void
VG_ApplyConstraints(VG_View *vv, VG_Vector *pos);

void
VG_GetVGCoords(VG_View *vv, int x, int y, VG_Vector *v);

void
VG_GetVGCoordsFlt(VG_View *vv, VG_Vector pos, VG_Vector *v);

void
VG_GetViewCoords(VG_View *vv, VG_Vector v, int *x, int *y);

void
VG_GetViewCoordsFlt(VG_View *vv, VG_Vector v, float *x, float *y);

void *
VG_Nearest(VG_View *vv, VG_Vector vPos);

void *
VG_NearestPoint(VG_View *vv, VG_Vector vPos, void *ignore);

The VG_ViewNew() function allocates, initializes, and attaches a VG_View widget displaying the specified vg object. Acceptable flags include:

VG_VIEW_GRID

Display the grid; see VG_ViewSetGrid().

VG_VIEW_EXTENTS

Display the bounding boxes of the VG elements. This option is only implemented in debug mode.

VG_VIEW_DISABLE_BG

Disable the VG-specific background.

VG_VIEW_CONSTRUCTION

Display VG elements marked as "for construction", such as the points used to construct a polygon. The exact interpretation of this setting is element-specific.

VG_VIEW_HFILL

Expand horizontally in parent container.

VG_VIEW_VFILL

Expand vertically in parent container.

VG_VIEW_EXPAND

Shorthand for VG_VIEW_HFILL | VG_VIEW_VFILL.

The VG object displayed can be changed at runtime with VG_ViewSetVG(). If a VG tool (see TOOL INTERFACE) is currently in use, changing the VG has the side effect of deselecting the tool.

VG_ViewSetScale() sets the scaling factor at which the vector scene will be displayed. The VG_ViewSetScalePreset() variant accepts an index into the table of preset scaling factors as an argument (0..nScaleFactors). VG_ViewSetScaleMin() and VG_ViewSetScaleMax() specify the range of scaling factors the user is allowed to select.

VG_ViewSetSnapMode() selects the snapping constraint mode for the cursor. Acceptable values of mode include:

VG_FREE_POSITIONING

No snapping constraint.

VG_GRID

Snap cursor to active grid.

VG_ENDPOINT

Snap to line endpoints.

VG_CLOSEST_POINT

Snap to closest point on nearest entity.

VG_ViewSetGrid() either creates a new grid, or changes the parameters of an existing grid gridID. The interval argument specifies the interval of the grid (in pixels). color sets the color which will be used to display the grid. type sets the style of rendering:

VG_GRID_POINTS

Draw the grid as an array of points.

VG_GRID_LINES

Draw the grid using lines only.

The VG_AddEditArea() routine indicates a container widget which the VG_View should use to display tool-specific GUI elements. Whenever a tool (or a VG_Node) is selected, its optional edit() operation may create one or more GUI elements bound to various parameters. Multiple edition areas are allowed. VG_AddEditArea() returns an index into the editAreas array of VG_View.

VG_ClearEditAreas() destroys all widgets currently attached to the container(s) registered by VG_AddEditArea().

VG_Status() sets the text displayed by any AG_Statusbar(3) associated with the VG_View.

VG_EditNode() populates the specified edit area (index as returned by VG_AddEditArea()) with the controls returned by the edit() operation of the specified VG_Node. VG_EditNode() is automatically invoked by the stock selection tool vgSelectTool when an entity is selected.

The VG_ApplyConstraints() routine applies effective position constraints (e.g., the snapping mode given by VG_ViewSetSnapMode()) on the given position, overwriting the contents of pos with the result.

The VG_GetVGCoords() routine converts the given integer coordinates (relative to the VG_View widget), into real coordinates in the VG scene. The VG_GetVGCoordsFlt() variant accepts view coordinates in floating-point format.

Conversely, VG_GetViewCoords() and VG_GetViewCoordsFlt() convert the specified real VG coordinates v to integer (or floating-point) view coordinates into x, y.

The VG_Nearest() routine returns a pointer to the entity nearest to the given coordinates. The VG_NearestPoint() variant searches the scene for a point which intersects a VG element and is closest to the specified VG coordinates vPos. ignore is an optional pointer to an element which should be ignored in the computation.

RENDERING ROUTINES

The draw() operation of most VG(3) elements will use the standard GUI rendering routines (see AG_Widget(3), “RENDERING AND PRIMITIVES”), or perform direct OpenGL calls. Vector coordinates are typically translated to view coordinates using VG_GetViewCoords(). The following rendering routines are specific to VG_View and must be invoked from VG_Node() draw() context.

void
VG_DrawSurface(VG_View *vv, int x, int y, float degs, int su);

The VG_DrawSurface() routine renders the contents of a surface at view coordinates x, y in pixels, rotated clockwise by degs degrees. The surface su must have been previously mapped to the VG_View object (see AG_WidgetMapSurface(3)).

TOOL INTERFACE

VG_Tool *
VG_ViewRegTool(VG_View *vv, const VG_ToolOps *classInfo, void *userPtr);

void
VG_ViewSelectTool(VG_View *vv, VG_Tool *tool, void *userPtr);

VG_Tool *
VG_ViewFindTool(VG_View *vv, const char *name);

VG_Tool *
VG_ViewFindToolByOps(VG_View *vv, const VG_ToolOps *classInfo);

void
VG_ViewSetDefaultTool(VG_View *vv, VG_Tool *tool);

Implementing an editor using VG_View is typically done by registering a set of tools which are invoked using a callback-style interface.

VG_ViewRegTool() registers a new tool class (described by the provided classInfo structure) with the VG_View. userPtr is an optional user pointer which will be passed to the tool. The VG_ToolOps structure is as follows. Any of the callback functions may be set to NULL.

typedef struct vg_tool_ops {
	const char *name;          /* Tool name */
	const char *desc;          /* Optional description */
	AG_StaticIcon *icon;       /* Optional GUI icon */
	AG_Size len;               /* Size of instance structure */
	Uint flags;                /* Options (see below) */

	void (*init)(void *);
	void (*destroy)(void *);
	void *(*edit)(void *, struct vg_view *);
	void (*predraw)(void *, struct vg_view *);
	void (*postdraw)(void *, struct vg_view *);
	void (*selected)(void *, struct vg_view *);
	void (*deselected)(void *, struct vg_view *);

	int (*mousemotion)(void *, VG_Vector vPos, VG_Vector vRel,
	                   int buttons);
	int (*mousebuttondown)(void *, VG_Vector vPos, int button);
	int (*mousebuttonup)(void *, VG_Vector vPos, int button);
	int (*keydown)(void *, int ksym, int kmod, Uint32 unicode);
	int (*keyup)(void *, int ksym, int kmod, Uint32 unicode);
} VG_ToolOps;

The name field specifies a short name for the tool. desc is a short description of the purpose of the tool. icon is an optional AG_StaticIcon(3) for the GUI.

The len value specifies the size, in bytes, of the structure which will be used to describe an instance of the tool (either VG_Tool or a derivative of it).

Acceptable flags options include:

VG_NOSNAP

Disable position constraints in any context.

VG_MOUSEMOTION_NOSNAP

Disable position constraints when communicating mouse motion events to the tool.

VG_BUTTONUP_NOSNAP

Disable position constraints when communicating mouse button release events to the tool.

VG_BUTTONDOWN_NOSNAP

Disable position constraints when communicating mouse button press events to the tool.

VG_BUTTON_NOSNAP

Implies VG_BUTTONUP_NOSNAP and VG_BUTTONDOWN_NOSNAP

VG_NOEDITCLEAR

When the tool is selected, do not perform automatic removal of GUI elements in the containers specified by VG_AddEditArea().

The init() callback initializes an instance of the tool. destroy() releases resources allocated by an instance of the tool.

The edit() operation creates one or more GUI elements, typically used to set various tool-specific options. The object returned by edit() should be a derivative of AG_Widget(3).

The predraw() and postdraw() callbacks are invoked prior to, and after rendering of the scene by the VG_View. Typically, postdraw() is used to render specialized cursors or provide visual feedback to the user in a manner specific to the tool.

selected() and deselected() are invoked whenever the tool is, respectively, selected or deselected by the user.

Low-level mouse and keyboard events can be handled directly by the tool using mousemotion() mousebuttondown(), mousebuttonup(), keydown() and keyup(). The coordinates passed to mouse-related callbacks are subject to the current position constraints, unless disabled by one of the VG_*_NOSNAP flags in the flags field.

SEE ALSO

VG(3)

HISTORY

The VG_View interface first appeared in Agar 1.3.0, and was first documented in Agar 1.3.3.