Gtk2::Hexgrid - a grid of hexagons

    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;

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.

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

  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.

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

Returns 0 if tile does not exist, else 1

 $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

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

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

 $hexgrid->redraw_board;

Redraw the board.

 $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.

 $hexgrid->get_image($imagename);

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

 $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.

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

Returns a tile object.

Returns the number of tiles in this hexgrid.

Returns all tile objects of this hexgrid.

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

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

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

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

 $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

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

Returns the pixel coordinates to the center of the tile

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

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

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

Returns a list of adjacent tile objects

 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.

 $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.

 $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.

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

ne_corner

nw_corner

se_corner

sw_corner

Returns the width of any tile.

Returns the height of any tile.

Lets you mess up this widget using cairo.

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.

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

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.