Hexmap Reference Manual
<<< Previous PageHomeUp 

HexGrid

Name

HexGrid -- A Layout Container for a Hexagonal Grid of HexTile

Synopsis


#include <hexmap.h>



struct      HexGrid;
struct      HexGridClass;



HexGrid*    hex_grid_new                    (HexData *background_hex,
                                             HexColor *grid_line_color,
                                             guint width,
                                             guint height);

void        hex_grid_set_size               (HexGrid *grid,
                                             guint width,
                                             guint height);
void        hex_grid_get_size               (HexGrid *grid,
                                             guint *width,
                                             guint *height);
void        hex_grid_set_grid_line_color    (HexGrid *grid,
                                             HexColor *color);
gboolean    hex_grid_get_grid_line_color    (HexGrid *grid,
                                             HexColor *color);
void        hex_grid_set_background_hex     (HexGrid *grid,
                                             HexData *background_hex);
HexData*    hex_grid_get_background_hex     (HexGrid *grid);
guint       hex_grid_get_hex_width          (HexGrid *grid);

void        hex_grid_set_tile               (HexGrid *grid,
                                             gint x,
                                             gint y,
                                             gint depth,
                                             HexTile *tile);
HexTile*    hex_grid_get_tile               (HexGrid *grid,
                                             gint x,
                                             gint y,
                                             gint depth);
void        hex_grid_clear_list             (HexGrid *grid,
                                             gint x,
                                             gint y);
HexList*    hex_grid_get_list               (HexGrid *grid,
                                             gint x,
                                             gint y);

gboolean    hex_grid_foreach_type_topdown   (HexGrid *grid,
                                             gint x,
                                             gint y,
                                             GType type,
                                             HexEachFunc func,
                                             gboolean halt_on,
                                             gpointer data);
gboolean    (*HexEachFunc)                  (HexTile *tile,
                                             gint depth,
                                             gpointer data);
gpointer    hex_grid_get_backend_drawable   (HexGrid *grid,
                                             HexGridCacheData *disp_info,
                                             gint x,
                                             gint y,
                                             gboolean (*equal_func) (HexGridCacheData*, HexGridCacheData*),
                                             HexGridCacheData* (*copy_func) (HexColor*, HexGridCacheData*, GDestroyNotify*),
                                             gpointer (*create_func) (HexList*, HexData*, HexColor*, gint,HexGridCacheData*, GDestroyNotify*));
struct      HexGridCacheData;

Object Hierarchy


  GObject
   +----HexGrid

Properties


  "background-hex"       HexData              : Read / Write
  "grid-height"          guint                : Read / Write
  "grid-line-color"      gpointer             : Write
  "grid-width"           guint                : Read / Write

Signal Prototypes


"hex-changed"
            void        user_function      (HexGrid *hexgrid,
                                            gint arg1,
                                            gint arg2,
                                            gpointer user_data);

Description

A HexGrid is essentially a hexagonal map. Since it is separate from HexDisplay, the map in a particular display widget can be swapped out easily. A HexGrid also performs internal caching of images through the function hex_grid_get_pixmap(), speeding up the drawing routine in HexDisplay.

Details

struct HexGrid

struct HexGrid;

A layout container for a grid of HexTile

struct HexGridClass

struct HexGridClass;

The class structure for HexGrid

hex_grid_new ()

HexGrid*    hex_grid_new                    (HexData *background_hex,
                                             HexColor *grid_line_color,
                                             guint width,
                                             guint height);

Creates a new HexGrid.

background_hex :

the HexData to be used as the background of each hex

grid_line_color :

the color to use when drawing the grid lines. Passing NULL will cause no grid lines to be drawn.

width :

the width of the grid in hexes

height :

the height of the grid in hexes

Returns :

a newly created HexGrid

hex_grid_set_size ()

void        hex_grid_set_size               (HexGrid *grid,
                                             guint width,
                                             guint height);

Sets the size of the grid.

grid :

a HexGrid

width :

the new width of the grid in hexes

height :

the new height of the grid in hexes

hex_grid_get_size ()

void        hex_grid_get_size               (HexGrid *grid,
                                             guint *width,
                                             guint *height);

Gets the size of the grid.

grid :

a HexGrid

width :

a location to return the width of the grid in hexes

height :

a location to return the height of the grid in hexes

hex_grid_set_grid_line_color ()

void        hex_grid_set_grid_line_color    (HexGrid *grid,
                                             HexColor *color);

Sets the grid line color.

grid :

a HexGrid

color :

the new color to use when drawing the grid lines. Passing NULL will cause no grid lines to be drawn.

hex_grid_get_grid_line_color ()

gboolean    hex_grid_get_grid_line_color    (HexGrid *grid,
                                             HexColor *color);

Gets the grid line color for a HexGrid.

grid :

a HexGrid

color :

a location to return the color to use when drawing the grid lines

Returns :

TRUE if grid lines are drawn, FALSE if not. color is only set in the TRUE case

hex_grid_set_background_hex ()

void        hex_grid_set_background_hex     (HexGrid *grid,
                                             HexData *background_hex);

Sets the background hex.

grid :

a HexGrid

background_hex :

the HexData to be used as the new background of each hex. The width of this HexData must be the same as that of the old background hex

hex_grid_get_background_hex ()

HexData*    hex_grid_get_background_hex     (HexGrid *grid);

Gets the background_hex.

grid :

a HexGrid

Returns :

the HexData to be used as the background of each hex

