Paved::canvas 1.1

Table Of Contents

• NAME
• SYNOPSIS
• INTRODUCTION
• STANDARD OPTIONS
• PAVED-SPECIFIC OPTIONS
• WIDGET COMMANDS
• EXTENDED COMMANDS
• ITEM IDS AND TAGS
• BINDINGS
• EXAMPLE
• NOTES
• HISTORY

NAME

Paved::canvas - an extension of the canvas widget

SYNOPSIS

package require Paved::canvas

Paved::canvas pathName ?options?

INTRODUCTION

Paved::canvas is an extension of the canvas widget.

A Paved-canvas is simply a canvas with an image item acting as a paved (tiled) background.

The background image is dinamically sized in order to cover all the visible canvas.

This widget can handle huge scrollregions; actually image size is 'one tile' more the canvas size, and it is automatically panned when canvas scrolls.

STANDARD OPTIONS

.. all canvas options are supported.

PAVED-SPECIFIC OPTIONS

-tile image

Specifies an image to display as background, which must have been created with the "image create" command. If image is the empty string, the background is disabled.

-tile filename

filename can be also the name of a supported graphic file ( see [ image types ] )

-bgzoom n

n is an integer value (default 1). With this option, each pixel of the source image will be expanded into a block of n x n pixels.

-tileorigin tuple

tuple is a list with two coordinates describing where the top-left corner of the 'first' tile will be placed in the canvas. Default is { 0 0 }. Each of the coordinates may be specified in any of the valid forms for the 'canvas' COORDINATES. If you have a MxN tile and you want its center be on the point (0,0) of the canvas, specify -tileorigin { M/2 N/2 } (or, equivalently {-M/2 -N/2}, by virtue of coherence properties)

WIDGET COMMANDS

.. all canvas widget commands are supported.

EXTENDED COMMANDS

pathName clean

delete all items on canvas (leaving the background-image intact). This command is obsolete; now you can safely use the delete command.

ITEM IDS AND TAGS

the embedded background image is tagged as "bgimage" (this tag is reserved).

BINDINGS

A script is attached to the <Configure> event for the pseudo class PavedCanvas, so that each time the widget is resized, the background image is resized accordling.

EXAMPLE

   package require Paved::canvas
    # suppose xyz.gif is in current directory
   image create photo xyzImage -file xyz.gif 
    # create a tiled-canvas widget; use 'xyzImage' as background.
   Paved::canvas .c -tile xyzImage
    # display it.
   pack .c -expand true -fill both

or in a more compact form:

   package require Paved::canvas
   Paved::canvas .c -tile xyz.gif
   pack .c -expand true -fill both

NOTES

A Paved-canvas is simply a canvas with an image item. This image item is automatically created and it is tagged as "bgimage"

(Within the next paragraphs, we assume that $c is the paved-canvas widget).

Few things you should always remember:

• In general, the background image item bgimage should never be selected. Be careful using the special tags "all" and "current" :
  • Never use the "all" tag ; instead use "!bgimage" (i.e. "all" but "bgimage" )
  • An exception of the above rule is for the delete command; it has been safely redefined, so that it is quite impossible to delete the background image.
    • you can write "$c delete all" without fear to delete the background.
  • Be careful with other canvas subcommands, since the "all" and "current" tags are not filtered for them.

       Example: 
          # *WRONG* way to get the bounding-box (since the background is included, too!)
         $c bbox all  
          # *RIGHT* way get the bounding-box   
         $c bbox !bgimage
    

  • Instead of using "current", use "current&&!bgimage"

       Example: 
         # *WRONG* way to move the item under the cursor 
         #   (if mouse pointer is over the canvas background, bgimage is moved)
        $c move current $dx $dy
         # *RIGHT* way to move the item under the cursor 
        $c move current&&!bgimage $dx $dy
    

HISTORY

• 1.0
  • initial revision
• 1.1
  • Bug-fixing for -scrollregion update
  • Added special trap for 'delete' command:
    • 'current' and 'all' tags are transparently transformed, so that the background image cannot be deleted (..with some limitations..)
  • Added Paved::canvasAdaptor for 'paving' existing canvas widgets.
  • Removed dependency from a fixed 'Snit' package (required Snit 0.91 or later).