RG_TILEVIEW(3)

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.

SEE ALSO
RG(3), RG_Anim(3), RG_Feature(3), RG_Pixmap(3), RG_Sketch(3), RG_Texture(3), RG_Tile(3)