NAME

Gtk2::Hexgrid - a grid of hexagons

SYNOPSIS

    use Gtk2 -init;
    use Gtk2::Hexgrid;
    
    my ($w, $h) = (4, 6);
    my $linesize = 35;
    my $border = 30;
    my $evenRowsFirst = 1;
    my $evenRowsLast = 0;
    my $hexgrid = Gtk2::Hexgrid->new ($w, $h, 
                        $linesize, $border, 
                        $evenRowsFirst, $evenRowsLast);
    
    my $window = Gtk2::Window->new;
    $window->add($hexgrid);
    $window->show_all;
    
    Gtk2->main;

DESCRIPTION

Gtk2::Hexgrid is a widget for displaying hexgrids. Choose the dimensions, tile size, tile colors, alignment, border stuff, give it text to display.

This widget only supports vertical orientation (definite columns)

Currently there is no support for sprites or textures. (TODO)

The grid coordinates may seem screwy. Think of the rows as being very thin and the columns as being very thick. As long as there are methods supplied for adjacent tiles, pathfinding, etc., it shouldn't matter at all. (pathfinding is TODO) See example program for a demonstration.

OBJECT HIERARCHY

    Glib::Object
    +--- Gtk2::Object
         +--- Gtk2::Widget
           +--- Gtk2::Container
             +--- Gtk2::Bin
              +--- Gtk2::EventBox
                 +--- Gtk2::Hexgrid

METHODS

new

  my $hexgrid = Gtk2::Hexgrid->new(
                        $w,
                        $h, 
                        $linesize,
                        $border, 
                        $evenRowsFirst,
                        $evenRowsLast,
                        $r,$g,$b);

Creates and returns a new Gtk2::Hexgrid widget.

• $w

  The number of hexes in the even rows

• $h

  Number of rows

• $linesize

  Hexagons have 6 lines under optimal conditions. $linesize is their length in pixels.

• $border

  Space between the grid and the widget boundary (drawable)

• $evenRowsFirst

  Upper-right corner to be "rounded" (see example prog)

• $evenRowsLast

  Upper-left corner to be "rounded" (see example prog)

• $r,$g,$b

  Color. Range is from 0 to 1.

tile_exists

 $hexgrid->tile_exists($col,$row);

Returns 0 if tile does not exist, else 1

draw_tile

 $hexgrid->draw_tile($cr, $col,$row, $r,$g,$b);

Ignore the $cr if you please. $r $g $b are between 0 and 1. Ignore $r,$g,$b if you want the tile's color

draw_tile_ref

 $hexgrid->draw_tile($tile, $r,$g,$b);

Ignore $r,$g,$b if you want the tile's color

redraw_board

 $hexgrid->redraw_board;

Redraw the board.

load_image

 $hexgrid->load_image ($imagename, $filename, $scale_to_tile_size);

This function loads a PNG file. If $scale_to_tile_size is set, it scales to tile size. Note that $tile->set_background also loads a png file, and it caches automatically.

get_image

 $hexgrid->get_image($imagename);

Returns the cairo image named $imagename. This is probably different from its filename. This method is mostly internal.

on_click

 $hexgrid->on_click(
      sub{
          my ($col, $row, $x, $y) = @_;
          $hexgrid->draw_tile(undef, $col,$row, 0, .4, 0);
      }
 );

Give widget something to do when clicked. Callback function is called with tile coordinates and pixel coordinates.

get_tile

 $hexgrid->get_tile($col, $row);

Returns a tile object.

num_tiles

Returns the number of tiles in this hexgrid.

get_all_tiles

Returns all tile objects of this hexgrid.

get_ring

 $hexgrid->get_tiles_in_range($col, $row, $radius);

Returns all tiles that are exactly a particular distance from the specified coordinates.

get_tiles_in_range

 $hexgrid->get_tiles_in_range($col, $row, $range);

Returns all tiles within a particular distance of the specified coordinates.

get_tile_from_XY, get_col_row_from_XY

 $hexgrid->get_col_row_from_XY($x, $y);

$x and $y are pixel coordinates Returns the column and row of the tile If $x and $y are not inside a tile, this function will return coordinates of a nonexistant tile. It may not be correct coordinates if $x and $y are far from any tile.

 $hexgrid->get_tile_from_XY($x, $y);

Returns a tile object

get_tile_center

 $hexgrid->get_tile_center($col, $row);

Returns the pixel coordinates to the center of the tile

get_adjacent_tile_coordinates

 my @adj = $hexgrid->get_adjacent_tile_coordinates($col, $row);

Returns a list of 6 array references containing col and row of adjacent tiles

get_adjacent_tiles

 my @adj = $hexgrid->get_adjacent_tiles($col, $row);

Returns a list of adjacent tile objects

tiles_adjacent

 my ($col1,$row1,$col2,$row2) = (4,5,4,7);
 die unless $hexgrid->tiles_adjacent($col1,$row1,$col2,$row2);

Rreturns 1 if tiles are adjacent, else 0. In case you're wondering, the above snippet lives. See the example for proof.

next_tile_by_direction

 $hexgrid->next_tile_by_direction($col,$row, $direction);

This will return a tile adjacent to the given coordinates in the given direction. If there is no tile, it will return undef. As for $direction, 0 is northeast, 1 southeast, 2 south, etc. Don't worry about going over 5 or under 0. $tile->northeast is a simpler way to do this.

next_col_row_by_direction

 $hexgrid->next_col_row_by_direction($col,$row, $direction);

This function exists because next_tile_by_direction will return undef if the tile does not exist. There are no such limits to this one.

Corners

These will return the one or two tiles at a corner of the grid.

ne_corner

nw_corner

se_corner

sw_corner

tile_w

Returns the width of any tile.

tile_h

Returns the height of any tile.

get_cairo_context

Lets you mess up this widget using cairo.

Other hexmap libraries

I started this lib before I saw the hexmap library: http://hexmap.sourceforge.net. It supposedly has perl bindings.

There are other implementations in wesnoth and freeciv. Services such as google codesearch will turn up a few more.

AUTHOR

Zach Morgan, <zpmorgan of google's most popular mail service>

COPYRIGHT & LICENSE

Copyright 2007 Zach Morgan, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Gtk2::Hexgrid

perl -MCPAN -e shell
install Gtk2::Hexgrid