.\" .\" Copyright (c) 2010-2022 Julien Nadeau Carriere .\" .\" 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 SK_VIEW 3 .Os Agar 1.7 .Sh NAME .Nm SK_View .Nd Editor/display widget for Agar dimensioned 2D sketches .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION The .Nm widget displays a .Xr SK 3 sketch, and allows edition facilities to be implemented using a tool registration interface. .Sh INHERITANCE HIERARCHY .Xr AG_Object 3 -> .Xr AG_Widget 3 -> .Nm . .Sh INITIALIZATION .nr nS 1 .Ft "SK_View *" .Fn SK_ViewNew "AG_Widget *parent" "SK *sk" "Uint flags" .Pp .Ft void .Fn SK_ViewZoom "SK_View *skv" "M_Real factor" .Pp .nr nS 0 The .Fn SK_ViewNew function allocates, initializes, and attaches a .Nm widget. Acceptable .Fa flags options include: .Bl -tag -width "SK_VIEW_EXPAND " .It SK_VIEW_HFILL Expand horizontally in parent container. .It SK_VIEW_VFILL Expand vertically in parent container. .It SK_VIEW_EXPAND Shorthand for .Dv SK_VIEW_HFILL | SK_VIEW_VFILL . .El .Pp The .Fn SK_ViewZoom function sets the display scaling factor (1.0 = 100%). .Sh TOOL SYSTEM .nr nS 1 .Ft "SK_Tool *" .Fn SK_ViewRegTool "SK_View *skv" "const SK_ToolOps *ops" "void *arg" .Pp .Ft "void" .Fn SK_ViewSelectTool "SK_View *skv" "SK_Tool *tool" "void *arg" .Pp .Ft "SK_Tool *" .Fn SK_ViewFindTool "SK_View *skv" "const char *name" .Pp .Ft "SK_Tool *" .Fn SK_ViewFindToolByOps "SK_View *skv" "const SK_ToolOps *ops" .Pp .Ft void .Fn SK_ViewSetDefaultTool "SK_View *skv" "SK_Tool *tool" .Pp .nr nS 0 The .Fn SK_ViewRegTool function registers a new tool class described by the .Fa ops structure, which is defined as: .Bd -literal .\" SYNTAX(c) typedef struct sk_tool_ops { const char *name; const char *desc; struct ag_static_icon *icon; AG_Size len; Uint flags; #define SK_MOUSEMOTION_NOSNAP 0x01 /* Ignore snapping in mousemotion */ #define SK_BUTTONUP_NOSNAP 0x02 /* Ignore snapping in buttonup */ #define SK_BUTTONDOWN_NOSNAP 0x04 /* Ignore snapping in buttondown */ #define SK_BUTTON_NOSNAP (SK_BUTTONUP_NOSNAP|SK_BUTTONDOWN_NOSNAP) #define SK_NOSNAP (SK_BUTTON_NOSNAP|SK_MOUSEMOTION_NOSNAP) void (*init)(void *tool); void (*destroy)(void *tool); void (*edit)(void *tool, void *editBox); int (*mousemotion)(void *tool, M_Vector3 pos, M_Vector3 vel, int btn); int (*mousebuttondown)(void *tool, M_Vector3 pos, int btn); int (*mousebuttonup)(void *tool, M_Vector3 pos, int btn); int (*keydown)(void *tool, int ksym, int kmod); int (*keyup)(void *tool, int ksym, int kmod); } SK_ToolOps; .Ed .Pp The .Fa name field is a unique name identifier for the tool. .Fa desc is a short description string. .Fa icon is an optional icon or NULL. .Fa len is the size of the structure describing an instance of this tool class. .Pp The .Fn init operation initializes a new instance of a tool. .Fn destroy should release all resources allocated by a tool instance. The optional .Fn edit operation is expected to attach arbitrary widgets to .Fa editBox , for purposes of editing tool parameters. .Pp The low-level input device events processed by the .Nm widget are forwarded to the handler functions .Fn mousemotion , .Fn mousebuttondown , .Fn mousebuttonup , .Fn keydown and .Fn keyup . They should return 1 if some action has resulted from the event, or 0 otherwise. The coordinates passed to the .Fn mouse* handlers are translated to actual .Xr SK 3 coordinates. .Pp The .Fn SK_ViewSelectTool function selects .Fa tool as the active tool instance. The .Fa arg argument is an optional user pointer passed to the tool instance. .Pp The .Fn SK_ViewFindTool function looks up a tool instance by name. .Fn SK_ViewFindToolByOps looks up a tool instance by class. Both functions return NULL if no match was found. .Pp .Fn SK_ViewSetDefaultTool configures a tool to be active by default when the .Nm is initially created. This is often a "select" type tool. .Sh MISCELLANEOUS .nr nS 1 .Ft "SK_Point *" .Fn SK_ViewOverPoint "SK_View *skv" "M_Vector3 *pos" "M_Vector3 *vC" "void *ignoreNode" .Pp .Ft "void" .Fn SK_ViewSetNodeData "SK_View *skv" "SK_Node *node" "void *pData" .Pp .Ft "void *" .Fn SK_ViewGetNodeData "SK_View *skv" "SK_Node *node" .Pp .nr nS 0 The .Fn SK_ViewOverPoint function performs a proximity query for the given position .Fa pos , with respect to all point entities in the sketch. This function is a convenient wrapper around .Xr SK_ProximitySearch 3 . The closest point is returned into the .Fa vC argument. The optional .Fa ignore argument specifies a pointer to a node that should be ignored in the search. .Pp The .Fn SK_ViewSetNodeData function registers a pointer to an arbitrary data structure (previously allocated with .Xr malloc 3 or .Xr AG_Malloc 3 ) to be associated with a given .Fa node , using a table in the .Nm structure. This is useful for nodes that need to cache resources such as texture handles, that are specific to an .Nm instance. .Pp .Fn SK_ViewGetNodeData returns a pointer to the arbitrary data structure previously associated with .Fa node , or NULL if no match was found. .Sh EXAMPLES See the .Xr skedit 1 application (the .Pa tools directory in the Agar source distribution). .Sh SEE ALSO .Xr M_Matrix 3 , .Xr M_Real 3 , .Xr M_Vector 3 , .Xr SG_Intro 3 , .Xr SK 3 .Sh HISTORY The .Nm widget first appeared in Agar 1.6.0.