.\" Copyright (c) 2002-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 MAP_VIEW 3 .Os Agar 1.7 .Sh NAME .Nm MAP_View .Nd editor and display widget for Agar-MAP maps .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION The .Nm widget renders the contents of a .Xr MAP 3 to the display. .Nm also provides a map editor with an extensible set of map edition tools. .Sh INITIALIZATION .nr nS 1 .Ft MAP_View * .Fn MAP_ViewNew "void *parent" "MAP *map" "Uint flags" "AG_Toolbar *toolbar" "AG_Statusbar *statbar" .Pp .Ft void .Fn MAP_ViewSizeHint "MAP_View *mv" "int w" "int h" .Pp .Ft void .Fn MAP_ViewSetScale "MAP_View *mv" "Uint zoom" "int adj_offs" .Pp .nr nS 0 The .Fn MAP_ViewNew function allocates, initializes, and attaches a .Nm widget, displaying the given .Fa map . The .Fa flags may include: .Bl -tag -width "MAP_VIEW_NO_BMPSCALE " .It MAP_VIEW_EDIT Enable map edition tools. .It MAP_VIEW_GRID Display the standard tile grid. .It MAP_VIEW_CENTER When the widget is attached to a new map, center on its origin. .It MAP_VIEW_NO_CURSOR Disable the edition cursor. .It MAP_VIEW_NO_BMPSCALE Disable bitmap scaling on zoom. .It MAP_VIEW_NO_BG Disable background tiling. .It MAP_VIEW_NO_NODESEL Disable node selection functions. .It MAP_VIEW_SHOW_ORIGIN Draw a circle at the origin. .El .Pp If .Fa toolbar is not NULL, the .Nm will automatically create buttons in it for each tool registered with .Fn MAP_ViewRegTool . If .Fa statbar is not NULL, it will be used to display status information. .Pp The .Fn MAP_ViewSizeHint function arranges for the .Nm to reserve enough space to display .Fa w by .Fa h nodes at the initial sizing stage. .Pp The .Fn MAP_ViewSetScale function sets the scaling factor to .Fa zoom , given in % of the default tile geometry. If the .Fa adj_offs argument is nonzero, the camera is offset to preserve centering. .Sh SELECTIONS .nr nS 1 .Ft void .Fn MAP_ViewSetSelection "MAP_View *mv" "int x" "int y" "int w" "int h" .Pp .Ft int .Fn MAP_ViewGetSelection "MAP_View *mv" "int *x" "int *y" "int *w" "int *h" .Pp .nr nS 0 The .Fn MAP_ViewSetSelection function sets the active selection to .Fa w by .Fa h nodes at map position .Fa x , .Fa y . .Fn MAP_ViewSetSelection also disables any mouse selection in progress. .Pp The .Fn 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 .Fa x , .Fa y , .Fa w and .Fa h . .Sh EXTENSIONS .nr nS 1 .Ft void .Fn MAP_ViewRegTool "MAP_View *mv" "const MAP_Tool *toolspec" "void *arg" .Pp .Ft void .Fn MAP_ViewSetDefaultTool "MAP_View *mv" "MAP_Tool *tool" .Pp .Ft void .Fn MAP_ViewRegDrawCb "MAP_View *mv" "void (*f)(MAP_View *mv, void *p)" .Pp .nr nS 0 The .Nm widget provides a generic interface for tools that must accomplish diverse map operations. .Fn MAP_ViewRegTool registers a tool for use from a .Nm . .Fa toolspec is assumed to point to a .Ft tool structure with the following fields properly initialized: .Bd -literal .\" SYNTAX(c) 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; .Ed .Pp The .Fn init , .Fn destroy , .Fn load and .Fn save operations are used to initialize, free, save and restore any private data structures needed by the tool. .Pp The .Fn cursor operation is expected to draw the current cursor at the screen coordinates given by the .Xr AG_Rect argument. .Pp The .Fn 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 .Sq stamp and .Sq eraser tools will use this operation. .Pp Tools that perform more complex operations (such as vector graphics manipulations) will generally use the lower-level .Fn mousemotion , .Fn mousebuttondown , .Fn mousebuttonup , .Fn keydown and .Fn 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. .Pp The .Fn 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. .Pp The .Fn MAP_ViewRegDrawCb function registers a function to invoke every time the .Nm widget is redrawn. .Sh EVENTS The .Nm widget generates the following events: .Pp .Bl -tag -compact -width 2n .It Fn mapview-dblclick "int button" "int x" "int y" "int xoff" "int yoff" The user double clicked over the given tile. .El .Sh SEE ALSO .Xr AG_DataSource 3 , .Xr AG_Widget 3 , .Xr AG_Window 3 , .Xr MAP 3 , .Xr MAP_Object 3 , .Xr RG 3 , .Xr SG_Intro 3 .Sh HISTORY The .Nm widget first appeared in Agar 1.0.