|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.|
The VG_ViewNew() function allocates, initializes, and attaches a VG_View widget displaying the specified vg object. Acceptable flags include:
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_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:
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.
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.
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)).
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.
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:
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.
|The VG_View interface first appeared in Agar 1.3, and was first documented in Agar 1.3.3.|