NAME

RG_Tileview — Agar-RG graphics editor

SYNOPSIS

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

DESCRIPTION

The RG_Tileview widget displays the contents of a RG_Tile(3) and provides an interface for implementing different types of graphical editors and tools. Built-in graphical editors for tile pixmaps, sketches and features are provided.

INITIALIZATION

RG_Tileview *
RG_TileviewNew(void *parent, RG_Tileset *ts, Uint flags);

void
RG_TileviewSetTile(RG_Tileview *tv, RG_Tile *tile);

void
RG_TileviewSetZoom(RG_Tileview *tv, int new_zoom, int adj_offset);

void
RG_TileviewSetAutoRefresh(RG_Tileview *tv, int flag, int rate);

The RG_TileviewNew() function allocates, initializes, and attaches a RG_Tileview widget, initially displaying the given tile. Acceptable flags include:

RG_TILEVIEW_NO_SCROLLING: Disable panning on right click.
RG_TILEVIEW_HIDE_CONTROLS: Hide the control overlays.
RG_TILEVIEW_NO_TILING: Disable background tiling.
RG_TILEVIEW_NO_EXTENT: Don't display the boundary rectangle.
RG_TILEVIEW_NO_GRID: Disable the standard tile grid.
RG_TILEVIEW_HFILL: Expand horizontally in parent container.
RG_TILEVIEW_VFILL: Expand vertically in parent container.
RG_TILEVIEW_EXPAND: Shorthand for RG_TILEVIEW_HFILL | RG_TILEVIEW_VFILL.

The RG_TileviewSetTile() function changes the tile associated with the given RG_Tileview.

The RG_TileviewSetZoom() function changes the display scaling factor to new_zoom (given in percents). If the adj_offset argument is non-zero, the display is offset to preserve centering.

The RG_TileviewSetAutoRefresh() function controls the auto-refresh setting. If flag is non-zero, the tile is automatically regenerated every rate milliseconds.

PRIMITIVES

void
RG_TileviewColor3i(RG_Tileview *tv, Uint8 r, Uint8 g, Uint8 b);

void
RG_TileviewColor4i(RG_Tileview *tv, Uint8 r, Uint8 g, Uint8 b, Uint8 a);

void
RG_TileviewColor(RG_Tileview *tv, AG_Color *color, Uint8 alpha);