hex_grid_get_hex_width ()

guint       hex_grid_get_hex_width          (HexGrid *grid);

Gets the width of the background hex.

grid :

a HexGrid

Returns :

the width of the background hex in the grid

hex_grid_set_tile ()

void        hex_grid_set_tile               (HexGrid *grid,
                                             gint x,
                                             gint y,
                                             gint depth,
                                             HexTile *tile);

Sets a tile. This function should not be used for HexWalker and types derived from it, which use hex_walker_connect_grid() instead.

grid :

a HexGrid

x :

the x position of the tile

y :

the y position of the tile

depth :

the depth of the tile

tile :

the new HexTile. The width of the tile must match the width of the background hex in the grid. Passing NULL will clear a previous tile in this location

hex_grid_get_tile ()

HexTile*    hex_grid_get_tile               (HexGrid *grid,
                                             gint x,
                                             gint y,
                                             gint depth);

Gets a tile from the grid.

grid :

a HexGrid

x :

the x position of a hex

y :

the y position of a hex

depth :

the depth of a tile

Returns :

the HexTile at (x, y) with depth depth. If there is no such tile, returns NULL.

hex_grid_clear_list ()

void        hex_grid_clear_list             (HexGrid *grid,
                                             gint x,
                                             gint y);

Removes tiles of all depths at a given (x, y) location.

grid :

a HexGrid

x :

the x location of the list

y :

the y location of the list

hex_grid_get_list ()

HexList*    hex_grid_get_list               (HexGrid *grid,
                                             gint x,
                                             gint y);

Gets a list of tiles from the grid.

grid :

a HexGrid

x :

the x position of a hex

y :

the y position of a hex

Returns :

a HexList containing all the HexTile at (x, y). A return value of NULL indicates an empty list, or a hex outside the range of the grid.

hex_grid_foreach_type_topdown ()

gboolean    hex_grid_foreach_type_topdown   (HexGrid *grid,
                                             gint x,
                                             gint y,
                                             GType type,
                                             HexEachFunc func,
                                             gboolean halt_on,
                                             gpointer data);

Calls the function func on each tile which g_type_is_a() type at the location (x, y) in the grid, starting with the highest depth and proceeding to the lowest. If any such function call returns the value matching halt_on, no further function calls are executed and halt_on is returned. Otherwise, !halt_on is returned.

grid :

a HexGrid

x :

the x position of a hex

y :

the y position of a hex

type :

the GType of an object descended from HexTile

func :

a HexEachFunc

halt_on :

which return value stops further function calls

data :

data passed to func

Returns :

halt_on if any function call returns halt_on, otherwise !halt_on

HexEachFunc ()

gboolean    (*HexEachFunc)                  (HexTile *tile,
                                             gint depth,
                                             gpointer data);

A callback passed to hex_grid_foreach_type_topdown(), which determines what happens to each hex.

tile :

a HexTile

depth :

the depth the tile is stored at in the HexGrid

data :

user data passed to hex_grid_foreach_type_topdown()

Returns :

if the return value matches the halt_on parameter passed to hex_grid_foreach_type_topdown(), that function returns immediately and does not call the HexEachFunc on any more tiles.

hex_grid_get_backend_drawable ()

gpointer    hex_grid_get_backend_drawable   (HexGrid *grid,
                                             HexGridCacheData *disp_info,
                                             gint x,
                                             gint y,
                                             gboolean (*equal_func) (HexGridCacheData*, HexGridCacheData*),
                                             HexGridCacheData* (*copy_func) (HexColor*, HexGridCacheData*, GDestroyNotify*),
                                             gpointer (*create_func) (HexList*, HexData*, HexColor*, gint,HexGridCacheData*, GDestroyNotify*));

This function is for use in writing backends to hexmap. Ordinary users should never use it.

grid :

A HexGrid

disp_info :

System dependent information about the object that is requesting the drawable.

x :

The x coordinate of the hex

y :

The y coordinate of the hex

equal_func :

A function to check if the system dependent information matches information already in the cache.

copy_func :

A function to copy the system independent information, for placement in the cache. The third argument of this function should return a pointer to a function to destroy the system dependent information when it is flushed from the cache. This is also a good time to calculate the system dependent form of the grid line color, as the cache is flushed whenever this color is changed.

create_func :

A function to create a system dependent drawable. The final argument of this function should return a pointer to a function to destroy the drawable.

Returns :

A drawable of the format returned by create_func.

struct HexGridCacheData

struct HexGridCacheData;

An implementation-dependent structure defined in each of the library's back ends. Only of interest to backend implementors.

Properties

"background-hex" (HexData : Read / Write)

The HexData used as the background (lowest layer) of the grid. It is recomended that this HexData have no fully or partially transparent pixels.

"grid-height" (guint : Read / Write)

The height of the grid in hexes

"grid-line-color" (gpointer : Write)

The color of the grid lines. NULL indicates no grid lines.

"grid-width" (guint : Read / Write)

the width of the grid in hexes

Signals

The "hex-changed" signal

void        user_function                  (HexGrid *hexgrid,
                                            gint arg1,
                                            gint arg2,
                                            gpointer user_data);

The image for the hex at (arg1, arg2) has changed, and needs to be redrawn. This signal is primarily for the benefit of HexDisplay.

hexgrid :

the object which received the signal.

arg1 :

the x coordinate of the hex

arg2 :

the y coordinate of the hex

user_data :

user data set when the signal handler was connected.



<<< Previous PageHomeUp 
HexList