<-- Back to AG_Intro.3

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>
#include <agar/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 (equivalent to invoking AG_ExpandHoriz(3)).
RG_TILEVIEW_VFILL	Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
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.