NAME

SK_View — Editor/display widget for Agar dimensioned 2D sketches

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).

SEE ALSO

M_Matrix(3), M_Real(3), M_Vector(3), SG_Intro(3), SK(3)

HISTORY

The SK_View widget first appeared in Agar 1.6.0.