SYNOPSIS

#include <agar/core.h>
#include <agar/sk.h>

DESCRIPTION

The SK_View widget displays a SK(3) sketch, and allows edition facilities to be implemented using a tool registration interface.

INHERITANCE HIERARCHY ↑

AG_Object(3)-> AG_Widget(3)-> SK_View.

INITIALIZATION ↑

SK_View * SK_ViewNew (AG_Widget *parent, SK *sk, Uint flags)

void SK_ViewZoom (SK_View *skv, M_Real factor)

The SK_ViewNew() function allocates, initializes, and attaches a SK_View widget. Acceptable flags options include:

SK_VIEW_HFILL	Expand horizontally in parent container.
SK_VIEW_VFILL	Expand vertically in parent container.
SK_VIEW_EXPAND	Shorthand for SK_VIEW_HFILL SK_VIEW_VFILL\|.

The SK_ViewZoom() function sets the display scaling factor (1.0 = 100%).

TOOL SYSTEM ↑

SK_Tool * SK_ViewRegTool (SK_View *skv, const SK_ToolOps *ops, void *arg)

void SK_ViewSelectTool (SK_View *skv, SK_Tool *tool, void *arg)

SK_Tool * SK_ViewFindTool (SK_View *skv, const char *name)

SK_Tool * SK_ViewFindToolByOps (SK_View *skv, const SK_ToolOps *ops)

void SK_ViewSetDefaultTool (SK_View *skv, SK_Tool *tool)

The SK_ViewRegTool() function registers a new tool class described by the ops structure, which is defined as:

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;

The name field is a unique name identifier for the tool. desc is a short description string. icon is an optional icon or NULL. len is the size of the structure describing an instance of this tool class.

The init() operation initializes a new instance of a tool. destroy() should release all resources allocated by a tool instance. The optional edit() operation is expected to attach arbitrary widgets to editBox, for purposes of editing tool parameters.

The low-level input device events processed by the SK_View widget are forwarded to the handler functions mousemotion(), mousebuttondown(), mousebuttonup(), keydown() and keyup(). They should return 1 if some action has resulted from the event, or 0 otherwise. The coordinates passed to the mouse*() handlers are translated to actual SK(3) coordinates.

The SK_ViewSelectTool() function selects tool as the active tool instance. The arg argument is an optional user pointer passed to the tool instance.

The SK_ViewFindTool() function looks up a tool instance by name. SK_ViewFindToolByOps() looks up a tool instance by class. Both functions return NULL if no match was found.

SK_ViewSetDefaultTool() configures a tool to be active by default when the SK_View is initially created. This is often a "select" type tool.

MISCELLANEOUS ↑

SK_Point * SK_ViewOverPoint (SK_View *skv, M_Vector3 *pos, M_Vector3 *vC, void *ignoreNode)

void SK_ViewSetNodeData (SK_View *skv, SK_Node *node, void *pData)

void * SK_ViewGetNodeData (SK_View *skv, SK_Node *node)

The SK_ViewOverPoint() function performs a proximity query for the given position pos, with respect to all point entities in the sketch. This function is a convenient wrapper around SK_ProximitySearch(3). The closest point is returned into the vC argument. The optional ignore argument specifies a pointer to a node that should be ignored in the search.

The SK_ViewSetNodeData() function registers a pointer to an arbitrary data structure (previously allocated with malloc(3) or AG_Malloc(3)) to be associated with a given node, using a table in the SK_View structure. This is useful for nodes that need to cache resources such as texture handles, that are specific to an SK_View instance.

SK_ViewGetNodeData() returns a pointer to the arbitrary data structure previously associated with node, or NULL if no match was found.

EXAMPLES ↑

See the skedit(1) application (the tools directory in the Agar source distribution).

HISTORY ↑

The SK_View widget first appeared in Agar 1.6.0.