NAME

       canvas::sqmap - Canvas with map background based on square tiles

SYNOPSIS

       package require Tcl  8.4

       package require Tk  8.4

       package require snit

       package require uevent::onidle

       package require cache::async

       package require canvas::sqmap  ?0.3.1?

       ::canvas::sqmap pathName ?options?

       canvasName image set cell image

       canvasName image unset cell

       canvasName flush

________________________________________________________________________________________________________________

DESCRIPTION

       This  package  provides  an extended canvas widget for the display of maps based on a set of square image
       tiles. The tiles are the background of the canvas, with all other canvas  items  added  always  shown  in
       front  of  them.  The  number  of  tiles  shown,  tile  size, and where to get the images to show are all
       configurable.

API

       ::canvas::sqmap pathName ?options?
              Creates the canvas pathName and configures it. The new widget supports  all  of  the  options  and
              methods of a regular canvas, plus the options and methods described below.

              The result of the command is pathName.

   OPTIONS
       -grid-cell-width
              The  value  for  this  option  is  a non-negative integer. It specifies the width of the cells the
              background is made up of.

       -grid-cell-height
              The value for this option is a non-negative integer. It specifies the  height  of  the  cells  the
              background is made up of.

       -grid-cell-command
              The  value  for this option is a command prefix. It is invoked whenever the canvas needs the image
              for a specific cell of the background, with two additional arguments, the id of the  cell,  and  a
              command prefix to invoke when the image is ready, or known to not exist.

              The  id  of the cell is a 2-element list containing the row and column number of the cell, in this
              order. The result command prefix (named "$result" in the example below) has  to  be  invoked  with
              either two or three arguments, i.e.

                  $result set   $cellid $image ; # image is known and ready
                  $result unset $cellid        ; # image does not exist

              This  option  may be left undefined, i.e. the canvas can operate without it. In that case the only
              images shown in grid cells are those explicitly set with  the  method  image  set,  see  the  next
              section. All other grid cells will simply be empty.

       -viewport-command
              This  option  specifies  a command prefix to invoke when the viewport of the canvas is changed, to
              allow users keep track of where in the scroll-region we are at all times. This can  be  used,  for
              example,  to  drive  derivate  displays,  or  to keep items in view by moving them as the viewport
              moves.

       -image-on-load
              The value for this option is an image. If specified the image is shown in a cell while the  actual
              image for that cell is getting loaded through the callback specified by the -grid-cell-command.

       -image-on-unset
              The  value  for  this  option is an image. If specified the image is shown in a cell for which the
              callback specified by the -grid-cell-command reported that there is no actual image to be shown.

   METHODS
       canvasName image set cell image
              Invoking this method places the image into the specified cell of the background. The cell is given
              as a 2-element list containing row and column number, in this order.

              Note that an image is allowed to be associated with and displayed in multiple cells of the canvas.

       canvasName image unset cell
              Invoking this method declares the specified cell of the background as  empty,  an  existing  image
              shown  by  this  cell will be forgotten.  The cell is given as a 2-element list containing row and
              column number, in this order.

       canvasName flush
              Invoking this method forces the canvas to completely reload the images for all cells. Do  not  use
              this  method  if  the  canvas is operated without a -grid-cell-command, as in that case the canvas
              will simply forget all images without being able to reload them.

IMAGE OWNERSHIP

       Note that the canvas does not take ownership of the images it shows in the background.  In  other  words,
       when we say that the canvas forgets an image this means only that the association between a grid cell and
       shown image is broken. The image is not deleted. Managing the lifecycle of the images shown by the canvas
       is responsibility of the user of the canvas.

BUGS, IDEAS, FEEDBACK

       This  document,  and  the package it describes, will undoubtedly contain bugs and other problems.  Please
       report such in the category canvas of the Tklib Trackers  [http://core.tcl.tk/tklib/reportlist].   Please
       also report any ideas for enhancements you may have for either package and/or documentation.

KEYWORDS

       canvas, cell, grid, image, map, square map, tile

tklib                                                 0.3.1                                   canvas::sqmap(3tk)