FreeBSD Manual Pages
VG_VIEW(3) Library Functions Manual VG_VIEW(3) 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 modu- lar 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 construc- tion", such as the points used to construct a polygon. The exact interpretation of this set- ting 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 in- dex into the table of preset scaling factors as an argument (0..nScale- Factors). 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 cur- sor. 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 inter- val 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 cre- ate 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 con- tainer(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 con- straints (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 co- ordinates 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 speci- fied 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 trans- lated to view coordinates using VG_GetViewCoords(). The following ren- dering 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 deriv- ative 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 auto- matic removal of GUI elements in the containers specified by VG_AddEditArea(). The init() callback initializes an instance of the tool. destroy() re- leases 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, respec- tively, 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 docu- mented in Agar 1.3.3. Agar 1.7 December 21, 2022 VG_VIEW(3)
NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INTERFACE | RENDERING ROUTINES | TOOL INTERFACE | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=VG_View&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>