canvas::sqmap(n)            Variations on a canvas            canvas::sqmap(n)



______________________________________________________________________________

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(n)
