<-- Back to AG_Intro.3

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.

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 (equivalent to invoking AG_ExpandHoriz(3)).
VG_VIEW_VFILL	Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
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)

void VG_ViewSelectToolEv (AG_Event *event)

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.

HISTORY

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