<-- Back to AG_Intro.3

SYNOPSIS

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

DESCRIPTION

The MAP_View widget renders the contents of a MAP(3) to the display. MAP_View also provides a map editor with an extensible set of map edition tools.

INITIALIZATION

MAP_View* MAP_ViewNew (void *parent, MAP *map, Uint flags, AG_Toolbar *toolbar, AG_Statusbar *statbar)

void MAP_ViewSizeHint (MAP_View *mv, int w, int h)

void MAP_ViewSetScale (MAP_View *mv, Uint zoom, int adj_offs)

The MAP_ViewNew() function allocates, initializes, and attaches a MAP_View widget, displaying the given map. The flags may include:

MAP_VIEW_EDIT	Enable map edition tools.
MAP_VIEW_GRID	Display the standard tile grid.
MAP_VIEW_CENTER	When the widget is attached to a new map, center on its origin.
MAP_VIEW_NO_CURSOR	Disable the edition cursor.
MAP_VIEW_NO_BMPSCALE	Disable bitmap scaling on zoom.
MAP_VIEW_NO_BG	Disable background tiling.
MAP_VIEW_NO_NODESEL	Disable node selection functions.
MAP_VIEW_SHOW_OFFSETS	Show lines to indicate element offsets (debug only).
MAP_VIEW_SHOW_ORIGIN	Draw a circle at the origin.

If toolbar is not NULL, the MAP_View will automatically create buttons in it for each tool registered with MAP_ViewRegTool(). If statbar is not NULL, it will be used to display status information.

The MAP_ViewSizeHint() function arranges for the MAP_View to reserve enough space to display w by h nodes at the initial sizing stage.

The MAP_ViewSetScale() function sets the scaling factor to zoom, given in % of the default tile geometry. If the adj_offs argument is nonzero, the camera is offset to preserve centering.

SELECTIONS

void MAP_ViewSetSelection (MAP_View *mv, int x, int y, int w, int h)

int MAP_ViewGetSelection (MAP_View *mv, int *x, int *y, int *w, int *h)

The MAP_ViewSetSelection() function sets the active selection to w by h nodes at map position x, y. MAP_ViewSetSelection() also disables any mouse selection in progress.

The MAP_ViewGetSelection() returns 1 if there is an active selection or 0 if there is none. If there is no selection, no value is written to x, y, w and h.

EXTENSIONS

void MAP_ViewRegTool (MAP_View *mv, const MAP_Tool *toolspec, void *arg)

void MAP_ViewSetDefaultTool (MAP_View *mv, MAP_Tool *tool)

void MAP_ViewRegDrawCb (MAP_View *mv, void (*f)(MAP_View *mv, void *p))

The MAP_View widget provides a generic interface for tools that must accomplish diverse map operations. MAP_ViewRegTool() registers a tool for use from a MAP_View. toolspec is assumed to point to a tool structure with the following fields properly initialized:

typedef struct map_tool {
	const char *name;     /* Name of the tool */
	const char *desc;     /* Short description */
	AG_StaticIcon *icon;  /* Icon (or NULL) */
	int cursor_index;     /* Static cursor (or -1) */

	void (*init)(MAP_Tool *t);
	void (*destroy)(MAP_Tool *t);
	int  (*load)(MAP_Tool *t, AG_DataSource *ds);
	int  (*save)(MAP_Tool *t, AG_DataSource *ds);
	int  (*cursor)(MAP_Tool *t, AG_Rect *r);
	void (*effect)(MAP_Tool *t, MAP_Node *n);
	int (*mousemotion)(MAP_Tool *t, int x, int y, int xrel,
	                  int yrel, int xo, int yo, int xorel,
			  int yorel, int button_state);
	int (*mousebuttondown)(MAP_Tool *t, int x, int y, int xoff,
	                       int yoff, int button);
	int (*mousebuttonup)(MAP_Tool *t, int x, int y, int xoff,
	                     int yoff, int button);
	int (*keydown)(MAP_Tool *t, int ksym, int kmod);
	int (*keyup)(MAP_Tool *t, int ksym, int kmod);
} MAP_Tool;

The init(), destroy(), load() and save() operations are used to initialize, free, save and restore any private data structures needed by the tool.

The cursor() operation is expected to draw the current cursor at the screen coordinates given by the AG_Rect argument.

The effect() operation is executed on mouse click events, and on mouse motion events where the relative map (node) coordinates are >|1|. Typically, simple tools that perform node-specific operations such as the stamp and eraser tools will use this operation.

Tools that perform more complex operations (such as vector graphics manipulations) will generally use the lower-level mousemotion(), mousebuttondown(), mousebuttonup(), keydown() and keyup() operations. If any of these functions return a value of 1, the given event will not be forwarded to the mouse/keyboard tool bindings and default operations.

The MAP_ViewSetDefaultTool() function configures a default tool which will receive all events that have not been processed by the active tool or a mouse event binding.

The MAP_ViewRegDrawCb() function registers a function to invoke every time the MAP_View widget is redrawn.

EVENTS

The MAP_View widget generates the following events:

mapview-dblclick (int button, int x, int y, int xoff, int yoff)

The user double clicked over the given tile.

HISTORY

The MAP_View widget first appeared in Agar 1.0.