Table of Contents

_________________________________________________________________

## Name

charts - Create and manipulate canvas Add-On Items

## Synopsis

canvas pathName ?options? ... see canvas.n

canvas-pathname create Item ?options?

The «vu-items» includes:

o A «sticker»
  canvas item type (tkSticker-1.2.tar.gz) Heribert Dahms

o A «stripchart» canvas item type (scotty,tkined) Juergen Schoenwaelder

o A «barchart»
  canvas item type (scotty,tkined) Juergen Schoenwaelder

## Standard Options

See canvas.n

See the options manual entry for details on the standard options.

## Overview of Item Types

The sections below describe the various types of items supported by canvas widgets. Each item type is characterized by two things: first, the form of the create command used to create instances of the type; and second, a set of configuration options for items of that type, which may be used in the create and itemconfigure widget commands. Most items don't support indexing or selection or the commands related to them, such as index and insert. Where items do support these facilities, it is noted explicitly in the descriptions below.

## Common Item Options

## Sticker Items

A sticker is a rectangle with text inside but which truncates if it's too long e.g. after the canvas is scaled. The text can be drawn vertically and/or repeated. You can also draw a (filled) bar; we use it showing percentage of a job's completeness. You may use mouse enter/leave bindings to put the complete text in a status line.

TheSticker Item has full support for Tk canvas Postscript generation.

USAGE

Creation, given canvas .c

pathName create sticker x1 y1 x2 y2 ?option value option value ...?

x1 y1 x2 y2 - just like the canvas rectangle coordinates

Options (21) with their defaults

-anchor
  center Position as accepted by Tk_GetAnchor for the text. Subject to rotation via -orient vertical.
-bar
  black Color as accepted by Tk_GetColor for drawing a bar or empty string to suppress drawing.
-color
  black Color as accepted by Tk_GetColor for drawing the text or empty string to suppress drawing.
-fill
  {} Color as accepted by Tk_GetColor for filling the rectangle x1 y1 x2 y1 or empty string for transparency.
-font
  «Helvetica -12" Font as accepted by Tk_GetFontStruct for drawing text.
-lefttrunc 0
  Flag as accepted by Tk_GetBoolean. If true, forces that the rightmost part of too long text is drawn.
-outline
  black Color as accepted by Tk_GetColor for drawing the outline or empty string to suppress drawing.
-relheight 0
  -relwidth 0
-relx
  0
-rely
  0 The above four floating-point numbers define a rectangular bar (similar to the Tk placer geometry manager) relative to the remaining area inside of a possibly fat outline. Negative numbers or values greater than 1 are valid. Only the part of the bar inside the «sticker» is drawn, if any. The bar is not drawn if either -relwidth or -relheight or both are negative. -relx 0 -rely 0 is upper left.
-space
  0 Distance as accepted by Tk_GetPixel between repeatedly drawn text or 0 if text is to be drawn only once.
-stipple {}
  Bitmap as accepted by Tk_GetBitmap for filling the rectangle with a stipple pattern or empty string for solid background. Without -fill there's no effect.
-tags
  {} List of tag names. May be empty.
-text
  {} String of characters to be displayed as text. May be empty. Text is always drawn solid regardless of -stipple.
-width
  0 Width as accepted by Tk_GetPixel for drawing the outline.
-orient
  horizontal Specify text orientation as either «horizontal" or «vertical". May be abbreviated.
-maxheight 32767
  -maxwidth 0 -minheight 32767 -minwidth 0 The above four values as accepted by Tk_GetPixel suppress the drawing of the whole sticker if it is too small or too large.
NOTES:

Text characters are always entirely drawn or omitted; there are no clipped partially drawn characters. This works both for fixed and proportional fonts.

Note that the bar specified with -relx, -rely, -relwidth, -relheight does *not* automatically rotate via -orient vertical unlike the text. If you need this, you may compute the transformation in a Tcl procedure.

Hint: The -anchor option supersedes -justify of a canvas text item.

Not implemented: Splitting up long text into multiple lines. In case of a newline either the first or last line will be drawn depending on -lefttrunc.

