.\" Copyright (c) 2008-2022 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 21, 2022 .Dt VG_VIEW 3 .Os Agar 1.7 .Sh NAME .Nm VG_View .Nd agar VG visualization widget .Sh SYNOPSIS .Bd -literal #include #include #include .Ed .Sh DESCRIPTION .\" IMAGE(/widgets/VG_View.png, "The VG_View widget") The .Nm widget displays a .Xr VG 3 vector graphics object. .Nm also provides a simple "tool" registration interface which allows modular editors to be implemented quickly. .Sh INHERITANCE HIERARCHY .Xr AG_Object 3 -> .Xr AG_Widget 3 -> .Nm . .Sh INTERFACE .nr nS 1 .Ft "VG_View *" .Fn VG_ViewNew "void *parent" "VG *vg" "Uint flags" .Pp .Ft "void" .Fn VG_ViewSetVG "VG_View *vv" "VG *vg" .Pp .Ft "void" .Fn VG_ViewSetScale "VG_View *vv" "float c" .Pp .Ft "void" .Fn VG_ViewSetScalePreset "VG_View *vv" "int index" .Pp .Ft "void" .Fn VG_ViewSetScaleMin "VG_View *vv" "float c" .Pp .Ft "void" .Fn VG_ViewSetScaleMax "VG_View *vv" "float c" .Pp .Ft "void" .Fn VG_ViewSetSnapMode "VG_View *vv" "enum vg_snap_mode mode" .Pp .Ft "void" .Fn VG_ViewSetGrid "VG_View *vv" "int gridID" "VG_GridType type" "int interval" "VG_Color color" .Pp .Ft "Uint" .Fn VG_AddEditArea "VG_View *vv" "void *widget" .Pp .Ft "void" .Fn VG_ClearEditAreas "VG_View *vv" .Pp .Ft "void" .Fn VG_Status "VG_View *vv" "const char *format" "..." .Pp .Ft "void" .Fn VG_StatusS "VG_View *vv" "const char *text" .Pp .Ft "void" .Fn VG_EditNode "VG_View *vv" "Uint editArea" "VG_Node *vn" .Pp .Ft "void" .Fn VG_ApplyConstraints "VG_View *vv" "VG_Vector *pos" .Pp .Ft "void" .Fn VG_GetVGCoords "VG_View *vv" "int x" "int y" "VG_Vector *v" .Pp .Ft "void" .Fn VG_GetVGCoordsFlt "VG_View *vv" "VG_Vector pos" "VG_Vector *v" .Pp .Ft "void" .Fn VG_GetViewCoords "VG_View *vv" "VG_Vector v" "int *x" "int *y" .Pp .Ft "void" .Fn VG_GetViewCoordsFlt "VG_View *vv" "VG_Vector v" "float *x" "float *y" .Pp .Ft "void *" .Fn VG_Nearest "VG_View *vv" "VG_Vector vPos" .Pp .Ft "void *" .Fn VG_NearestPoint "VG_View *vv" "VG_Vector vPos" "void *ignore" .Pp .nr nS 0 The .Fn VG_ViewNew function allocates, initializes, and attaches a .Nm widget displaying the specified .Fa vg object. Acceptable .Fa flags include: .Bl -tag -width "VG_VIEW_CONSTRUCTION " .It VG_VIEW_GRID Display the grid; see .Fn VG_ViewSetGrid . .It VG_VIEW_EXTENTS Display the bounding boxes of the VG elements. This option is only implemented in debug mode. .It VG_VIEW_DISABLE_BG Disable the VG-specific background. .It 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. .It VG_VIEW_HFILL Expand horizontally in parent container. .It VG_VIEW_VFILL Expand vertically in parent container. .It VG_VIEW_EXPAND Shorthand for .Dv VG_VIEW_HFILL | VG_VIEW_VFILL . .El .Pp The VG object displayed can be changed at runtime with .Fn VG_ViewSetVG . If a VG tool (see .Sx TOOL INTERFACE ) is currently in use, changing the VG has the side effect of deselecting the tool. .Pp .Fn VG_ViewSetScale sets the scaling factor at which the vector scene will be displayed. The .Fn VG_ViewSetScalePreset variant accepts an index into the table of preset scaling factors as an argument (0..nScaleFactors). .Fn VG_ViewSetScaleMin and .Fn VG_ViewSetScaleMax specify the range of scaling factors the user is allowed to select. .Pp .Fn VG_ViewSetSnapMode selects the snapping constraint mode for the cursor. Acceptable values of .Fa mode include: .Pp .Bl -tag -compact -width "VG_FREE_POSITIONING " .It VG_FREE_POSITIONING No snapping constraint. .It VG_GRID Snap cursor to active grid. .It VG_ENDPOINT Snap to line endpoints. .It VG_CLOSEST_POINT Snap to closest point on nearest entity. .El .Pp .Fn VG_ViewSetGrid either creates a new grid, or changes the parameters of an existing grid .Fa gridID . The .Fa interval argument specifies the interval of the grid (in pixels). .Fa color sets the color which will be used to display the grid. .Fa type sets the style of rendering: .Pp .Bl -tag -compact -width "VG_GRID_POINTS " .It VG_GRID_POINTS Draw the grid as an array of points. .It VG_GRID_LINES Draw the grid using lines only. .El .Pp The .Fn VG_AddEditArea routine indicates a container widget which the .Nm should use to display tool-specific GUI elements. Whenever a tool (or a .Ft VG_Node ) is selected, its optional .Fn edit operation may create one or more GUI elements bound to various parameters. Multiple edition areas are allowed. .Fn VG_AddEditArea returns an index into the .Va editAreas array of .Nm . .Pp .Fn VG_ClearEditAreas destroys all widgets currently attached to the container(s) registered by .Fn VG_AddEditArea . .Pp .Fn VG_Status sets the text displayed by any .Xr AG_Statusbar 3 associated with the .Nm . .Pp .Fn VG_EditNode populates the specified edit area (index as returned by .Fn VG_AddEditArea ) with the controls returned by the .Fn edit operation of the specified .Ft VG_Node . .Fn VG_EditNode is automatically invoked by the stock selection tool .Va vgSelectTool when an entity is selected. .Pp The .Fn VG_ApplyConstraints routine applies effective position constraints (e.g., the snapping mode given by .Fn VG_ViewSetSnapMode ) on the given position, overwriting the contents of .Fa pos with the result. .Pp The .Fn VG_GetVGCoords routine converts the given integer coordinates (relative to the .Nm widget), into real coordinates in the VG scene. The .Fn VG_GetVGCoordsFlt variant accepts view coordinates in floating-point format. .Pp Conversely, .Fn VG_GetViewCoords and .Fn VG_GetViewCoordsFlt convert the specified real VG coordinates .Fa v to integer (or floating-point) view coordinates into .Fa x , .Fa y . .Pp The .Fn VG_Nearest routine returns a pointer to the entity nearest to the given coordinates. The .Fn VG_NearestPoint variant searches the scene for a point which intersects a VG element and is closest to the specified VG coordinates .Fa vPos . .Fa ignore is an optional pointer to an element which should be ignored in the computation. .Sh RENDERING ROUTINES The .Fn draw operation of most .Xr VG 3 elements will use the standard GUI rendering routines (see .Xr AG_Widget 3 , .Dq RENDERING AND PRIMITIVES ) , or perform direct OpenGL calls. Vector coordinates are typically translated to view coordinates using .Fn VG_GetViewCoords . The following rendering routines are specific to .Nm and must be invoked from .Fn VG_Node .Fn draw context. .Pp .nr nS 1 .Ft "void" .Fn VG_DrawSurface "VG_View *vv" "int x" "int y" "float degs" "int su" .Pp .nr nS 0 The .Fn VG_DrawSurface routine renders the contents of a surface at view coordinates .Fa x , .Fa y in pixels, rotated clockwise by .Fa degs degrees. The surface .Fa su must have been previously mapped to the .Nm object (see .Xr AG_WidgetMapSurface 3 ) . .\" MANLINK(VG_ToolOps) .Sh TOOL INTERFACE .nr nS 1 .Ft "VG_Tool *" .Fn VG_ViewRegTool "VG_View *vv" "const VG_ToolOps *classInfo" "void *userPtr" .Pp .Ft "void" .Fn VG_ViewSelectTool "VG_View *vv" "VG_Tool *tool" "void *userPtr" .Pp .Ft "VG_Tool *" .Fn VG_ViewFindTool "VG_View *vv" "const char *name" .Pp .Ft "VG_Tool *" .Fn VG_ViewFindToolByOps "VG_View *vv" "const VG_ToolOps *classInfo" .Pp .Ft "void" .Fn VG_ViewSetDefaultTool "VG_View *vv" "VG_Tool *tool" .Pp .nr nS 0 Implementing an editor using .Nm is typically done by registering a set of tools which are invoked using a callback-style interface. .Pp .Fn VG_ViewRegTool registers a new tool class (described by the provided .Fa classInfo structure) with the .Nm . .Fa userPtr is an optional user pointer which will be passed to the tool. The .Ft VG_ToolOps structure is as follows. Any of the callback functions may be set to NULL. .Bd -literal .\" SYNTAX(c) 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; .Ed .Pp The .Fa name field specifies a short name for the tool. .Fa desc is a short description of the purpose of the tool. .Fa icon is an optional .Xr AG_StaticIcon 3 for the GUI. .Pp The .Fa len value specifies the size, in bytes, of the structure which will be used to describe an instance of the tool (either .Ft VG_Tool or a derivative of it). .Pp Acceptable .Fa flags options include: .Bl -tag -width "VG_MOUSEMOTION_NOSNAP " .It VG_NOSNAP Disable position constraints in any context. .It VG_MOUSEMOTION_NOSNAP Disable position constraints when communicating mouse motion events to the tool. .It VG_BUTTONUP_NOSNAP Disable position constraints when communicating mouse button release events to the tool. .It VG_BUTTONDOWN_NOSNAP Disable position constraints when communicating mouse button press events to the tool. .It VG_BUTTON_NOSNAP Implies .Dv VG_BUTTONUP_NOSNAP and .Dv VG_BUTTONDOWN_NOSNAP .It VG_NOEDITCLEAR When the tool is selected, do not perform automatic removal of GUI elements in the containers specified by .Fn VG_AddEditArea . .El .Pp The .Fn init callback initializes an instance of the tool. .Fn destroy releases resources allocated by an instance of the tool. .Pp The .Fn edit operation creates one or more GUI elements, typically used to set various tool-specific options. The object returned by .Fn edit should be a derivative of .Xr AG_Widget 3 . .Pp The .Fn predraw and .Fn postdraw callbacks are invoked prior to, and after rendering of the scene by the .Nm . Typically, .Fn postdraw is used to render specialized cursors or provide visual feedback to the user in a manner specific to the tool. .Pp .Fn selected and .Fn deselected are invoked whenever the tool is, respectively, selected or deselected by the user. .Pp Low-level mouse and keyboard events can be handled directly by the tool using .Fn mousemotion .Fn mousebuttondown , .Fn mousebuttonup , .Fn keydown and .Fn keyup . The coordinates passed to mouse-related callbacks are subject to the current position constraints, unless disabled by one of the .Dv VG_*_NOSNAP flags in the .Fa flags field. .Sh SEE ALSO .Xr VG 3 .Sh HISTORY The .Nm interface first appeared in Agar 1.3.0, and was first documented in Agar 1.3.3.