void
RG_TileviewAlpha(RG_Tileview *tv, Uint8, alpha");

void
RG_TileviewPixel(RG_Tileview *tv, int x, int y);

void
RG_TileviewPixelCached(RG_Tileview *tv, int x, int y, Uint8 r, Uint8 g, Uint8 b);

void
RG_TileviewRect(RG_Tileview *tv, int x, int y, int w, int h);

void
RG_TileviewRectOut(RG_Tileview *tv, int x, int y, int w, int h);

void
RG_TileviewCircle(RG_Tileview *tv, int x, int y, int r);

The RG_TileviewColor3i(), RG_TileviewColor4i(), RG_TileviewColor() and RG_TileviewAlpha() functions modify the current RGBA value describing the color to use for subsequent primitive calls.

The RG_TileviewPixel() function plots a pixel at the specified tile coordinates. The pixel will not be visible until the tile is regenerated.

The RG_TileviewPixelCached() function overwrites the pixel on the cached, generated tile used by RG_Tileview, as opposed to the source tile. The pixel will be visible immediately, but the source tile will be unchanged.

The RG_TileviewRect() function draws a filled rectangle of dimensions w, h at tile coordinates x, y. The RG_TileviewRectOut() variant draws a rectangle outline.

The RG_TileviewCircle() function draws a circle outline of radius r with the origin at x, y.

GRAPHICAL CONTROLS

RG_TileviewCtrl *
RG_TileviewAddCtrl(RG_Tileview *tv, enum rg_tileview_ctrl_type type, const char *fmt);

void
RG_TileviewDelCtrl(RG_Tileview *tv, RG_TileviewCtrl *ctrl);

int
RG_TileviewInt(RG_Tileview *tv, int nval);

Uint
RG_TileviewUint(RG_Tileview *tv, int nval);

float
RG_TileviewFloat(RG_Tileview *tv, int nval);

double
RG_TileviewDouble(RG_Tileview *tv, int nval);

void
RG_TileviewSetInt(RG_Tileview *tv, int nval, int v);

void
RG_TileviewSetUint(RG_Tileview *tv, int nval, Uint v);

void
RG_TileviewSetFloat(RG_Tileview *tv, int nval, float v);

void
RG_TileviewSetDouble(RG_Tileview *tv, int nval, double v);

The RG_Tileview widget implements generic graphical controls. It is used for moving and resizing pixmaps/sketches inside tiles and controlling particular features. A control may manipulate multiple integral and floating-point variables.

The RG_TileviewAddCtrl() function creates a new graphical control of the given type:

enum rg_tileview_ctrl_type {
	RG_TILEVIEW_POINT,         /* Point (x,y) */
	RG_TILEVIEW_RECTANGLE,     /* Rectangle (x,y,w,h) */
	RG_TILEVIEW_RDIMENSIONS,   /* Rectangle (w,h) */
	RG_TILEVIEW_CIRCLE         /* Circle (x,y,r) */
};

RG_TILEVIEW_POINT controls a single point value. It is used for setting the position of the origin of a tile, for instance. RG_TILEVIEW_RECTANGLE controls both the coordinates and geometry of a rectangle. It is used for things like pixmaps and sketches. RG_TILEVIEW_RDIMENSIONS controls the dimensions of a non-movable rectangle. It is used for changing the geometry of the tile itself when no sketches, pixmaps or features are selected. RG_TILEVIEW_CIRCLE controls the position and radius of a circle.

The special format string fmt and subsequent arguments specify the variables to edit. Acceptable sequences include %i (int), %u (Uint), %f (float) and %d (double). Sequences such as %*i specify that the argument is a pointer to the given type.

The RG_TileviewDelCtrl() function destroys the given control.

The remaining tileview_*() and tileview_set_*() functions respectively retrieve and modify the given value associated with the given control.

TOOLS

void
RG_TileviewSelectTool(RG_Tileview *tv, RG_TileviewTool *tool);

void
RG_TileviewUnselectTool(RG_Tileview *tv);

The RG_TileviewSelectTool() and RG_TileviewUnselectTool() functions select or deselect the current edition tool.

The generic features of all edition tools are defined by the structure:

typedef struct rg_tileview_tool_ops {
	const char *name;     /* Name of tool */
	const char *desc;     /* Tool description */
	AG_Size len;          /* Size of structure */
	Uint flags;

	int icon;             /* Specific icon (or -1) */
	int cursor;           /* Specific cursor (or -1) */

	void       (*init)(void *);
	void       (*destroy)(void *);
	AG_Window *(*edit)(void *);
	void       (*selected)(void *);
	void       (*unselected)(void *);
} RG_TileviewToolOps;

Two specialized derivates are available, one for bitmap-specific tools and another for vector-specific tools:

typedef struct rg_tileview_bitmap_tool_ops {
	struct rg_tileview_tool_ops ops;
	void (*mousebuttondown)(void *, int, int, int);
	void (*mousebuttonup)(void *, int, int, int);
	void (*mousemotion)(void *, int, int, int, int);
} RG_TileviewBitmapToolOps;

typedef struct rg_tileview_sketch_tool_ops {
	struct rg_tileview_tool_ops ops;
	void (*mousebuttondown)(void *, RG_Sketch *, float, float, int);
	void (*mousebuttonup)(void *, RG_Sketch *, float, float, int);
	void (*mousemotion)(void *, RG_Sketch *, float, float, float,
	                    float);
	int (*mousewheel)(void *, RG_Sketch *, int);
	void (*keydown)(void *, RG_Sketch *, int, int);
	void (*keyup)(void *, RG_Sketch *, int, int);
} RG_TileviewSketchToolOps;

EVENTS

The RG_Tileview widget does not generate any event.