The following canvas widget commands (for text items) are not supported: - dchars, focus, icursor, index, insert, select.

## Stripchart Items

Stripchart items are used to display measured data. They show values in a X-Y diagram which is scaled automatically. Scale lines indicate the current scale value. A stripchart object is represented by a Tcl list containing four elements:

canvas-pathName create stripchart x1 y1 x2 y2 ?option value option value ...?

The arguments x1, y1, x2, and y2 give the coordinates of two diagonally opposite corners of the rectangle (the rectangle will include its upper and left edges but not its lower or right edges). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure widget commands to change the item's configuration.

The Stripchart Item has full support for Tk canvas Postscript generation.

USAGE
-background
  {} If empty the item is transparent otherwise opaque with the choosen color.
-fill
  black The color of each strip can be changed with this option. Choosing no color {} makes the strip transparent and a line will be drawn in the «-stripline» color.
-jumpscroll
  5 After have been filled by the first time the stripchart is moved by the «jumpscroll value" left. New values are allways insert to the right side.
-outline
  black With «outline» the color of the surrounding item frame is choosen. No value {} means no frame.
-scaleline
  black If one of the shown strips is greater than the «scalevalue» the scalevalue is automatically increased and a scaleline is drawn. An empty value disables the scalline.
-scalelinestyle 4
  The scalline can be dashed: 4 means: 4 dots shown, 4 dots empty. (0 == undashed)
-scalevalue
  100.0 This floating point value relates to the max Y value, before a scaleline is drawn.
-stripline
  {} The color of the envelop is choosen with this option. An empty value disables the scalline.
-tags
  {} List of tag names. May be empty.
-values
  {} A list of floating point values is aoutomatically allocated. The listlenght equals the following formula when one times filled : «X dimension -jumpscrol value - 2" New values are inserted at the end.
-selected
  0 Special option for usage within the TkIned package.

## Barchart Items

Barchart items are used to display measured data. They show a set of values in a barchart diagram. Scale lines indicate the current scale value. A barchart object is represented by a Tcl list containing four elements:

canvas-pathName create barchart x1 y1 x2 y2 ?option value option value ...?

The arguments x1, y1, x2, and y2 give the coordinates of two diagonally opposite corners of the rectangle (the rectangle will include its upper and left edges but not its lower or right edges). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure widget commands to change the item's configuration.

The Barpchart Item has full support for Tk canvas Postscript generation.

USAGE
-autocolor
  0 This boolean value «autocolors» the barchart item. A scheme of 6 colors is compiled in.
-background
  {} If empty the item is transparent otherwise opaque with the choosen color.
-barline
  black If the «value» is greater than the «scalevalue", the scalevalue is automatically increased and a scaleline is drawn. An empty value disables the scalline.
-fill
  {} The color of each strip can be changed with this option. Choosing no color {} makes the bar transparent and a line will be drawn in the «-scaleline» color.
-outline
  black With «outline» the color of the surrounding item frame is choosen. No value {} means no frame.
-scaleline
  black If the bar value is greater than the «scalevalue" the scalevalue is automatically increased and a scaleline is drawn. An empty value disables the scalline.
-scalelinestyle 4
  The scalline can be dashed: 4 means: 4 dots shown, 4 dots empty. (0 == undashed)
-scalevalue
  100.0 This floating point value relates to the max Y value, before a scaleline is drawn.
-tags
  {} List of tag names. May be empty.
-values
  {} A list of one floating point value is aoutomatically allocated.
-selected
  0 Special option for usage within the TkIned package.

## Bindings

In the current implementation, new canvases are not given any default behavior: you'll have to execute explicit Tcl commands to give the canvas its behavior.

## Credits

Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's ezd program. Ezd provides structured graphics in a Scheme environment and preceded canvases by a year or two. Its simple mechanisms for placing and animating graphical objects inspired the functions of canvases.

## Keywords

canvas, widget

Table of Contents

- Name
- Synopsis
- Standard Options
- Overview of Item Types
- Common Item Options
- Sticker Items
- Stripchart Items
- Barchart Items
- Bindings
- Credits
- Keywords