Tk Source Code

# graph(n) -- 2D graph for plotting X-Y coordinate data

*   [SYNOPSIS](#SYNOPSIS)  
*   [STANDARD OPTIONS](#STANDARD-OPTIONS)  
  [-background or -bg, background, Background](options.htm#M-background)  
  [-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)  
  [-cursor, cursor, Cursor](options.htm#M-cursor)  
  [-foreground or -fg, foreground, Foreground](options.htm#M-foreground)  
  [-height, height, Height](options.htm#M-height)  
  [-width, width, Width](options.htm#M-width)  
*   [WIDGET-SPECIFIC OPTIONS](#WIDGET-SPECIFIC-OPTIONS)  
  [-aspect, aspect, Aspect](#-aspect) *width/height*  
  [-barmode, barMode, BarMode](#-barmode)  
  [-barwidth, barWidth, BarWidth](#-barwidth)  
  [-baseline, baseline, Baseline](#-baseline)  
  [-bottommargin, bottomMargin, Margin](#-bottommargin) *pixels*  
  [-bottomvariable, bottomVariable, BottomVariable](#-bottomvariable)  
  [-bufferelements, bufferElements, BufferElements](#-bufferelements) *boolean*  
  [-buffergraph, bufferGraph, BufferGraph](#-buffergraph)  
  [-class, class, Class](options.htm#M-class)  
  [-font, font, Font](#-font) *fontName*  
  [-halo, halo, Halo](#-halo) *pixels*  
  [-highlightbackground, highlightBackground, HighlightBackground](#-highlightbackground)  
  [-highlightcolor, highlightColor, HighlightColor](#-highlightcolor)  
  [-highlightthickness, highlightThickness, HighlightThickness](#-highlightthickness)  
  [-invertxy, invertXY, InvertXY](#-invertxy) *boolean*  
  [-justify, justify, Justify](#-justify) *justify*  
  [-leftmargin or -lm, leftMargin, Margin](#-leftmargin) *pixels*  
  [-leftvariable, leftVariable, LeftVariable](#-leftvariable)  
  [-plotbackground, plotBackground, Background](#-plotbackground) *color*  
  [-plotborderwidth, plotBorderWidth, BorderWidth](#-plotborderwidth) *pixels*  
  [-plotpadx, plotPadX, PlotPad](#-plotpadx) *pad*  
  [-plotpady, plotPadY, PlotPad](#-plotpadx) *pad*  
  [-plotrelief, plotRelief, Relief](#-plotrelief) *relief*  
  [-relief, relief, Relief](#-relief) *relief*  
  [-rightmargin or -rm, rightMargin, Margin](#-rightmargin) *pixels*  
  [-rightvariable, rightVariable, RightVariable](#-rightvariable)  
  [-shadow, shadow, Shadow](#-shadow)  
  [-style, style, Style](#-style) *line|bar|strip*  
  [-takefocus, takeFocus, TakeFocus](#-takefocus)  
  [-tile, tile, Tile](#-tile)  
  [-title, title, Title](#-title) *text|image*  
  [-topmargin or -tm, topMargin, Margin](#-topmargin) *pixels*  
  [-topvariable, topVariable, TopVariable](#-topvariable)  
*   [DESCRIPTION](#DESCRIPTION)  
*   [WIDGET COMMAND](#WIDGET-COMMAND)  
  [*pathName* **axis**](#pathName-axis) *operation ?arg?...*  
  [*pathName* **binding**](#pathName-binding) *?crosshairs? ?findelement? ?legend? ?zoom?*  
  [*pathName* **bar**](#pathName-bar) *elemName ?option value?...*  
  [*pathName* **cget**](#pathName-cget) *option*  
  [*pathName* **configure**](#pathName-configure) *?option value?...*  
  [*pathName* **crosshairs**](#pathName-crosshairs) *operation ?arg?*  
  [*pathName* **element**](#pathName-element) *operation ?arg?...*  
  [*pathName* **extents**](#pathName-extents) *item*  
  [*pathName* **grid**](#pathName-grid) *operation ?arg?...*  
  [*pathName* **invtransform**](#pathName-invtransform) *winX winY*  
  [*pathName* **inside**](#pathName-inside) *x y*  
  [*pathName* **legend**](#pathName-legend) *operation ?arg?...*  
  [*pathName* **line**](#pathName-line) *operation arg...*  
  [*pathName* **marker**](#pathName-marker) *operation ?arg?...*  
  [*pathName* **postscript**](#pathName-postscript) *operation ?arg?...*  
  [*pathName* **snap**](#pathName-snap) *?switches? outputName*  
  [*pathName* **transform**](#pathName-transform) *x y*  
  [*pathName* **xaxis**](#pathName-xaxis) *operation ?arg?...*  
  [*pathName* **x2axis**](#pathName-x2axis) *operation ?arg?...*  
  [*pathName* **yaxis**](#pathName-yaxis) *operation ?arg?...*  
  [*pathName* **y2axis**](#pathName-y2axis) *operation ?arg?...*  
* [AXIS COMPONENT](#AXIS-COMPONENT)  
  [*pathName* **axis bind**](#pathName-axis-bind) *tagName ?sequence? ?command?*  
  [*pathName* **axis cget**](#pathName-axis-cget) *axisName option*  
  [*pathName* **axis configure**](#pathName-axis-configure) *axisName ?axisName?... ?option value?...*  
  [*pathName* **axis create**](#pathName-axis-create) *axisName ?option value?...*  
  [*pathName* **axis delete**](#pathName-axis-delete) *?axisName?...*  
  [*pathName* **axis invtransform**](#pathName-axis-invtransform) *axisName value*  
  [*pathName* **axis limits**](#pathName-axis-limits) *axisName*  
  [*pathName* **axis names**](#pathName-axis-names) *?pattern?...*  
  [*pathName* **axis transform**](#pathName-axis-transform) *axisName value*  
  [*pathName* **axis view**](#pathName-axis-view) *axisName*  
* [CROSSHAIRS COMPONENT](#)  
  [*pathName* **crosshairs cget**](#pathName-crosshairs-cget) *option*  
  [*pathName* **crosshairs configure**](#pathName-crosshairs-configure) *?option value?...*  
  [*pathName* **crosshairs off**](#pathName-crosshairs-off)  
  [*pathName* **crosshairs on**](#pathName-crosshairs-on)  
  [*pathName* **crosshairs toggle**](#pathName-crosshairs-toggle)  
* [ELEMENT COMPONENT](#ELEMENT-COMPONENT)  
  [*pathName* **element activate**](#pathName-element-activate) *elemName ?index?...*  
  [*pathName* **element bind**](#pathName-element-bind) *tagName ?sequence? ?command?*  
  [*pathName* **element cget**](#pathName-element-cget) *elemName option*  
  [*pathName* **element closest**](#pathName-element-closest) *x y varName ?option value?... ?elemName?...*  
  [*pathName* **element configure**](#pathName-element-configure) *elemName ?elemName... ?option value?...*  
  [*pathName* **element create**](#pathName-element-create) *elemName ?option value?...*  
  [*pathName* **element deactivate**](#pathName-element-deactivate) *elemName ?elemName?...*  
  [*pathName* **element delete**](#pathName-element-delete) *?elemName?...*  
  [*pathName* **element exists**](#pathName-element-exists) *elemName*  
  [*pathName* **element names**](#pathName-element-names) *?pattern?...*  
  [*pathName* **element show**](#pathName-element-show) *?nameList?*  
  [*pathName* **element type**](#pathName-element-type) *elemName*  
* [GRID COMPONENT](#GRID-COMPONENT)  
  [*pathName* **grid cget**](#pathName-grid-cget) *option*  
  [*pathName* **grid configure**](#pathName-grid-configure) *?option value?...*  
  [*pathName* **grid off**](#pathName-grid-off)  
  [*pathName* **grid on**](#pathName-grid-on)  
  [*pathName* **grid toggle**](#pathName-grid-toggle)  
* [LEGEND COMPONENT](#LEGEND-COMPONENT)  
  [*pathName* **legend activate**](#pathName-legend-activate) *pattern...*  
  [*pathName* **legend bind**](#pathName-legend-bind) *tagName ?sequence? ?command?*  
  [*pathName* **legend cget**](#pathName-legend-cget) *option*  
  [*pathName* **legend configure**](#pathName-legend-configure) *?option value?...*  
  [*pathName* **legend deactivate**](#pathName-legend-deactivate) *pattern...*  
  [*pathName* **legend get**](#pathName-legend-get) *pos*  
* [PEN COMPONENT](#PEN-COMPONENT)  
  [*pathName* **pen cget**](#pathName-pen-cget) *penName option*  
  [*pathName* **pen configure**](#pathName-pen-configure) *penName ?penName... ?option value?...*  
  [*pathName* **pen create**](#pathName-pen-create) *penName ?option value?...*  
  [*pathName* **pen delete**](#pathName-pen-delete) *?penName?...*  
  [*pathName* **pen names**](#pathName-pen-names) *?pattern?...*  
* [POSTSCRIPT COMPONENT](#POSTSCRIPT-COMPONENT)  
  [*pathName* **postscript cget**](#pathName-postscript-cget) *option*  
  [*pathName* **postscript configure**](#pathName-postscript-configure) *?option value?...*  
  [*pathName* **postscript output**](#pathName-postscript-output) *?fileName? ?option value?...*  
* [MARKER COMPONENT](#MARKER-COMPONENT)  
  [*pathName* **marker after**](#pathName-marker-after) *markerId ?afterId?*  
  [*pathName* **marker before**](#pathName-marker-before) *markerId ?beforeId?*  
  [*pathName* **marker bind**](#pathName-marker-bind) *tagName ?sequence? ?command?*  
  [*pathName* **marker cget**](#pathName-marker-cget) *option*  
  [*pathName* **marker configure**](#pathName-marker-configure) *markerId ?option value?...*  
  [*pathName* **marker create**](#pathName-marker-create) *type ?option value?...*  
  [*pathName* **marker delete**](#pathName-marker-delete) *?name?...*  
  [*pathName* **marker exists**](#pathName-marker-exists) *markerId*  
  [*pathName* **marker names**](#pathName-marker-names) *?pattern?*  
  [*pathName* **marker type**](#pathName-marker-type) *markerId*  
  [BITMAP MARKERS](#BITMAP-MARKERS)  
  [*pathName* **marker create bitmap**](#pathName-marker-create-bitmap) *?option value?...*  
  [IMAGE MARKERS](#IMAGE-MARKERS)  
  [*pathName* **marker create image**](#pathName-marker-create-image) *?option value?...*  
  [LINE MARKERS](#LINE-MARKERS)  
  [*pathName* **marker create line**](#pathName-marker-create-line) *?option value?...*  
  [POLYGON MARKERS](#POLYGON-MARKERS)  
  [*pathName* **marker create polygon**](#pathName-marker-create-polygon) *?option value?...*  
  [TEXT MARKERS](#TEXT-MARKERS)  
  [*pathName* **marker create text**](#pathName-marker-create-text) *?option value?...*  
  [WINDOW MARKERS](#WINDOW-MARKERS)  
  [*pathName* **marker create window**](#pathName-marker-create-window) *?option value?...*  
*   [GRAPH COMPONENT BINDINGS](#GRAPH-COMPONENT-BINDINGS)  
*   [C LANGUAGE API](#[C-LANGUAGE-API)  
*   [SPEED TIPS](#SPEED-TIPS)  
*   [LIMITATIONS](#LIMITATIONS)  
*   [EXAMPLE](#EXAMPLE)  
*   [CREDITS](#CREDITS)  
*   [KEYWORDS](#KEYWORDS)  
*   [COPYRIGHT](#COPYRIGHT)  

<a name="SYNOPSIS"></a>
## SYNOPSIS 

**graph** *pathName ?-style line|bar|strip? ?option value?...*

The graph command creates a new window pathName and makes it into a graph widget. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist. Additional options may be specified on the command line or in the option database to configure aspects of the graph such as its colors and font. See the configure operation below for the exact details about what option and value pairs are valid.

The *-style* option can only be set on creation time of the new window. The option control the appearance of the widget. Default value is "line".

If successful, graph returns the path name of the widget. It also creates a new Tcl command by the same name. You can use this command to invoke various operations that query or modify the graph. The general form is:

**pathName** *operation ?arg?...*

Both operation and its arguments determine the exact behavior of the command. The operations available for the graph are described in the section.

The command can also be used to access components of the graph.

**pathName component** *operation ?arg?...*

A graph is composed of several components: coordinate axes, data elements, legend, grid, cross hairs, postscript, and annotation markers. Instead of one big set of configuration options and operations, the graph is partitioned, where each component has its own configuration options and operations that specifically control that aspect or part of the graph.

The operation, now located after the name of the component, is the function to be performed on that component. Each component has its own set of operations that manipulate that component. They will be described below in their own sections.

<a name="STANDARD-OPTIONS"></a>
## STANDARD OPTIONS

[-background or -bg, background, Background](options.htm#M-background) This includes the margins and legend, but not the plotting area.  
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)  
[-cursor, cursor, Cursor](options.htm#M-cursor)  
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)  
[-height, height, Height](options.htm#M-height) The default is 4i.  
[-width, width, Width](options.htm#M-width) The default is 5i.  

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

<a name="WIDGET-SPECIFIC-OPTIONS"></a>
## WIDGET-SPECIFIC OPTIONS

<a name="-aspect"></a>
Command-Line Name: **-aspect**  
Database Name: **aspect**  
Database Class: **Aspect**

> > Force a fixed aspect ratio of width/height, a floating point number.

<a name="-barmode"></a>
Command-Line Name: **-barmode**  
Database Name: **barMode**  
Database Class: **BarMode**

<a name="-barwidth"></a>
Command-Line Name: **-barwidth**  
Database Name: **barWidth**  
Database Class: **BarWidth**

<a name="-baseline"></a>
Command-Line Name: **-baseline**  
Database Name: **baseline**  
Database Class: **Baseline**

<a name="-bottommargin"></a>
Command-Line Name: **-bottommargin or -bm**  
Database Name: **bottomMargin**  
Database Class: **Margin**

> > If non-zero, overrides the computed size of the margin extending below the X-coordinate axis. If pixels is 0, the automatically computed size is used. The default is 0.

<a name="-bottomvariable"></a>
Command-Line Name: **-bottomvariable**  
Database Name: **bottomVariable**  
Database Class: **BottomVariable**

<a name="-bufferelements"></a>
Command-Line Name: **-bufferelements**  
Database Name: **bufferElements**  
Database Class: **BufferElements**

> > Indicates whether an internal pixmap to buffer the display of data elements should be used. If boolean is true, data elements are drawn to an internal pixmap. This option is especially useful when the graph is redrawn frequently while the remains data unchanged (for example, moving a marker across the plot). See the section. The default is 1.

<a name="-buffergraph"></a>
Command-Line Name: **-buffergraph**  
Database Name: **bufferGraph**  
Database Class: **BufferGraph**

<a name="-class"></a>
Command-Line Name: **-class**  
Database Name: **class**  
Database Class: **Class**

> > Define class for use in getting values from option database.

<a name="-font"></a>
Command-Line Name: **-font**  
Database Name: **font**  
Database Class: **Font**

> > Specifies the font of the graph title. The default is `*-Helvetica-Bold-R-Normal-*-18-180-*`.

<a name="-halo"></a>
Command-Line Name: **-halo**  
Database Name: **halo**  
Database Class: **Halo**

> > Specifies a maximum distance to consider when searching for the closest data point (see the element's closest operation below). Data points further than pixels away are ignored. The default is 0.5i.

<a name="-highlightbackground"></a>
Command-Line Name: **-highlightbackground**  
Database Name: **highlightBackground**  
Database Class: **HighlightBackground**

<a name="-highlightcolor"></a>
Command-Line Name: **-highlightcolor**  
Database Name: **highlightColor**  
Database Class: **HighlightColor**

<a name="-highlightthickness"></a>
Command-Line Name: **-highlightthickness**  
Database Name: **highlightThickness**  
Database Class: **HighlightThickness**

<a name="-invertxy"></a>
Command-Line Name: **-invertxy**  
Database Name: **invertXY**  
Database Class: **InvertXY**

> > Indicates whether the placement X-axis and Y-axis should be inverted. If boolean is true, the X and Y axes are swapped. The default is 0.

<a name="-justify"></a>
Command-Line Name: **-justify**  
Database Name: **justify**  
Database Class: **Justify**

> > Specifies how the title should be justified. This matters only when the title contains more than one line of text. Justify must be left, right, or center. The default is center.

<a name="-leftmargin"></a>
Command-Line Name: **-leftmargin or -lm**  
Database Name: **leftMargin**  
Database Class: **Margin**

> > If non-zero, overrides the computed size of the margin extending from the left edge of the window to the Y-coordinate axis. If pixels is 0, the automatically computed size is used. The default is 0.

<a name="-leftvariable"></a>
Command-Line Name: **-leftvariable**  
Database Name: **leftVariable**  
Database Class: **LeftVariable**

<a name="-plotbackground"></a>
Command-Line Name: **-plotbackground**  
Database Name: **plotBackground**  
Database Class: **Background**

> > Specifies the background color of the plotting area. The default is white.

<a name="-plotborderwidth"></a>
Command-Line Name: **-plotborderwidth**  
Database Name: **plotBorderWidth**  
Database Class: **BorderWidth**

> > Sets the width of the 3-D border around the plotting area. The -plotrelief option determines if a border is drawn. The default is 2.

<a name="-plotpadx"></a>
Command-Line Name: **-plotpadx**  
Database Name: **plotPadX**  
Database Class: **PlotPad**


> > Sets the amount of padding to be added to the left and right sides of the plotting area. Pad can be a list of one or two screen distances. If pad has two elements, the left side of the plotting area entry is padded by the first distance and the right side by the second. If pad is just one distance, both the left and right sides are padded evenly. The default is 8.

<a name="-plotpady"></a>
Command-Line Name: **-plotpady**  
Database Name: **plotPadY**  
Database Class: **PlotPad**

> > Sets the amount of padding to be added to the top and bottom of the plotting area. Pad can be a list of one or two screen distances. If pad has two elements, the top of the plotting area is padded by the first distance and the bottom by the second. If pad is just one distance, both the top and bottom are padded evenly. The default is 8.

> **-plotrelief**
<a name="-plotrelief"></a>
Command-Line Name: **-plotrelief**  
Database Name: **plotRelief**  
Database Class: **Relief**

> > Specifies the 3-D effect for the plotting area. Relief specifies how the interior of the plotting area should appear relative to rest of the graph; for example, raised means the plot should appear to protrude from the graph, relative to the surface of the graph. The default is sunken.

> **-relief** *relief*
<a name="-relief"></a>
Command-Line Name: **-relief**  
Database Name: **relief**  
Database Class: **Relief**

> > Specifies the 3-D effect for the graph widget. Relief specifies how the graph should appear relative to widget it is packed into; for example, raised means the graph should appear to protrude. The default is flat.

<a name="-rightmargin"></a>
Command-Line Name: **-rightmargin**  
Database Name: **rightMargin**  
Database Class: **Margin**

> > If non-zero, overrides the computed size of the margin extending from the plotting area to the right edge of the window. By default, the legend is drawn in this margin. If pixels is 0, the automatically computed size is used. The default is 0.

<a name="-rightvariable"></a>
Command-Line Name: **-rightvariable**  
Database Name: **rightVariable**  
Database Class: **RightVariable**

<a name="-shadow"></a>
Command-Line Name: **-shadow**  
Database Name: **shadow**  
Database Class: **Shadow**

<a name="-style"></a>
Command-Line Name: **-style**  
Database Name: **style**  
Database Class: **Style**

The option can only be set on creation time of the new window. The option control the appearance of the widget. Default value is **line**.

> **line**

> > Display X-Y plotchart

> **bar**

> > Display barchart.

> **strip**

> > Display stripchart.

> **-takefocus** *focus*
<a name="-takefocus"></a>
Command-Line Name: **-takefocus**  
Database Name: **takeFocus**  
Database Class: **TakeFocus**

> > Provides information used when moving the focus from window to window via keyboard traversal (e.g., Tab and Shift-Tab). If focus is 0, this means that this window should be skipped entirely during keyboard traversal. 1 means that the this window should always receive the input focus. An empty value means that the traversal scripts make the decision whether to focus on the window. The default is "".

<a name="-tile"></a>
Command-Line Name: **-tile**  
Database Name: **tile**  
Database Class: **Title**

> **image**

> > Specifies a tiled background for the widget. If image isn't "", the background is tiled using image. Otherwise, the normal background color is drawn (see the -background option). Image must be an image created using the Tk image command. The default is "".

> **text**

> > Sets the title to text. If text is "", no title will be displayed.

<a name="-topmargin"></a>
Command-Line Name: **-topmargin**  
Database Name: **topMargin**  
Database Class: **Margin**

> > If non-zero, overrides the computed size of the margin above the x2 axis. If pixels is 0, the automatically computed size is used. The default is 0.

<a name="-topvariable"></a>
Command-Line Name: **-topvariable**  
Database Name: **topVariable**  
Database Class: **TopVariable**

<a name="DESCRIPTION"></a>
## DESCRIPTION 

The graph command creates a new window for plotting two-dimensional data (X-Y coordinates). Data points are plotted in a rectangular area displayed in the center of the new window. This is the plotting area. The coordinate axes are drawn in the margins around the plotting area. By default, the legend is displayed in the right margin. The title is displayed in top margin. They allow you to customize the look and feel of the graph.

The graph widget is composed of several components: coordinate axes, data elements, legend, grid, cross hairs, pens, postscript, and annotation markers.

**axis**
    The graph has four standard axes (x, x2, y, and y2), but you can create and display any number of axes. Axes control what region of data is displayed and how the data is scaled. Each axis consists of the axis line, title, major and minor ticks, and tick labels. Tick labels display the value at each major tick.

**crosshairs**
    Cross hairs are used to position the mouse pointer relative to the X and Y coordinate axes. Two perpendicular lines, intersecting at the current location of the mouse, extend across the plotting area to the coordinate axes.

**element**
    An element represents a set of data points. Elements can be plotted with a symbol at each data point and lines connecting the points. The appearance of the element, such as its symbol, line width, and color is configurable.

**grid**
    Extends the major and minor ticks of the X-axis and/or Y-axis across the plotting area.

**legend**
    The legend displays the name and symbol of each data element. The legend can be drawn in any margin or in the plotting area.

**marker**
    Markers are used annotate or highlight areas of the graph. For example, you could use a polygon marker to fill an area under a curve, or a text marker to label a particular data point. Markers come in various forms: text strings, bitmaps, connected line segments, images, polygons, or embedded widgets.

**pen**
    Pens define attributes (both symbol and line style) for elements. Data elements use pens to specify how they should be drawn. A data element may use many pens at once. Here, the particular pen used for a data point is determined from each element's weight vector (see the element's -weight and -style options).

**postscript**
    The widget can generate encapsulated PostScript output. This component has several options to configure how the PostScript is generated.

<a name="WIDGET-COMMAND"></a>
## WIDGET COMMAND

<a name="pathName-axis"></a>
**pathName axis** *operation ?arg?...*

> See the [AXIS COMPONENT](#AXIS-COMPONENT) section.

<a name="pathName-bar"></a>
**pathName bar** *elemName ?option value?...*

> Creates a new barchart element elemName. It's an error if an element elemName already exists. See the manual for barchart for details about what option and value pairs are valid. TODO

name="pathName-binding"></a>
**pathName binding** *?crosshairs? ?findelement? ?legend? ?zoom?*

The procedure allows the setting of some default bindings. It will add bindings if a name is given and remove bindings if a name is not given.

> If given then the following bindings will be applied:

> *crosshairs*

> > <Any-Motion> will draw crosshairs in the graph window. Leaving the widget will remove the crosshairs.

> *findelement*

> > <Control-ButtonPress-2> This will display informations of the nearest element point.  
> > <Control-Buttonrelease-2> This will remove the displayed informations.  

> *legend* 

> > <Enter> an element will activate the elment entry in the legend window.  
> > <Leave> an element will deactivate the element entry in the legend window.  
> > <ButtonPress-1> will select the element entry in the legend window.  

> *zoom*

> > <ButtonPress-1> Create first and second point of a zooming window. When the second point is created the graph will be zoomed to the new window and the old window will be remembered.  
> > <ButtonPress-3> Undo the last zoom operation.  

<a name="pathName-cget"></a>
**pathName cget** *option*

> Returns the current value of the configuration option given by option. Option may be any option described below for the configure operation.

<a name="pathName-configure"></a>
**pathName configure** *?option value?...*

> Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for pathName (see [Tk_ConfigureInfo][] for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **graph** command. 

<a name="pathName-crosshairs"></a>
**pathName crosshairs** *operation ?arg?*

> See the [CROSSHAIRS COMPONENT](#CROSSHAIRS-COMPONENT) section.

<a name="pathName-element"></a>
**pathName element** *operation ?arg?...*

> See the [ELEMENT COMPONENT](#ELEMENT-COMPONENT) section.

<a name="pathName-extents"></a>
**pathName extents** *item*

> Returns the size of a particular item in the graph. Item must be either leftmargin, rightmargin, topmargin, bottommargin, plotwidth, or plotheight.

<a name="pathName-grid"></a>
**pathName grid** *operation ?arg?...*

> See the [GRID COMPONENT](#GRID-COMPONENT) section.

<a name="pathName-invtransform"></a>
**pathName invtransform** *winX winY*

> Performs an inverse coordinate transformation, mapping window coordinates back to graph coordinates, using the standard X-axis and Y-axis. Returns a list of containing the X-Y graph coordinates.

<a name="pathName-inside"></a>
**pathName inside** *x y*

> Returns 1 is the designated screen coordinate (x and y) is inside the plotting area and 0 otherwise.

<a name="pathName-legend"></a>
**pathName legend** *operation ?arg?...*

> See the [LEGEND COMPONENT](#LEGEND-COMPONENT) section.

<a name="pathName-line"></a>
**pathName line** *operation arg...*

> The operation is the same as element.

<a name="pathName-marker"></a>
**pathName marker** *operation ?arg?...*

> See the [MARKER COMPONENT](#MARKER-COMPONENT) section.

<a name="pathName-postscript"></a>
**pathName postscript** *operation ?arg?...*

> See the [POSTSCIPT COMPONENT](#POSTSCRIPT-COMPONENT)section.

<a name="pathName-snap"></a>
**pathName snap** *?switches? outputName*

> Takes a snapshot of the graph, saving the output in outputName. The following switches are available.

> **-format** *format*

> > Specifies how the snapshot is output. Format may be one of the following listed below. The default is photo.

> > **photo**

> > > Saves a Tk photo image. OutputName represents the name of a Tk photo image that must already have been created.

> > **wmf**

> > > Saves an Aldus Placeable Metafile. OutputName represents the filename where the metafile is written. If outputName is CLIPBOARD, then output is written directly to the Windows clipboard. This format is available only under Microsoft Windows.

> > **emf**

> > > Saves an Enhanced Metafile. OutputName represents the filename where the metafile is written. If outputName is CLIPBOARD, then output is written directly to the Windows clipboard. This format is available only under Microsoft Windows.

> **-height** *size*

> > Specifies the height of the graph. Size is a screen distance. The graph will be redrawn using this dimension, rather than its current window height.

> **-width** *size*

> > Specifies the width of the graph. Size is a screen distance. The graph will be redrawn using this dimension, rather than its current window width.

<a name="pathName-transform"></a>
**pathName transform** *x y*

> > Performs a coordinate transformation, mapping graph coordinates to window coordinates, using the standard X-axis and Y-axis. Returns a list containing the X-Y screen coordinates.

<a name="pathName-xaxis"></a>
**pathName xaxis** *operation ?arg?...*

<a name="pathName-x2axis"></a>
**pathName x2axis** *operation ?arg?...*

<a name="pathName-yaxis"></a>
**pathName yaxis** *operation ?arg?...*

<a name="pathName-y2axis"></a>
**pathName y2axis** *operation ?arg?...*

> See the [AXIS COMPONENT](#AXIS-COMPONENT) section.

<a name="AXIS-COMPONENT"></a>
## AXIS COMPONENT

Four coordinate axes are automatically created: two X-coordinate axes (x and x2) and two Y-coordinate axes (y, and y2). By default, the axis x is located in the bottom margin, y in the left margin, x2 in the top margin, and y2 in the right margin.

An axis consists of the axis line, title, major and minor ticks, and tick labels. Major ticks are drawn at uniform intervals along the axis. Each tick is labeled with its coordinate value. Minor ticks are drawn at uniform intervals within major ticks.

The range of the axis controls what region of data is plotted. Data points outside the minimum and maximum limits of the axis are not plotted. By default, the minimum and maximum limits are determined from the data, but you can reset either limit.

You can have several axes. To create an axis, invoke the axis component and its create operation.

> <code>
	# Create a new axis called "tempAxis"  
	.g axis create tempAxis  
</code>

You map data elements to an axis using the element's -mapy and -mapx configuration options. They specify the coordinate axes an element is mapped onto.

> <code>
	# Now map the tempAxis data to this axis.  
	.g element create "e1" -xdata $x -ydata $y -mapy tempAxis  
</code>

Any number of axes can be displayed simultaneously. They are drawn in the margins surrounding the plotting area. The default axes x and y are drawn in the bottom and left margins. The axes x2 and y2 are drawn in top and right margins. By default, only x and y are shown. Note that the axes can have different scales.

To display a different axis or more than one axis, you invoke one of the following components: xaxis, yaxis, x2axis, and y2axis. Each component has a use operation that designates the axis (or axes) to be drawn in that corresponding margin: xaxis in the bottom, yaxis in the left, x2axis in the top, and y2axis in the right.

> <code>
	# Display the axis tempAxis in the left margin.  
	.g yaxis use tempAxis  
</code>

The use operation takes a list of axis names as its last argument. This is the list of axes to be drawn in this margin.

You can configure axes in many ways. The axis scale can be linear or logarithmic. The values along the axis can either monotonically increase or decrease. If you need custom tick labels, you can specify a Tcl procedure to format the label any way you wish. You can control how ticks are drawn, by changing the major tick interval or the number of minor ticks. You can define non-uniform tick intervals, such as for time-series plots.

<a name="pathName-axis-bind"></a>
**pathName axis bind** *tagName ?sequence? ?command?*

> Associates command with tagName such that whenever the event sequence given by sequence occurs for an axis with this tag, command will be invoked. The syntax is similar to the bind command except that it operates on graph axes, rather than widgets. See the bind manual entry for complete details on sequence and the substitutions performed on command before invoking it.

> If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName. If the first character of command is + then command augments an existing binding rather than replacing it. If no command argument is provided then the command currently associated with tagName and sequence (it's an error occurs if there's no such binding) is returned. If both command and sequence are missing then a list of all the event sequences for which bindings have been defined for tagName.

<a name="pathName-axis-cget"></a>
**pathName axis cget** *axisName option*

> Returns the current value of the option given by option for axisName. Option may be any option described below for the axis configure operation.

<a name="pathName-axis-configure"></a>
**pathName axis configure** *axisName ?axisName?... ?option value?...*

> Queries or modifies the configuration options of axisName. Several axes can be changed. If option isn't specified, a list describing all the current options for axisName is returned. If option is specified, but not value, then a list describing option is returned. If one or more option and value pairs are specified, then for each pair, the axis option option is set to value. The following options are valid for axes.

> **-bindtags** *tagList*

> > Specifies the binding tags for the axis. TagList is a list of binding tag names. The tags and their order will determine how events for axes are handled. Each tag in the list matching the current event sequence will have its Tcl command executed. Implicitly the name of the element is always the first tag in the list. The default value is all.

> **-color** *color*

> > Sets the color of the axis and tick labels. The default is black.

> **-command** *prefix*

> > Specifies a Tcl command to be invoked when formatting the axis tick labels. Prefix is a string containing the name of a Tcl proc and any extra arguments for the procedure. This command is invoked for each major tick on the axis. Two additional arguments are passed to the procedure: the pathname of the widget and the current the numeric value of the tick. The procedure returns the formatted tick label. If "" is returned, no label will appear next to the tick. You can get the standard tick labels again by setting prefix to "". The default is "".

> > Please note that this procedure is invoked while the graph is redrawn. You may query configuration options. But do not them, because this can have unexpected results.

> **-descending** *boolean*

> > Indicates whether the values along the axis are monotonically increasing or decreasing. If boolean is true, the axis values will be decreasing. The default is 0.

> **-hide** *boolean*

> > Indicates if the axis is displayed. If boolean is false the axis will be displayed. Any element mapped to the axis is displayed regardless. The default value is 0.

> **-justify** *justify*

> > Specifies how the axis title should be justified. This matters only when the axis title contains more than one line of text. Justify must be left, right, or center. The default is center.

> **-limits** *formatStr*

> > Specifies a printf-like description to format the minimum and maximum limits of the axis. The limits are displayed at the top/bottom or left/right sides of the plotting area. FormatStr is a list of one or two format descriptions. If one description is supplied, both the minimum and maximum limits are formatted in the same way. If two, the first designates the format for the minimum limit, the second for the maximum. If "" is given as either description, then the that limit will not be displayed. The default is "".

> **-linewidth** *pixels*

> > Sets the width of the axis and tick lines. The default is 1 pixel.

> **-logscale** *boolean*

> > Indicates whether the scale of the axis is logarithmic or linear. If boolean is true, the axis is logarithmic. The default scale is linear.

> **-loose** *boolean*

> > Indicates whether the limits of the axis should fit the data points tightly, at the outermost data points, or loosely, at the outer tick intervals. If the axis limit is set with the -min or -max option, the axes are displayed tightly. If boolean is true, the axis range is "loose". The default is 0.

> **-majorticks** *majorList*

> > Specifies where to display major axis ticks. You can use this option to display ticks at non-uniform intervals. MajorList is a list of axis coordinates designating the location of major ticks. No minor ticks are drawn. If majorList is "", major ticks will be automatically computed. The default is "".

> **-max** *value*

> > Sets the maximum limit of axisName. Any data point greater than value is not displayed. If value is "", the maximum limit is calculated using the largest data value. The default is "".

> **-min** *value*

> > Sets the minimum limit of axisName. Any data point less than value is not displayed. If value is "", the minimum limit is calculated using the smallest data value. The default is "".

> **-minorticks** *minorList*

> > Specifies where to display minor axis ticks. You can use this option to display minor ticks at non-uniform intervals. MinorList is a list of real values, ranging from 0.0 to 1.0, designating the placement of a minor tick. No minor ticks are drawn if the -majortick option is also set. If minorList is "", minor ticks will be automatically computed. The default is "".

> **-rotate** *theta*

> > Specifies the how many degrees to rotate the axis tick labels. Theta is a real value representing the number of degrees to rotate the tick labels. The default is 0.0 degrees.

> **-scrollcommand** *command*

> > Specify the prefix for a command used to communicate with scrollbars for this axis, such as .sbar set.

> **-scrollmax** *value*

> > Sets the maximum limit of the axis scroll region. If value is "", the maximum limit is calculated using the largest data value. The default is "".

> **-scrollmin** *value*

> > Sets the minimum limit of axis scroll region. If value is "", the minimum limit is calculated using the smallest data value. The default is "".

> **-showticks** *boolean*

> > Indicates whether axis ticks should be drawn. If boolean is true, ticks are drawn. If false, only the axis line is drawn. The default is 1.

> **-stepsize** *value*

> > Specifies the interval between major axis ticks. If value isn't a valid interval (must be less than the axis range), the request is ignored and the step size is automatically calculated.

> **-subdivisions** *number*

> > Indicates how many minor axis ticks are to be drawn. For example, if number is two, only one minor tick is drawn. If number is one, no minor ticks are displayed. The default is 2.

> **-tickfont** *fontName*

> > Specifies the font for axis tick labels. The default is `*-Courier-Bold-R-Normal-*-100-*`.

> **-ticklength** *pixels*

> > Sets the length of major and minor ticks (minor ticks are half the length of major ticks). If pixels is less than zero, the axis will be inverted with ticks drawn pointing towards the plot. The default is 0.1i.

> **-title** *text*

> > Sets the title of the axis. If text is "", no axis title will be displayed.

> **-titlealternate** *boolean*

> > Indicates to display the axis title in its alternate location. Normally the axis title is centered along the axis. This option places the axis either to the right (horizontal axes) or above (vertical axes) the axis. The default is 0.

> **-titlecolor** *color*

> > Sets the color of the axis title. The default is black.

> **-titlefont** *fontName*

> > Specifies the font for axis title. The default is `*-Helvetica-Bold-R-Normal-*-14-140-*`.

Axis configuration options may be also be set by the option command. The resource class is Axis. The resource names are the names of the axes (such as x or x2).

> <code>
        option add *Graph.Axis.Color  blue
        option add *Graph.x.LogScale  true
        option add *Graph.x2.LogScale false
</code>

<a name="pathName-axis-create"></a>
**pathName axis create** *axisName ?option value?...*

> Creates a new axis by the name axisName. No axis by the same name can already exist. Option and value are described in above in the axis configure operation.

<a name="pathName-axis-delete"></a>
**pathName axis delete** *?axisName?...*

> Deletes the named axes. An axis is not really deleted until it is not longer in use, so it's safe to delete axes mapped to elements.

<a name="pathName-axis-invtransform"></a>
**pathName axis invtransform** *axisName value*

> Performs the inverse transformation, changing the screen coordinate value to a graph coordinate, mapping the value mapped to axisName. Returns the graph coordinate.

<a name="pathName-axis-limits"></a>
**pathName axis limits** *axisName*

> Returns a list of the minimum and maximum limits for axisName. The order of the list is min max.

<a name="pathName-axis-names"></a>
**pathName axis names** *?pattern?...*

> Returns a list of axes matching zero or more patterns. If no pattern argument is give, the names of all axes are returned.

<a name="pathName-axis-transform"></a>
**pathName axis transform** *axisName value*

> Transforms the coordinate value to a screen coordinate by mapping the it to axisName. Returns the transformed screen coordinate.

<a name="pathName-axis-view"></a>
**pathName axis view** *axisName*

> Change the viewable area of this axis. Use as an argument to a scrollbar's "-command".

The default axes are x, y, x2, and y2. But you can display more than four axes simultaneously. You can also swap in a different axis with use operation of the special axis components: xaxis, x2axis, yaxis, and y2axis.

> <code>
	.g create axis temp  
	.g create axis time  
	...  
	.g xaxis use temp  
	.g yaxis use time  
</code>

Only the axes specified for use are displayed on the screen.

The xaxis, x2axis, yaxis, and y2axis components operate on an axis location rather than a specific axis like the more general axis component does. They implicitly control the axis that is currently using to that location. By default, xaxis uses the x axis, yaxis uses y, x2axis uses x2, and y2axis uses y2. When more than one axis is displayed in a margin, it represents the first axis displayed.

<a name="CROSSHAIRS-COMPONENT"></a>
## CROSSHAIRS COMPONENT

Cross hairs consist of two intersecting lines (one vertical and one horizontal) drawn completely across the plotting area. They are used to position the mouse in relation to the coordinate axes. Cross hairs differ from line markers in that they are implemented using XOR drawing primitives. This means that they can be quickly drawn and erased without redrawing the entire graph.

The following operations are available for cross hairs:

<a name="pathName-crosshairs-cget"></a>
**pathName crosshairs cget** *option*

> Returns the current value of the cross hairs configuration option given by option. Option may be any option described below for the cross hairs configure operation.

<a name="pathName-crosshairs-configure"></a>
**pathName crosshairs configure** *?option value?...*

> Queries or modifies the configuration options of the cross hairs. If option isn't specified, a list describing all the current options for the cross hairs is returned. If option is specified, but not value, then a list describing option is returned. If one or more option and value pairs are specified, then for each pair, the cross hairs option option is set to value. The following options are available for cross hairs.

> **-color** *color*

> > Sets the color of the cross hairs. The default is black.

> **-dashes** *dashList*

> > Sets the dash style of the cross hairs. DashList is a list of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the cross hair lines. Each number must be between 1 and 255. If dashList is "", the cross hairs will be solid lines.

> **-hide** *boolean*

> > Indicates whether cross hairs are drawn. If boolean is true, cross hairs are not drawn. The default is yes.

> **-linewidth** *pixels*

> > Set the width of the cross hair lines. The default is 1.

> **-position** *pos*

> > Specifies the screen position where the cross hairs intersect. Pos must be in the form "@x,y", where x and y are the window coordinates of the intersection.

> Cross hairs configuration options may be also be set by the option command. The resource name and class are crosshairs and Crosshairs respectively.

> > <code>
        option add *Graph.Crosshairs.LineWidth 2  
        option add *Graph.Crosshairs.Color     red  
</code>

<a name="pathName-crosshairs-off"></a>
**pathName crosshairs off**

> Turns off the cross hairs.

<a name="pathName-crosshairs-on"></a>
**pathName crosshairs on**

> Turns on the display of the cross hairs.

<a name="pathName-crosshairs-toggle"></a>
**pathName crosshairs toggle**

> Toggles the current state of the cross hairs, alternately mapping and unmapping the cross hairs.

<a name="ELEMENT-COMPONENT"></a>
## ELEMENT COMPONENT

A data element represents a set of data. It contains x and y vectors containing the coordinates of the data points. Elements can be displayed with a symbol at each data point and lines connecting the points. Elements also control the appearance of the data, such as the symbol type, line width, color etc.

When new data elements are created, they are automatically added to a list of displayed elements. The display list controls what elements are drawn and in what order.

The following operations are available for elements.

<a name="pathName-element-activate"></a>
**pathName element activate** *elemName ?index?...*

> Specifies the data points of element elemName to be drawn using active foreground and background colors. ElemName is the name of the element and index is a number representing the index of the data point. If no indices are present then all data points become active.

<a name="pathName-element-bind"></a>
**pathName element bind** *tagName ?sequence? ?command?*

> Associates command with tagName such that whenever the event sequence given by sequence occurs for an element with this tag, command will be invoked. The syntax is similar to the bind command except that it operates on graph elements, rather than widgets. See the bind manual entry for complete details on sequence and the substitutions performed on command before invoking it.

> If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName. If the first character of command is + then command augments an existing binding rather than replacing it. If no command argument is provided then the command currently associated with tagName and sequence (it's an error occurs if there's no such binding) is returned. If both command and sequence are missing then a list of all the event sequences for which bindings have been defined for tagName.

<a name="pathName-element-cget"></a>
**pathName element cget** *elemName option*

> Returns the current value of the element configuration option given by option. Option may be any of the options described below for the element configure operation.

<a name="pathName-element-closest"></a>
**pathName element closest** *x y varName ?option value?... ?elemName?...*

> Searches for the data point closest to the window coordinates x and y. By default, all elements are searched. Hidden elements (see the -hide option is false) are ignored. You can limit the search by specifying only the elements you want to be considered. ElemName must be the name of an element that is not be hidden. VarName is the name of a Tcl array variable and will contain the search results: the name of the closest element, the index of the closest data point, and the graph coordinates of the point. Returns 0, if no data point within the threshold distance can be found, otherwise 1 is returned. The following option-value pairs are available.

> **-along** *direction*

> > Search for the closest element using the following criteria:

> > *x*

> > > Find closest element vertically from the given X-coordinate.

> > *y*

> > > Find the closest element horizontally from the given Y-coordinate.

> > *both*

> > > Find the closest element for the given point (using both the X and Y coordinates).

> **-halo** *pixels*

> > Specifies a threshold distance where selected data points are ignored. Pixels is a valid screen distance, such as 2 or 1.2i. If this option isn't specified, then it defaults to the value of the graph's -halo option.

> **-interpolate** *string*

> > Indicates whether to consider projections that lie along the line segments connecting data points when searching for the closest point. The default value is 0. The values for string are described below.

> > *no*

> > > Search only for the closest data point.

> > *yes*

> > > Search includes projections that lie along the line segments connecting the data points.

<a name="pathName-element-configure"></a>
**pathName element configure** *elemName ?elemName... ?option value?...*

> Queries or modifies the configuration options for elements. Several elements can be modified at the same time. If option isn't specified, a list describing all the current options for elemName is returned. If option is specified, but not value, then a list describing the option option is returned. If one or more option and value pairs are specified, then for each pair, the element option option is set to value. The following options are valid for elements.

> **-activepen** *penName*

> > Specifies pen to use to draw active element. If penName is "", no active elements will be drawn. The default is activeLine.

> **-bindtags** *tagList*

> > Specifies the binding tags for the element. TagList is a list of binding tag names. The tags and their order will determine how events are handled for elements. Each tag in the list matching the current event sequence will have its Tcl command executed. Implicitly the name of the element is always the first tag in the list. The default value is all.

> **-color** *color*

> > Sets the color of the traces connecting the data points.

> **-dashes** *dashList*

> > Sets the dash style of element line. DashList is a list of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the element line. Each number must be between 1 and 255. If dashList is "", the lines will be solid.

> **-data** *coordList*

> > Specifies the X-Y coordinates of the data. CoordList is a list of numeric expressions representing the X-Y coordinate pairs of each data point.

> **-fill** *color*

> > Sets the interior color of symbols. If color is "", then the interior of the symbol is transparent. If color is defcolor, then the color will be the same as the -color option. The default is defcolor.

> **-hide** *boolean*

> > Indicates whether the element is displayed. The default is no.

> **-label** *text*

> > Sets the element's label in the legend. If text is "", the element will have no entry in the legend. The default label is the element's name.

> **-linewidth** *pixels*

> > Sets the width of the connecting lines between data points. If pixels is 0, no connecting lines will be drawn between symbols. The default is 0.

> **-mapx** *xAxis*

> > Selects the X-axis to map the element's X-coordinates onto. XAxis must be the name of an axis. The default is x.

> **-mapy** *yAxis*

> > Selects the Y-axis to map the element's Y-coordinates onto. YAxis must be the name of an axis. The default is y.

> **-offdash** *color*

> > Sets the color of the stripes when traces are dashed (see the -dashes option). If color is "", then the "off" pixels will represent gaps instead of stripes. If color is defcolor, then the color will be the same as the -color option. The default is defcolor.

> **-outline** *color*

> > Sets the color or the outline around each symbol. If color is "", then no outline is drawn. If color is defcolor, then the color will be the same as the -color option. The default is defcolor.

> **-pen** *penname*

> > Set the pen to use for this element.

> **-outlinewidth** *pixels*

> > Sets the width of the outline bordering each symbol. If pixels is 0, no outline will be drawn. The default is 1.

> **-pixels** *pixels*

> > Sets the size of symbols. If pixels is 0, no symbols will be drawn. The default is 0.125i.

> **-scalesymbols** *boolean*

> > If boolean is true, the size of the symbols drawn for elemName will change with scale of the X-axis and Y-axis. At the time this option is set, the current ranges of the axes are saved as the normalized scales (i.e scale factor is 1.0) and the element is drawn at its designated size (see the -pixels option). As the scale of the axes change, the symbol will be scaled according to the smaller of the X-axis and Y-axis scales. If boolean is false, the element's symbols are drawn at the designated size, regardless of axis scales. The default is 0.

> **-smooth** *smooth*

> > Specifies how connecting line segments are drawn between data points. Smooth can be either linear, step, natural, or quadratic. If smooth is linear, a single line segment is drawn, connecting both data points. When smooth is step, two line segments are drawn. The first is a horizontal line segment that steps the next X-coordinate. The second is a vertical line, moving to the next Y-coordinate. Both natural and quadratic generate multiple segments between data points. If natural, the segments are generated using a cubic spline. If quadratic, a quadratic spline is used. The default is linear.

> **-styles** *styleList*

> > Specifies what pen to use based on the range of weights given. StyleList is a list of style specifications. Each style specification, in turn, is a list consisting of a pen name, and optionally a minimum and maximum range. Data points whose weight (see the -weight option) falls in this range, are drawn with this pen. If no range is specified it defaults to the index of the pen in the list. Note that this affects only symbol attributes. Line attributes, such as line width, dashes, etc. are ignored.

> **-symbol** *symbol*

> > Specifies the symbol for data points. Symbol can be either square, circle, diamond, plus, cross, splus, scross, triangle, "" (where no symbol is drawn), or a bitmap. Bitmaps are specified as "source ?mask?", where source is the name of the bitmap, and mask is the bitmap's optional mask. The default is circle.

> **-trace** *direction*

> > Indicates whether connecting lines between data points (whose X-coordinate values are either increasing or decreasing) are drawn. Direction must be increasing, decreasing, or both. For example, if direction is increasing, connecting lines will be drawn only between those data points where X-coordinate values are monotonically increasing. If direction is both, connecting lines will be draw between all data points. The default is both.

> **-weights** *wVec*

> > Specifies the weights of the individual data points. This, with the list pen styles (see the -styles option), controls how data points are drawn. WVec is the name of a graph vector or a list of numeric expressions representing the weights for each data point.

> **-xdata** *xVec*

> > Specifies the X-coordinates of the data. XVec is the name of a graph vector or a list of numeric expressions.

> **-ydata** *yVec*

> > Specifies the Y-coordinates of the data. YVec is the name of a graph vector or a list of numeric expressions.

> Element configuration options may also be set by the option command. The resource class is Element. The resource name is the name of the element.

> > <code>
        option add *Graph.Element.symbol line  
        option add *Graph.e1.symbol line  
</code>

<a name="pathName-element-create"></a>
**pathName element create** *elemName ?option value?...*

> Creates a new element elemName. It's an error is an element elemName already exists. If additional arguments are present, they specify options valid for the element configure operation.

<a name="pathName-element-deactivate"></a>
**pathName element deactivate** *elemName ?elemName?...*

> Deactivates all the elements matching pattern. Elements whose names match any of the patterns given are redrawn using their normal colors.

<a name="pathName-element-delete"></a>
**pathName element delete** *?elemName?...*

> Deletes all the named elements. The graph is automatically redrawn.

<a name="pathName-element-exists"></a>
**pathName element exists** *elemName*

> Returns 1 if an element elemName currently exists and 0 otherwise.

<a name="pathName-element-names"></a>
**pathName element names** *?pattern?...*

> Returns the elements matching one or more pattern. If no pattern is given, the names of all elements is returned.

<a name="pathName-element-show"></a>
**pathName element show** *?nameList?*

> Queries or modifies the element display list. The element display list designates the elements drawn and in what order. NameList is a list of elements to be displayed in the order they are named. If there is no nameList argument, the current display list is returned.

<a name="pathName-element-type"></a>
**pathName element type** *elemName*

> Returns the type of elemName. If the element is a bar element, the commands returns the string "bar", otherwise it returns "line".

<a name="GRID-COMPONENT"></a>
## GRID COMPONENT

Grid lines extend from the major and minor ticks of each axis horizontally or vertically across the plotting area. The following operations are available for grid lines.

<a name="pathName-grid-cget"></a>
**pathName grid cget** *option*

> Returns the current value of the grid line configuration option given by option. Option may be any option described below for the grid configure operation.

<a name="pathName-grid-configure"></a>
**pathName grid configure** *?option value?...*

> Queries or modifies the configuration options for grid lines. If option isn't specified, a list describing all the current grid options for pathName is returned. If option is specified, but not value, then a list describing option is returned. If one or more option and value pairs are specified, then for each pair, the grid line option option is set to value. The following options are valid for grid lines.

> **-color** *color*

> > Sets the color of the grid lines. The default is black.

> **-dashes** *dashList*

> > Sets the dash style of the grid lines. DashList is a list of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the grid lines. Each number must be between 1 and 255. If dashList is "", the grid will be solid lines.

> **-hide** *boolean*

> > Indicates whether the grid should be drawn. If boolean is true, grid lines are not shown. The default is yes.

> **-linewidth** *pixels*

> > Sets the width of grid lines. The default width is 1.

> **-mapx** *xAxis*

> > Specifies the X-axis to display grid lines. XAxis must be the name of an axis or "" for no grid lines. The default is "".

> **-mapy** *yAxis*

> > Specifies the Y-axis to display grid lines. YAxis must be the name of an axis or "" for no grid lines. The default is y.

> **-minor** *boolean*

> > Indicates whether the grid lines should be drawn for minor ticks. If boolean is true, the lines will appear at minor tick intervals. The default is 1.

> **-raised** *boolean*

> > Grid is to be raised or drawn over elements.

> Grid configuration options may also be set by the option command. The resource name and class are grid and Grid respectively.

> > <code>
        option add *Graph.grid.LineWidth 2  
        option add *Graph.Grid.Color     black  
</code>

<a name="pathName-grid-off"></a>
**pathName grid off**

> Turns off the display the grid lines.

<a name="pathName-grid-on"></a>
**pathName grid on**

> Turns on the display the grid lines.

<a name="pathName-grid-toggle"></a>
**pathName grid toggle**

> Toggles the display of the grid.

<a name="LEGEND-COMPONENT"></a>
## LEGEND COMPONENT

The legend displays a list of the data elements. Each entry consists of the element's symbol and label. The legend can appear in any margin (the default location is in the right margin). It can also be positioned anywhere within the plotting area.

The following operations are valid for the legend.

<a name="pathName-legend-activate"></a>
**pathName legend activate** *pattern...*

> Selects legend entries to be drawn using the active legend colors and relief. All entries whose element names match pattern are selected. To be selected, the element name must match only one pattern.

<a name="pathName-legend-bind"></a>
**pathName legend bind** *tagName ?sequence? ?command?*

> Associates command with tagName such that whenever the event sequence given by sequence occurs for a legend entry with this tag, command will be invoked. Implicitly the element names in the entry are tags. The syntax is similar to the bind command except that it operates on legend entries, rather than widgets. See the bind manual entry for complete details on sequence and the substitutions performed on command before invoking it.

> If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName. If the first character of command is + then command augments an existing binding rather than replacing it. If no command argument is provided then the command currently associated with tagName and sequence (it's an error occurs if there's no such binding) is returned. If both command and sequence are missing then a list of all the event sequences for which bindings have been defined for tagName.

<a name="pathName-legend-cget"></a>
**pathName legend cget** *option*

> Returns the current value of a legend configuration option. Option may be any option described below in the legend configure operation.

<a name="pathName-legend-configure"></a>
**pathName legend configure** *?option value?...*

> Queries or modifies the configuration options for the legend. If option isn't specified, a list describing the current legend options for pathName is returned. If option is specified, but not value, then a list describing option is returned. If one or more option and value pairs are specified, then for each pair, the legend option option is set to value. The following options are valid for the legend.

> **-activebackground** *color*

> > Sets the background color for active legend entries. All legend entries marked active (see the legend activate operation) are drawn using this background color.

> **-activeborderwidth** *pixels*

> > Sets the width of the 3-D border around the outside edge of the active legend entries. The default is 2.

> **-activeforeground** *color*

> > Sets the foreground color for active legend entries. All legend entries marked as active (see the legend activate operation) are drawn using this foreground color.

> **-activerelief** *relief*

> > Specifies the 3-D effect desired for active legend entries. Relief denotes how the interior of the entry should appear relative to the legend; for example, raised means the entry should appear to protrude from the legend, relative to the surface of the legend. The default is flat.

> **-anchor** *anchor*

> > Tells how to position the legend relative to the positioning point for the legend. This is dependent on the value of the -position option. The default is center.

> > *left* or *right*

> > > The anchor describes how to position the legend vertically.

> > *top* or *bottom*

> > > The anchor describes how to position the legend horizontally.

> > *@x,y*

> > > The anchor specifies how to position the legend relative to the positioning point. For example, if anchor is center then the legend is centered on the point; if anchor is n then the legend will be drawn such that the top center point of the rectangular region occupied by the legend will be at the positioning point.

> > *plotarea*

> > > The anchor specifies how to position the legend relative to the plotting area. For example, if anchor is center then the legend is centered in the plotting area; if anchor is ne then the legend will be drawn such that occupies the upper right corner of the plotting area.

> **-background** *color*

> > Sets the background color of the legend. If color is "", the legend background with be transparent.

> **-bindtags** *tagList*

> > Specifies the binding tags for legend entries. TagList is a list of binding tag names. The tags and their order will determine how events are handled for legend entries. Each tag in the list matching the current event sequence will have its Tcl command executed. The default value is all.

> **-borderwidth** *pixels*

> > Sets the width of the 3-D border around the outside edge of the legend (if such border is being drawn; the relief option determines this). The default is 2 pixels.

> **-font** *fontName*

> > FontName specifies a font to use when drawing the labels of each element into the legend. The default is `*-Helvetica-Bold-R-Normal-*-12-120-*`.

> **-foreground** *color*

> > Sets the foreground color of the text drawn for the element's label. The default is black.

> **-hide** *boolean*

> > Indicates whether the legend should be displayed. If boolean is true, the legend will not be draw. The default is no.

> **-ipadx** *pad*

> > Sets the amount of internal padding to be added to the width of each legend entry. Pad can be a list of one or two screen distances. If pad has two elements, the left side of the legend entry is padded by the first distance and the right side by the second. If pad is just one distance, both the left and right sides are padded evenly. The default is 2.

> **-ipady** *pad*

> > Sets an amount of internal padding to be added to the height of each legend entry. Pad can be a list of one or two screen distances. If pad has two elements, the top of the entry is padded by the first distance and the bottom by the second. If pad is just one distance, both the top and bottom of the entry are padded evenly. The default is 2.

> **-padx** *pad*

> > Sets the padding to the left and right exteriors of the legend. Pad can be a list of one or two screen distances. If pad has two elements, the left side of the legend is padded by the first distance and the right side by the second. If pad has just one distance, both the left and right sides are padded evenly. The default is 4.

> **-pady** *pad*

> > Sets the padding above and below the legend. Pad can be a list of one or two screen distances. If pad has two elements, the area above the legend is padded by the first distance and the area below by the second. If pad is just one distance, both the top and bottom areas are padded evenly. The default is 0.

> **-position** *pos*

> > Specifies where the legend is drawn. The -anchor option also affects where the legend is positioned. If pos is left, left, top, or bottom, the legend is drawn in the specified margin. If pos is plotarea, then the legend is drawn inside the plotting area at a particular anchor. If pos is in the form "@x,y", where x and y are the window coordinates, the legend is drawn in the plotting area at the specified coordinates. The default is right.

> **-raised** *boolean*

> > Indicates whether the legend is above or below the data elements. This matters only if the legend is in the plotting area. If boolean is true, the legend will be drawn on top of any elements that may overlap it. The default is no.

> **-relief** *relief*

> > Specifies the 3-D effect for the border around the legend. Relief specifies how the interior of the legend should appear relative to the graph; for example, raised means the legend should appear to protrude from the graph, relative to the surface of the graph. The default is sunken.

> Legend configuration options may also be set by the option command. The resource name and class are legend and Legend respectively.

> > <code>
        option add *Graph.legend.Foreground blue  
        option add *Graph.Legend.Relief     raised  
</code>

<a name="pathName-legend-deactivate"></a>
**pathName legend deactivate** *pattern...*

> Selects legend entries to be drawn using the normal legend colors and relief. All entries whose element names match pattern are selected. To be selected, the element name must match only one pattern.

<a name="pathName-legend-get"></a>
**pathName legend get** *pos*

> Returns the name of the element whose entry is at the screen position pos in the legend. Pos must be in the form "@x,y", where x and y are window coordinates. If the given coordinates do not lie over a legend entry, "" is returned.

<a name="PEN-COMPONENT"></a>
## PEN COMPONENT

Pens define attributes (both symbol and line style) for elements. Pens mirror the configuration options of data elements that pertain to how symbols and lines are drawn. Data elements use pens to determine how they are drawn. A data element may use several pens at once. In this case, the pen used for a particular data point is determined from each element's weight vector (see the element's -weight and -style options).

One pen, called activeLine, is automatically created. It's used as the default active pen for elements. So you can change the active attributes for all elements by simply reconfiguring this pen.

> <code>
	.g pen configure "activeLine" -color green  
</code>

You can create and use several pens. To create a pen, invoke the pen component and its create operation.

> <code>
	.g pen create myPen  
</code>

You map pens to a data element using either the element's -pen or -activepen options.

> <code>
	.g element create "line1" -xdata $x -ydata $tempData -pen myPen  
</code>

An element can use several pens at once. This is done by specifying the name of the pen in the element's style list (see the -styles option).

> <code>
	.g element configure "line1" -styles { myPen 2.0 3.0 }  
</code>

This says that any data point with a weight between 2.0 and 3.0 is to be drawn using the pen myPen. All other points are drawn with the element's default attributes.

The following operations are available for pen components.

<a name="pathName-pen-cget"></a>
**pathName pen cget** *penName option*

> Returns the current value of the option given by option for penName. Option may be any option described below for the pen configure operation.

<a name="pathName-pen-configure"></a>
**pathName pen configure** *penName ?penName... ?option value?...*

> Queries or modifies the configuration options of penName. Several pens can be modified at once. If option isn't specified, a list describing the current options for penName is returned. If option is specified, but not value, then a list describing option is returned. If one or more option and value pairs are specified, then for each pair, the pen option option is set to value. The following options are valid for pens.

> **-color** *color*

> > Sets the color of the traces connecting the data points.

> **-dashes** *dashList*

> > Sets the dash style of element line. DashList is a list of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the element line. Each number must be between 1 and 255. If dashList is "", the lines will be solid.

> **-fill** *color*

> > Sets the interior color of symbols. If color is "", then the interior of the symbol is transparent. If color is defcolor, then the color will be the same as the -color option. The default is defcolor.

> **-linewidth** *pixels*

> > Sets the width of the connecting lines between data points. If pixels is 0, no connecting lines will be drawn between symbols. The default is 0.

> **-offdash** *color*

> > Sets the color of the stripes when traces are dashed (see the -dashes option). If color is "", then the "off" pixels will represent gaps instead of stripes. If color is defcolor, then the color will be the same as the -color option. The default is defcolor.

> **-outline** *color*

> > Sets the color or the outline around each symbol. If color is "", then no outline is drawn. If color is defcolor, then the color will be the same as the -color option. The default is defcolor.

> **-outlinewidth** *pixels*

> > Sets the width of the outline bordering each symbol. If pixels is 0, no outline will be drawn. The default is 1.

> **-pixels** *pixels*

> > Sets the size of symbols. If pixels is 0, no symbols will be drawn. The default is 0.125i.

> **-symbol** *symbol*

> Specifies the symbol for data points. Symbol can be either square, circle, diamond, plus, cross, splus, scross, triangle, "" (where no symbol is drawn), or a bitmap. Bitmaps are specified as "source ?mask?", where source is the name of the bitmap, and mask is the bitmap's optional mask. The default is circle.

> **-type** *elemType*

> > Specifies the type of element the pen is to be used with. This option should only be employed when creating the pen. This is for those that wish to mix different types of elements (bars and lines) on the same graph. The default type is "line".

> Pen configuration options may be also be set by the option command. The resource class is Pen. The resource names are the names of the pens.

> > <code>
        option add *Graph.Pen.Color  blue  
        option add *Graph.activeLine.color  green  
</code>

<a name="pathName-pen-create"></a>
**pathName pen create** *penName ?option value?...*

> Creates a new pen by the name penName. No pen by the same name can already exist. Option and value are described in above in the pen configure operation.

<a name="pathName-pen-delete"></a>
**pathName pen delete** *?penName?...*

> Deletes the named pens. A pen is not really deleted until it is not longer in use, so it's safe to delete pens mapped to elements.

<a name="pathName-pen-names"></a>
**pathName pen names** *?pattern?...*

> Returns a list of pens matching zero or more patterns. If no pattern argument is give, the names of all pens are returned.

<a name="POSTSCRIPT-COMPONENT"></a>
## POSTSCRIPT COMPONENT

The graph can generate encapsulated PostScript output. There are several configuration options you can specify to control how the plot will be generated. You can change the page dimensions and borders. The plot itself can be scaled, centered, or rotated to landscape. The PostScript output can be written directly to a file or returned through the interpreter.

The following postscript operations are available.

<a name="pathName-postscript-cget"></a>
**pathName postscript cget** *option*

> Returns the current value of the postscript option given by option. Option may be any option described below for the postscript configure operation.

<a name="pathName-postscript-configure"></a>
**pathName postscript configure** *?option value?...*

> Queries or modifies the configuration options for PostScript generation. If option isn't specified, a list describing the current postscript options for pathName is returned. If option is specified, but not value, then a list describing option is returned. If one or more option and value pairs are specified, then for each pair, the postscript option option is set to value. The following postscript options are available.

> **-center** *boolean*

> > Indicates whether the plot should be centered on the PostScript page. If boolean is false, the plot will be placed in the upper left corner of the page. The default is 1.

> **-colormap** *varName*

> > VarName must be the name of a global array variable that specifies a color mapping from the X color name to PostScript. Each element of varName must consist of PostScript code to set a particular color value (e.g. ``1.0 1.0 0.0 setrgbcolor''). When generating color information in PostScript, the array variable varName is checked if an element of the name as the color exists. If so, it uses its value as the PostScript command to set the color. If this option hasn't been specified, or if there isn't an entry in varName for a given color, then it uses the red, green, and blue intensities from the X color.

> **-colormode** *mode*

> > Specifies how to output color information. Mode must be either color (for full color output), gray (convert all colors to their gray-scale equivalents) or mono (convert foreground colors to black and background colors to white). The default mode is color.

> **-fontmap** *varName*

> > VarName must be the name of a global array variable that specifies a font mapping from the X font name to PostScript. Each element of varName must consist of a Tcl list with one or two elements; the name and point size of a PostScript font. When outputting PostScript commands for a particular font, the array variable varName is checked to see if an element by the specified font exists. If there is such an element, then the font information contained in that element is used in the PostScript output. (If the point size is omitted from the list, the point size of the X font is used). Otherwise the X font is examined in an attempt to guess what PostScript font to use. This works only for fonts whose foundry property is Adobe (such as Times, Helvetica, Courier, etc.). If all of this fails then the font defaults to Helvetica-Bold.

> **-decorations** *boolean*

> > Indicates whether PostScript commands to generate color backgrounds and 3-D borders will be output. If boolean is false, the background will be white and no 3-D borders will be generated. The default is 1.

> **-height** *pixels*

> > Sets the height of the plot. This lets you print the graph with a height different from the one drawn on the screen. If pixels is 0, the height is the same as the widget's height. The default is 0.

> **-landscape** *boolean*

> > If boolean is true, this specifies the printed area is to be rotated 90 degrees. In non-rotated output the X-axis of the printed area runs along the short dimension of the page (``portrait'' orientation); in rotated output the X-axis runs along the long dimension of the page (``landscape'' orientation). Defaults to 0.

> **-maxpect** *boolean*

> > Indicates to scale the plot so that it fills the PostScript page. The aspect ratio of the graph is still retained. The default is 0.

> **-padx** *pad*

> > Sets the horizontal padding for the left and right page borders. The borders are exterior to the plot. Pad can be a list of one or two screen distances. If pad has two elements, the left border is padded by the first distance and the right border by the second. If pad has just one distance, both the left and right borders are padded evenly. The default is 1i.

> **-pady** *pad*

> > Sets the vertical padding for the top and bottom page borders. The borders are exterior to the plot. Pad can be a list of one or two screen distances. If pad has two elements, the top border is padded by the first distance and the bottom border by the second. If pad has just one distance, both the top and bottom borders are padded evenly. The default is 1i.

> **-paperheight** *pixels*

> > Sets the height of the postscript page. This can be used to select between different page sizes (letter, A4, etc). The default height is 11.0i.

> **-paperwidth** *pixels*

> > Sets the width of the postscript page. This can be used to select between different page sizes (letter, A4, etc). The default width is 8.5i.

> **-width** *pixels*

> > Sets the width of the plot. This lets you generate a plot of a width different from that of the widget. If pixels is 0, the width is the same as the widget's width. The default is 0.

> Postscript configuration options may be also be set by the option command. The resource name and class are postscript and Postscript respectively.

> > <code>
        option add *Graph.postscript.Decorations false  
        option add *Graph.Postscript.Landscape   true  
</code>

<a name="pathName-postscript-output"></a>
**pathName postscript output** *?fileName? ?option value?...*

> Outputs a file of encapsulated PostScript. If a fileName argument isn't present, the command returns the PostScript. If any option-value pairs are present, they set configuration options controlling how the PostScript is generated. Option and value can be anything accepted by the postscript configure operation above.

<a name="MARKER-COMPONENT"></a>
## MARKER COMPONENT

Markers are simple drawing procedures used to annotate or highlight areas of the graph. Markers have various types: text strings, bitmaps, images, connected lines, windows, or polygons. They can be associated with a particular element, so that when the element is hidden or un-hidden, so is the marker. By default, markers are the last items drawn, so that data elements will appear in behind them. You can change this by configuring the -under option.

Markers, in contrast to elements, don't affect the scaling of the coordinate axes. They can also have elastic coordinates (specified by -Inf and Inf respectively) that translate into the minimum or maximum limit of the axis. For example, you can place a marker so it always remains in the lower left corner of the plotting area, by using the coordinates -Inf,-Inf.

The following operations are available for markers.

<a name="pathName-marker-after"></a>
**pathName marker after markerId ?afterId?
    Changes the order of the markers, drawing the first marker after the second. If no second afterId argument is specified, the marker is placed at the end of the display list. This command can be used to control how markers are displayed since markers are drawn in the order of this display list.

<a name="pathName-marker-before"></a>
**pathName marker before** *markerId ?beforeId?*

> Changes the order of the markers, drawing the first marker before the second. If no second beforeId argument is specified, the marker is placed at the beginning of the display list. This command can be used to control how markers are displayed since markers are drawn in the order of this display list.

<a name="pathName-marker-bind"></a>
**pathName marker bind** *tagName ?sequence? ?command?*

> Associates command with tagName such that whenever the event sequence given by sequence occurs for a marker with this tag, command will be invoked. The syntax is similar to the bind command except that it operates on graph markers, rather than widgets. See the bind manual entry for complete details on sequence and the substitutions performed on command before invoking it.

> If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName. If the first character of command is + then command augments an existing binding rather than replacing it. If no command argument is provided then the command currently associated with tagName and sequence (it's an error occurs if there's no such binding) is returned. If both command and sequence are missing then a list of all the event sequences for which bindings have been defined for tagName.

<a name="pathName-marker-cget"></a>
**pathName marker cget** *option*

> Returns the current value of the marker configuration option given by option. Option may be any option described below in the configure operation.

<a name="pathName-marker-configure"></a>
**pathName marker configure** *markerId ?option value?...*

> Queries or modifies the configuration options for markers. If option isn't specified, a list describing the current options for markerId is returned. If option is specified, but not value, then a list describing option is returned. If one or more option and value pairs are specified, then for each pair, the marker option option is set to value.

> The following options are valid for all markers. Each type of marker also has its own type-specific options. They are described in the sections below.

> **-bindtags** *tagList*

> > Specifies the binding tags for the marker. TagList is a list of binding tag names. The tags and their order will determine how events for markers are handled. Each tag in the list matching the current event sequence will have its Tcl command executed. Implicitly the name of the marker is always the first tag in the list. The default value is all.

> **-coords** *coordList*

> > Specifies the coordinates of the marker. CoordList is a list of graph coordinates. The number of coordinates required is dependent on the type of marker. Text, image, and window markers need only two coordinates (an X-Y coordinate). Bitmap markers can take either two or four coordinates (if four, they represent the corners of the bitmap). Line markers need at least four coordinates, polygons at least six. If coordList is "", the marker will not be displayed. The default is "".

> **-element** *elemName*

> > Links the marker with the element elemName. The marker is drawn only if the element is also currently displayed (see the element's show operation). If elemName is "", the marker is always drawn. The default is "".

> **-hide** *boolean*

> > Indicates whether the marker is drawn. If boolean is true, the marker is not drawn. The default is no.

> **-mapx** *xAxis*

> > Specifies the X-axis to map the marker's X-coordinates onto. XAxis must the name of an axis. The default is x.

> **-mapy** *yAxis*

> > Specifies the Y-axis to map the marker's Y-coordinates onto. YAxis must the name of an axis. The default is y.

> **-name** *markerId*

> > Changes the identifier for the marker. The identifier markerId can not already be used by another marker. If this option isn't specified, the marker's name is uniquely generated.

> **-under** *boolean*

> > Indicates whether the marker is drawn below/above data elements. If boolean is true, the marker is be drawn underneath the data element symbols and lines. Otherwise, the marker is drawn on top of the element. The default is 0.

> **-xoffset** *pixels*

> > Specifies a screen distance to offset the marker horizontally. Pixels is a valid screen distance, such as 2 or 1.2i. The default is 0.

> **-yoffset** *pixels*

> > Specifies a screen distance to offset the markers vertically. Pixels is a valid screen distance, such as 2 or 1.2i. The default is 0.

> Marker configuration options may also be set by the option command. The resource class is either BitmapMarker, ImageMarker, LineMarker, PolygonMarker, TextMarker, or WindowMarker, depending on the type of marker. The resource name is the name of the marker.

> > <code>
        option add *Graph.TextMarker.Foreground white  
        option add *Graph.BitmapMarker.Foreground white  
        option add *Graph.m1.Background     blue  
</code>

<a name="pathName-marker-create"></a>
**pathName marker create** *type ?option value?...*

> Creates a marker of the selected type. Type may be either text, line, bitmap, image, polygon, or window. This command returns the marker identifier, used as the markerId argument in the other marker-related commands. If the -name option is used, this overrides the normal marker identifier. If the name provided is already used for another marker, the new marker will replace the old.

<a name="pathName-marker-delete"></a>
**pathName marker delete** *?name?...*

> Removes one of more markers. The graph will automatically be redrawn without the marker.

<a name="pathName-marker-exists"></a>
**pathName marker exists** *markerId*

> Returns 1 if the marker markerId exists and 0 otherwise.

<a name="pathName-marker-names"></a>
**pathName marker names** *?pattern?*

> Returns the names of all the markers that currently exist. If pattern is supplied, only those markers whose names match it will be returned.

<a name="pathName-marker-type"></a>
**pathName marker type** *markerId*

> Returns the type of the marker given by markerId, such as line or text. If markerId is not a valid a marker identifier, "" is returned.

<a name="BITMAP-MARKERS"></a>
### BITMAP MARKERS

A bitmap marker displays a bitmap. The size of the bitmap is controlled by the number of coordinates specified. If two coordinates, they specify the position of the top-left corner of the bitmap. The bitmap retains its normal width and height. If four coordinates, the first and second pairs of coordinates represent the corners of the bitmap. The bitmap will be stretched or reduced as necessary to fit into the bounding rectangle.

Bitmap markers are created with the marker's create operation in the form:

<a name="pathName-marker-create-bitmap"></a>
**pathName marker create bitmap** *?option value?...*

There may be many option-value pairs, each sets a configuration options for the marker. These same option-value pairs may be used with the marker's configure operation.

The following options are specific to bitmap markers:

> **-background** *color*

> > Same as the -fill option.

> **-bitmap** *bitmap*

> > Specifies the bitmap to be displayed. If bitmap is "", the marker will not be displayed. The default is "".

> **-fill** *color*

> > Sets the background color of the bitmap. If color is the empty string, no background will be transparent. The default background color is "".

> **-foreground** *color*

> > Same as the -outline option.

> **-mask** *mask*

> > Specifies a mask for the bitmap to be displayed. This mask is a bitmap itself, denoting the pixels that are transparent. If mask is "", all pixels of the bitmap will be drawn. The default is "".

> **-outline** *color*

> > Sets the foreground color of the bitmap. The default value is black.

> **-rotate** *theta*

> > Sets the rotation of the bitmap. Theta is a real number representing the angle of rotation in degrees. The marker is first rotated and then placed according to its anchor position. The default rotation is 0.0.

<a name="IMAGE-MARKERS"></a>
### IMAGE MARKERS

A image marker displays an image. Image markers are created with the marker's create operation in the form:

<a name="pathName-marker-create-image"></a>
**pathName marker create image** *?option value?...*

There may be many option-value pairs, each sets a configuration option for the marker. These same option-value pairs may be used with the marker's configure operation.

The following options are specific to image markers:

> **-anchor** *anchor*

> > Anchor tells how to position the image relative to the positioning point for the image. For example, if anchor is center then the image is centered on the point; if anchor is n then the image will be drawn such that the top center point of the rectangular region occupied by the image will be at the positioning point. This option defaults to center.

> **-image** *image*

> > Specifies the image to be drawn. If image is "", the marker will not be drawn. The default is "".

<a name="LINE-MARKERS"></a>
### LINE MARKERS

A line marker displays one or more connected line segments. Line markers are created with marker's create operation in the form:

<a name="pathName-marker-create-line"></a>
**pathName marker create line** *?option value?...*

There may be many option-value pairs, each sets a configuration option for the marker. These same option-value pairs may be used with the marker's configure operation.

The following options are specific to line markers:

> **-dashes** *dashList*

> > Sets the dash style of the line. DashList is a list of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the line. Each number must be between 1 and 255. If dashList is "", the marker line will be solid.

> **-fill** *color*

> > Sets the background color of the line. This color is used with striped lines (see the -fdashes option). If color is the empty string, no background color is drawn (the line will be dashed, not striped). The default background color is "".

> **-linewidth** *pixels*

> > Sets the width of the lines. The default width is 0.

> **-outline** *color*

> > Sets the foreground color of the line. The default value is black.

> **-stipple** *bitmap*

> > Specifies a stipple pattern used to draw the line, rather than a solid line. Bitmap specifies a bitmap to use as the stipple pattern. If bitmap is "", then the line is drawn in a solid fashion. The default is "".

<a name=">POLYGON-MARKERS"></a>
### POLYGON MARKERS

A polygon marker displays a closed region described as two or more connected line segments. It is assumed the first and last points are connected. Polygon markers are created using the marker create operation in the form:

<a name="pathName-marker-create-polygon"></a>
**pathName marker create polygon** *?option value?...*

There may be many option-value pairs, each sets a configuration option for the marker. These same option-value pairs may be used with the marker configure command to change the marker's configuration. The following options are supported for polygon markers:

> **-dashes** *dashList*
    Sets the dash style of the outline of the polygon. DashList is a list of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the outline. Each number must be between 1 and 255. If dashList is "", the outline will be a solid line.

> **-fill** *color*

> > Sets the fill color of the polygon. If color is "", then the interior of the polygon is transparent. The default is white.

> **-linewidth** *pixels*

> > Sets the width of the outline of the polygon. If pixels is zero, no outline is drawn. The default is 0.

> **-outline** *color*

> > Sets the color of the outline of the polygon. If the polygon is stippled (see the -stipple option), then this represents the foreground color of the stipple. The default is black.

> **-stipple** *bitmap*

> > Specifies that the polygon should be drawn with a stippled pattern rather than a solid color. Bitmap specifies a bitmap to use as the stipple pattern. If bitmap is "", then the polygon is filled with a solid color (if the -fill option is set). The default is "".

<a name=TEXT-MARKERS"></a>
### TEXT MARKERS

A text marker displays a string of characters on one or more lines of text. Embedded newlines cause line breaks. They may be used to annotate regions of the graph. Text markers are created with the create operation in the form:

<a name="pathName-marker-create-text"></a>
**pathName marker create text** *?option value?...*

There may be many option-value pairs, each sets a configuration option for the text marker. These same option-value pairs may be used with the marker's configure operation.

The following options are specific to text markers:

> **-anchor** *anchor*

> > Anchor tells how to position the text relative to the positioning point for the text. For example, if anchor is center then the text is centered on the point; if anchor is n then the text will be drawn such that the top center point of the rectangular region occupied by the text will be at the positioning point. This default is center.

> **-background** *color*

> > Same as the -fill option.

> **-font** *fontName*

> > Specifies the font of the text. The default is `*-Helvetica-Bold-R-Normal-*-120-*`.

> **-fill** *color*

> > Sets the background color of the text. If color is the empty string, no background will be transparent. The default background color is "".

> **-foreground** *color*

> > Same as the -outline option.

> **-justify** *justify*

> > Specifies how the text should be justified. This matters only when the marker contains more than one line of text. Justify must be left, right, or center. The default is center.

> **-outline** *color*

> > Sets the color of the text. The default value is black.

> **-padx** *pad*

> > Sets the padding to the left and right exteriors of the text. Pad can be a list of one or two screen distances. If pad has two elements, the left side of the text is padded by the first distance and the right side by the second. If pad has just one distance, both the left and right sides are padded evenly. The default is 4.

> **-pady** *pad*

> > Sets the padding above and below the text. Pad can be a list of one or two screen distances. If pad has two elements, the area above the text is padded by the first distance and the area below by the second. If pad is just one distance, both the top and bottom areas are padded evenly. The default is 4.

> **-rotate** *theta*

> > Specifies the number of degrees to rotate the text. Theta is a real number representing the angle of rotation. The marker is first rotated along its center and is then drawn according to its anchor position. The default is 0.0.

> **-text** *text*

> > Specifies the text of the marker. The exact way the text is displayed may be affected by other options such as -anchor or -rotate.

<a name="WINDOW-MARKERS"></a>
### WINDOW MARKERS

A window marker displays a widget at a given position. Window markers are created with the marker's create operation in the form:

<a name="pathName-marker-create-window"></a>
**pathName marker create window** *?option value?...*

There may be many option-value pairs, each sets a configuration option for the marker. These same option-value pairs may be used with the marker's configure command.

The following options are specific to window markers:

> **-anchor** *anchor*

> > Anchor tells how to position the widget relative to the positioning point for the widget. For example, if anchor is center then the widget is centered on the point; if anchor is n then the widget will be displayed such that the top center point of the rectangular region occupied by the widget will be at the positioning point. This option defaults to center.

> **-height** *pixels*

> > Specifies the height to assign to the marker's window. If this option isn't specified, or if it is specified as "", then the window is given whatever height the widget requests internally.

> **-width** *pixels*

> > Specifies the width to assign to the marker's window. If this option isn't specified, or if it is specified as "", then the window is given whatever width the widget requests internally.

> **-window** *pathName*

> > Specifies the widget to be managed by the graph. PathName must be a child of the graph widget.

<a name="GRAPH-COMPONENT-BINDINGS"></a>
## GRAPH COMPONENT BINDINGS

Specific graph components, such as elements, markers and legend entries, can have a command trigger when event occurs in them, much like canvas items in Tk's canvas widget. Not all event sequences are valid. The only binding events that may be specified are those related to the mouse and keyboard (such as Enter, Leave, ButtonPress, Motion, and KeyPress).

Only one element or marker can be picked during an event. This means, that if the mouse is directly over both an element and a marker, only the uppermost component is selected. This isn't true for legend entries. Both a legend entry and an element (or marker) binding commands will be invoked if both items are picked.

It is possible for multiple bindings to match a particular event. This could occur, for example, if one binding is associated with the element name and another is associated with one of the element's tags (see the -bindtags option). When this occurs, all of the matching bindings are invoked. A binding associated with the element name is invoked first, followed by one binding for each of the element's bindtags. If there are multiple matching bindings for a single tag, then only the most specific binding is invoked. A continue command in a binding script terminates that script, and a break command terminates that script and skips any remaining scripts for the event, just as for the bind command.

The -bindtags option for these components controls addition tag names which can be matched. Implicitly elements and markers always have tags matching their names. Setting the value of the -bindtags option doesn't change this.

Some common bindings can be set with the [*pathName* **binding**](#pathName-binding) command.

## <a name="C-LANGUAGE-API"></a>
## C LANGUAGE API 

You can manipulate data elements from the C language. There may be situations where it is too expensive to translate the data values from ASCII strings. Or you might want to read data in a special file format.

Data can manipulated from the C language using graph vectors. You specify the X-Y data coordinates of an element as vectors and manipulate the vector from C. The graph will be redrawn automatically after the vectors are updated.

From Tcl, create the vectors and configure the element to use them.

> <code>
	vector X Y  
	.g element configure line1 -xdata X -ydata Y  
</code>

To set data points from C, you pass the values as arrays of doubles using the Rbc_ResetVector call. The vector is reset with the new data and at the next idle point (when Tk re-enters its event loop), the graph will be redrawn automatically.

> <code>
	#include "tcl.h"  
	#include "rbcInt.h"  

	register int i;  
	Rbc_Vector *xVec, *yVec;  
	double x[50], y[50];  

	/* Get the graph vectors "X" and "Y" (created above from Tcl) */  
	if ((Rbc_GetVector(interp, "X", &xVec) != TCL_OK) ||  
	    (Rbc_GetVector(interp, "Y", &yVec) != TCL_OK)) {  
	    return TCL_ERROR;  
 	}  

	for (i = 0; i < 50; i++) {  
	    x[i] = i * 0.02;  
	    y[i] = sin(x[i]);  
	}  

	/* Put the data into graph vectors */  
	if ((Rbc_ResetVector(xVec, x, 50, 50, TCL_VOLATILE) != TCL_OK) ||  
	    (Rbc_ResetVector(yVec, y, 50, 50, TCL_VOLATILE) != TCL_OK)) {  
	    return TCL_ERROR;  
	}  
</code>

See the vector manual page for more details.

<a name="SPEED-TIPS"></a>
## SPEED TIPS

There may be cases where the graph needs to be drawn and updated as quickly as possible. If drawing speed becomes a big problem, here are a few tips to speed up displays.

Try to minimize the number of data points. The more data points the looked at, the more work the graph must do.

If your data is generated as floating point values, the time required to convert the data values to and from ASCII strings can be significant, especially when there any many data points. You can avoid the redundant string-to-decimal conversions using the C API to graph vectors.

Data elements without symbols are drawn faster than with symbols. Set the data element's -symbol option to none. If you need to draw symbols, try using the simple symbols such as splus and scross.

Don't stipple or dash the element. Solid lines are much faster.

If you update data elements frequently, try turning off the widget's -bufferelements option. When the graph is first displayed, it draws data elements into an internal pixmap. The pixmap acts as a cache, so that when the graph needs to be redrawn again, and the data elements or coordinate axes haven't changed, the pixmap is simply copied to the screen. This is especially useful when you are using markers to highlight points and regions on the graph. But if the graph is updated frequently, changing either the element data or coordinate axes, the buffering becomes redundant.

## <a name="LIMITATIONS"></a>
## LIMITATIONS

Auto-scale routines do not use requested min/max limits as boundaries when the axis is logarithmically scaled.

The PostScript output generated for polygons with more than 1500 points may exceed the limits of some printers (See PostScript Language Reference Manual, page 568). The work-around is to break the polygon into separate pieces.

<a name="EXAMPLE"></a>
## EXAMPLE

The graph command creates a new graph.

> <code>
	# Create a new graph.  Plotting area is black.  
	graph .g -plotbackground black
</code>

A new Tcl command .g is also created. This command can be used to query and modify the graph. For example, to change the title of the graph to "My Plot", you use the new command and the graph's configure operation.

> <code>
	# Change the title.  
	.g configure -title "My Plot"
</code>

A graph has several components. To access a particular component you use the component's name. For example, to add data elements, you use the new command and the element component.

> <code>
	# Create a new element named "line1"  
	.g element create line1 \\  
	-xdata { 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 } \\  
	-ydata { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 155.85 166.60 175.38 }
</code>

The element's X-Y coordinates are specified using lists of numbers. Alternately, graph vectors could be used to hold the X-Y coordinates.

> <code>
	# Create two vectors and add them to the graph.
	vector xVec yVec  
	xVec set { 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 }  
	yVec set { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 155.85 166.60 175.38 }  
	.g element create line1 -xdata xVec -ydata yVec  
</code>

The advantage of using vectors is that when you modify one, the graph is automatically redrawn to reflect the new values.

> <code>
	# Change the y coordinate of the first point.  
	set yVector(0) 25.18
</code>

An element named e1 is now created in .b. It is automatically added to the display list of elements. You can use this list to control in what order elements are displayed. To query or reset the element display list, you use the element's show operation.

> <code>
	# Get the current display list 	
	set elemList [.b element show]  
	# Remove the first element so it won't be displayed.  
	.b element show [lrange $elemList 0 end]  
</code>

The element will be displayed by as many bars as there are data points (in this case there are ten). The bars will be drawn centered at the x-coordinate of the data point. All the bars will have the same attributes (colors, stipple, etc). The width of each bar is by default one unit. You can change this with using the -barwidth option.

> <code>
	# Change the X-Y coordinates of the first point.  
	set xVec(0) 0.18  
	set yVec(0) 25.18  
</code>

An element named line1 is now created in .g. By default, the element's label in the legend will be also line1. You can change the label, or specify no legend entry, again using the element's configure operation.

> <code>
	# Don't display "line1" in the legend.  
	.g element configure line1 -label ""  
</code>

You can configure more than just the element's label. An element has many attributes such as symbol type and size, dashed or solid lines, colors, line width, etc.

> <code>
	# Configure line1  
	.g element configure line1 -symbol square -color red -dashes { 2 4 2 } -linewidth 2 -pixels 2c  
</code>

Four coordinate axes are automatically created: x, x2, y, and y2. And by default, elements are mapped onto the axes x and y. This can be changed with the -mapx and -mapy options.

> <code>
	# Map "line1" on the alternate Y-axis "y2".  
	.g element configure line1 -mapy y2  
</code>
Axes can be configured in many ways too. For example, you change the scale of the Y-axis from linear to log using the axis component.

> <code>
	# Y-axis is log scale.  
	.g axis configure y -logscale yes  
</code>

One important way axes are used is to zoom in on a particular data region. Zooming is done by simply specifying new axis limits using the -min and -max configuration options.

> <code>
	.g axis configure x -min 1.0 -max 1.5  
	.g axis configure y -min 12.0 -max 55.15  
</code>

To zoom interactively, you link the axis configure operations with some user interaction (such as pressing the mouse button), using the bind command. To convert between screen and graph coordinates, use the invtransform operation.

> <code>
	# Click the button to set a new minimum  
	bind .g <ButtonPress-1> {  
    		%W axis configure x -min [%W axis invtransform x %x]  
    		%W axis configure x -min [%W axis invtransform x %y]  
	}  
</code>

By default, the limits of the axis are determined from data values. To reset back to the default limits, set the -min and -max options to the empty value.

> <code>
	# Reset the axes to autoscale again.  
	.g axis configure x -min {} -max {}  
	.g axis configure y -min {} -max {}  
</code>

By default, the legend is drawn in the right margin. You can change this or any legend configuration options using the legend component.

> <code>
	# Configure the legend font, color, and relief  
	.g legend configure -position left -relief raised -font fixed -fg blue  
</code>

To prevent the legend from being displayed, turn on the -hide option.

> <code>
	# Don't display the legend.  
	.g legend configure -hide yes  
</code>

The graph widget has simple drawing procedures called markers. They can be used to highlight or annotate data in the graph. The types of markers available are bitmaps, images, polygons, lines, or windows. Markers can be used, for example, to mark or brush points. In this example, is a text marker that labels the data first point. Markers are created using the marker component.

> <code>
	# Create a label for the first data point of "line1".  
	.g marker create text -name first_marker -coords { 0.2 26.18 } \\  
	-text "start" -anchor se -xoffset -10 -yoffset -10  
</code>
This creates a text marker named first_marker. It will display the text "start" near the coordinates of the first data point. The -anchor, -xoffset, and -yoffset options are used to display the marker above and to the left of the data point, so that the data point isn't covered by the marker. By default, markers are drawn last, on top of data. You can change this with the -under option.

> <code>
	# Draw the label before elements are drawn.  
	.g marker configure first_marker -under yes  
</code>

You can add cross hairs or grid lines using the crosshairs and grid components.

> <code>
	# Display both cross hairs and grid lines.  
	.g crosshairs configure -hide no -color red  
	.g grid configure -hide no -dashes { 2 2 }  

	# Set up a binding to reposition the crosshairs.  
	bind .g <Motion> {  
    		.g crosshairs configure -position @%x,%y  
	}  
</code>

The crosshairs are repositioned as the mouse pointer is moved in the graph. The pointer X-Y coordinates define the center of the crosshairs.

Finally, to get hardcopy of the graph, use the postscript component.

> <code>
	# Print the graph into file "file.ps"  
	.g postscript output file.ps -maxpect yes -decorations no  
</code>

This generates a file file.ps containing the encapsulated PostScript of the graph. The option -maxpect says to scale the plot to the size of the page. Turning off the -decorations option denotes that no borders or color backgrounds should be drawn (i.e. the background of the margins, legend, and plotting area will be white).

<a name="CREDITS"></a>
## CREDITS

[BLT][] was originally develeoped by George A. Howlett. It can be found at <https://sourceforge.net/projects/blt/>.

Refactored [BLT][] Components ([Rbc][]), includes data vectors and graph widgets from the original [BLT][]. Both can be found at sourceforge.

User visible changes to the original [Rbc][] code are:

- widget name is **graph**
- new **-style** *line|bar|strip* option instead of three different commands **graph**, **barchart** and **stripchart**
- no unique abbreviations of widget commands

<a name="KEYWORDS"></a>
## KEYWORDS

graph, widget

<a name="COPYRIGHT"></a>:1

## COPYRIGHT

&copy; 1995-1997 Roger E. Critchlow Jr.

&copy; 2001 George A. Howlett.

&copy; 2018 René Zaumseil <[email protected]>

[BLT]: <https://sourceforge.net/projects/blt/>
[Rbc]: <https://sourceforge.net/projects/rbctoolkit/>

# path(n) -- 2D canvas widget

*   [SYNOPSIS](#SYNOPSIS)
*   [STANDARD OPTIONS](#STANDARD-OPTIONS)  
  [-background or -bg, background, Background](options.htm#M-background)   
  [-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)  
  [-cursor, cursor, Cursor](options.htm#M-cursor)  
  [-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)  
  [-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)  
  [-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)  
  [-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground)  
  [-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth)  
  [-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime)  
  [-insertontime, insertOnTime, OnTime](options.htm#M-insertontime)  
  [-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth)  
  [-relief, relief, Relief](options.htm#M-relief)  
  [-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground)  
  [-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth)  
  [-selectforeground, selectForeground, Background](options.htm#M-selectforeground)  
  [-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)  
  [-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand)  
  [-yscrollcommand, yScrollCommand, ScrollCommand](options.htm#M-yscrollcommand)  
* [WIDGET-SPECIFIC OPTIONS](#WIDGET-SPECIFIC-OPTIONS)  
  [-class, class, Class](#-class)  
  [-closeenough, closeEnough, CloseEnough](#-closeenough)  
  [-confine, confine, Confine](#-confine)  
  [-height, height, Height](#-height)  
  [-offset, offset, Offset](#-offset)  
  [-scrollregion, scrollRegion, ScrollRegion](#-scrollregion)  
  [-state, state, State](#-state)  
  [-tagstyle, tagstyle, Tagstyle](#-tagstyle)  
  [-width, width, Width](#-width)  
  [-xscrollincrement, xScrollIncrement, ScrollIncrement](#-xscrollincrement)  
  [-yscrollincrement, yScrollIncrement, ScrollIncrement](#-yscrollincrement)  
*   [DESCRIPTION](#DESCRIPTION)  
  * [DISPLAY LIST](#DISPLAY-LIST)  
  * [ITEM IDS AND TAGS](#ITEM-IDS-AND-TAGS)  
  * [COORDINATES](#COORDINATES)  
  * [TEXT INDICES](#TEXT-INDICES)  
  * [TRANSFORMATIONS](#TRANSFORMATIONS)    
  [**path::matrix rotate**](#path::matrix-rotate) *angle ?cx? ?cy?*  
  [**path::matrix scale**](#path::matrix-scale) *sx ?sy?*  
  [**path::matrix flip**](#path::matrix-flip) *?cx? ?cy? ?fx? ?fy?*  
  [**path::matrix rotateflip**](#path::matrix-rotateflip) *?angle? ?cx? ?cy? ?fx? ?fy?*  
  [**path::matrix skewx**](#path::matrix-skewx) *?angle?*  
  [**path::matrix skewy**](#path::matrix-skewy) *?angle?*  
  [**path::matrix move**](#path::matrix-move) *dx dy*  
  [**path::matrix mult**](#path::matrix-mult) *ma mb*  
  * [STYLES](#STYLES)  
  [**path::style cget**](#path::style-cget) *token option*  
  [**path::style configure**](#path::style-configure) *token ?option? ?value option value...?*  
  [**path::style create**](#path::style-create) *?fillOptions strokeOptions?*  
  [**path::style delete**](#path::style-delete) *token*  
  [**path::style inuse**](#path::style-inuse) *token*  
  [**path::style names**](#path::style-names)  
  * [GRADIENTS](#GRADIENTS)  
  [**path::gradient cget**](#path::gradient-cget) *token option*  
  [**path::gradient configure**](#path::gradient-configure) *token ?option? ?value option value...?*  
  [**path::gradient create**](#path::gradient-create) *type ?-key value ...?*  
  [**path::gradient delete**](#path::gradient-delete) *token*  
  [**path::gradient inuse**](#path::gradient-inuse) *token*  
  [**path::gradient names**](#path::gradient-names)  
  [**path::gradient type**](#path::gradient-type) *token*  
  * [SURFACE](#SURFACE)  
  [**path::surface names**](#path::surface-names)  
  [**path::surface new**](#path::surface-new) *width height*  
*   [WIDGET COMMAND](#WIDGET-COMMAND)  
  [*pathName* **addtag**](#pathName-addtag) *tag searchSpec ?arg arg ...?*  
  [*pathName* **ancestors**](#pathName-ancestors) *tagOrId*  
  [*pathName* **bind**](#pathName-bind) *tagOrId ?sequence? ?command?*  
  [*pathName* **canvasy**](#pathName-canvasy) *screeny ?gridspacing?*  
  [*pathName* **cget**](#pathName-cget) *option*  
  [*pathName* **children**](#pathName-children) *tagOrId*  
  [*pathName* **configure**](#pathName-configure) *?option? ?value? ?option value ...?*  
  [*pathName* **coords**](#pathName-coords) *tagOrId ?x0 y0 ...?*  
  [*pathName* **create**](#pathName-create) *type x y ?x y ...? ?option value ...?*  
  [*pathName* **dchars**](#pathName-dchars) *tagOrId first ?last?*  
  [*pathName* **delete**](#pathName-delete) *?*tagOrId* *tagOrId* ...?*  
  [*pathName* **depth**](#pathName-depth) *tagOrId*  
  [*pathName* **distance**](#pathName-distance) *tagOrId x y*  
  [*pathName* **dtag**](#pathName-dtag) *tagOrId ?tagToDelete?*  
  [*pathName* **find**](#pathName-find) *searchCommand ?arg arg ...?*  
  [*pathName* **firstchild**](#pathName-firstchild) *tagOrId*  
  [*pathName* **focus**](#pathName-focus) *?*tagOrId*?*  
  [*pathName* **gettags**](#pathName-gettags) *tagOrId*  
  [*pathName* **gradient**](#pathName-gradient) *command ?options?*  
  [*pathName* **icursor**](#pathName-icursor) *tagOrId index*   
  [*pathName* **imove**](#pathName-imove) *tagOrId index x y*  
  [*pathName* **index**](#pathName-index) *tagOrId index*  
  [*pathName* **insert**](#pathName-insert) *tagOrId beforeThis string*  
  [*pathName* **itemcget**](#pathName-itemcget) *tagOrId option*  
  [*pathName* **itemconfigure**](#pathName-itemconfigure) *tagOrId ?option? ?value? ?option value ...?*  
  [*pathName* **itempdf**](#pathName-itempdf) *tagOrId ?extgsProc objProc gradProc?*  
  [*pathName* **lastchild**](#pathName-lastchild) *tagOrId*  
  [*pathName* **lower**](#pathName-lower) *tagOrId ?belowThis?*  
  [*pathName* **move**](#pathName-move) *tagOrId xAmount yAmount*  
  [*pathName* **moveto**](#pathName-moveto) *tagOrId xPos yPos*  
  [*pathName* **nextsibling**](#pathName-nextsibling) *tagOrId*  
  [*pathName* **parent**](#pathName-parent) *tagOrId*  
  [*pathName* **prevsibling**](#pathName-prevsibling) *tagOrId*  
  [*pathName* **raise**](#pathName-raise) *tagOrId ?aboveThis?*  
  [*pathName* **rchars**](#pathName-rchars) *tagOrId first last string*  
  [*pathName* **scale**](#pathName-scale) *tagOrId xOrigin yOrigin xScale yScale*  
  [*pathName* **scan**](#pathName-scan) *option args*  
  [*pathName* **select**](#pathName-select) *option ?*tagOrId* arg?*  
  [*pathName* **style**](#pathName-style) *cmd ?options?*  
  [*pathName* **type**](#pathName-type) *tagOrId*  
  [*pathName* **types**](#pathName-types)  
  [*pathName* **xview**](#pathName-xview) *?args?*  
  [*pathName* **yview**](#pathName-yview) *?args?*  
*   [ITEM TYPES](#ITEM-TYPES)  
  * [COMMON ITEM OPTIONS](#COMMON-ITEM-OPTIONS)  
  [**-fill** *color\|gradientToken*](#ITEM-fill)  
  [**-fillopacity** *value*](#ITEM-fillopacity)  
  [**-fillrule** *nonzero\|evenodd*](#ITEM-fillrule)  
  [**-stroke** *color*](#ITEM-stroke)  
  [**-strokedasharray** *dashArray*](#ITEM-strokedasharray)  
  [**-strokelinecap** *butt\|round\|square*](#ITEM-strokelinecap)  
  [**-strokelinejoin** *miter\|round\|bevel*](#ITEM-strokelinejoin)  
  [**-strokemiterlimit** *float*](#ITEM-strokemiterlimit)  
  [**-strokeopacity** *value*](#ITEM-strokeopacity)  
  [**-strokewidth** *float*](#ITEM-strokewidth)  
  [**-matrix** *{a b c d tx ty}*](#ITEM-matrix)  
  [**-parent** *tagOrId*](#ITEM-parent)  
  [**-state** *active\|disabled\|normal\|hidden*](#ITEM-state)  
  [**-style** *styleToken*](#ITEM-style)  
  [**-tags** *tagList*](#ITEM-tags)  
  [**-startarrow** *boolean*](#ITEM-startarrow)  
  [**-startarrowlength** *float*](#ITEM-startarrowlength)  
  [**-startarrowwidth** *float*](#ITEM-startarrowwidth)  
  [**-startarrowfill** *float*](#ITEM-startarrowfill)  
  [**-endarrow** *boolean*](#ITEM-endarrow)  
  [**-endarrowlength** *float*](#ITEM-endarrowlength)  
  [**-endarrowwidth** *float*](#ITEM-endarrowwidth)  
  [**-endarrowfill** *float*](#ITEM-endarrowfill)  
  * [GROUP ITEM](#GROUP-ITEM)  
  [*pathName* **create group**](#pathName-create-group) *?fillOptions strokeOptions genericOptions?*  
  * [PATH ITEMS](#PATH-ITEM)  
  [*pathName* **create path**](#pathName-create-path) *pathSpec ?fillOptions strokeOptions arrowOptions genericOptions?*  
  * [LINE ITEM](#LINE-ITEM)  
  [*pathName* **create line**](#pathName-create-line) *x1 y1 x2 y2 ?strokeOptions arrowOptions genericOptions?*  
  * [POLYLINE ITEM](#POLYLINE-ITEM)  
  [*pathName* **create polyline**](#pathName-create-polyline) *x1 y1 x2 y2 .... ?strokeOptions arrowOptions genericOptions?*  
  * [POLYGON ITEM](#POLYGON-ITEM)  
  [*pathName* **create polygon**](#pathName-create-polygon) *x1 y1 x2 y2 .... ?fillOptions strokeOptions genericOptions?*  
  * [RECT ITEM](#RECT-ITEM)  
  [*pathName* **create rect**](#pathName-create-rect) *x1 y1 x2 y2 ?-rx value? ?-ry value? ?fillOptions strokeOptions genericOptions?*  
  * [CIRCLE ITEM](#CIRCLE-ITEM)  
  [*pathName* **create circle**](#pathName-create-circle) *cx cy ?-r fillOptions strokeOptions genericOptions?*  
  * [ELLIPSE ITEM](#ELLIPSE-ITEM)  
  [*pathName* **create ellipse**](#pathName-create-ellipse) *cx cy ?-rx value? ?-ry value? ?fillOptions strokeOptions genericOptions?*  
  * [IMAGE ITEM](#IMAGE-ITEM)  
  [*pathName* **create image**](#pathName-create-image) *x y ?-image -width -height genericOptions?*  
  * [TEXT ITEM](#TEXT-ITEM)  
  [*pathName* **create text**](#pathName-create-text) *x y ?-text string? ?-textanchor start\|middle\|end\|n\|w\|s\|e\|nw\|ne\|sw\|se\|c? ?-fontfamily fontname -fontsize float? ?-fontslant normal\|italic\|oblique? ?-fontweight normal\|bold? ?fillOptions strokeOptions genericOptions? ?-filloverstroke BOOLEAN?*  
  * [WINDOW ITEM](#WINDOW-ITEM)  
  [*pathName* **create window**](#pathName-create-window) *x y ?option value ...?*  
*   [CREDITS](#CREDITS)  
*   [KEYWORDS](#KEYWORDS)  
*   [COPYRIGHT](#COPYRIGHT)  

<a name="SYNOPSIS"></a>
## SYNOPSIS

**path** *pathName ?options?*

The **path** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget.

<a name="STANDARD-OPTIONS"></a>
## STANDARD OPTIONS

[-background or -bg, background, Background](options.htm#M-background)  
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)  
[-cursor, cursor, Cursor](options.htm#M-cursor)  
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)  
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)  
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)  
[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground)  
[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth)  
[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime)  
[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime)  
[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth)  
[-relief, relief, Relief](options.htm#M-relief)  
[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground)  
[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth)  
[-selectforeground, selectForeground, Background](options.htm#M-selectforeground)  
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)  
[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand)  
[-yscrollcommand, yScrollCommand, ScrollCommand](options.htm#M-yscrollcommand)  

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

<a name="WIDGET-SPECIFIC-OPTIONS"></a>
## WIDGET-SPECIFIC OPTIONS

<a name="-class"></a>
Command-Line Name: **-class**  
Database Name: **class**  
Database Class: **Class**

> > Define class for use in getting values from option database.

<a name="-closeenough"></a>
Command-Line Name: **-closeenough**  
Database Name: **closeEnough**  
Database Class: **CloseEnough**

> Specifies a floating-point value indicating how close the mouse cursor must be to an item before it is considered to be "inside" the item. Defaults to 1.0. 

<a name="-confine"></a>
Command-Line Name: **-confine**  
Database Name: **confine**  
Database Class: **Confine**

> Specifies a boolean value that indicates whether or not it should be allowable to set the canvas's view outside the region defined by the **scrollRegion** argument. Defaults to true, which means that the view will be constrained within the scroll region. 

<a name="-height"></a>
Command-Line Name: **-height**  
Database Name: **height**  
Database Class: **Height**

> Specifies a desired window height that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the [COORDINATES][] section below. 

<a name="-offset"></a>
Command-Line Name: **-offset**  
Database Name: **offset**  
Database Class: **Offset**

> Stipple offset for outline. 

<a name="-scrollregion"></a>
Command-Line Name: **-scrollregion**  
Database Name: **scrollRegion**  
Database Class: **ScrollRegion**

> Specifies a list with four coordinates describing the left, top, right, and bottom coordinates of a rectangular region. This region is used for scrolling purposes and is considered to be the boundary of the information in the canvas. Each of the coordinates may be specified in any of the forms given in the [COORDINATES][] section below. 

<a name="-state"></a>
Command-Line Name: **-state**  
Database Name: **state**  
Database Class: **State**

> Modifies the default state of the canvas where state may be set to one of: **normal**, **disabled**, or **hidden**. Individual canvas objects all have their own state option which may override the default state. Many options can take separate specifications such that the appearance of the item can be different in different situations. The options that start with **active** control the appearance when the mouse pointer is over it, while the option starting with **disabled** controls the appearance when the state is disabled. Canvas items which are **disabled** will not react to canvas bindings. 

<a name="-tagstyle"></a>
Command-Line Name: **-tagstyle**  
Database Name: **tagstyle**  
Database Class: **Tagstyle**

> Define working with tags. Possible values are *expr\|exact\|glob*. Default is *expr*. TODO

<a name="-width"></a>
Command-Line Name: **-width**  
Database Name: **width**  
Database Class: **Width**

> Specifies a desired window width that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the [COORDINATES][] section below. 

<a name="-xscrollincrement"></a>
Command-Line Name: **-xscrollincrement**  
Database Name: **xScrollIncrement**  
Database Class: **ScrollIncrement**

> Specifies an increment for horizontal scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the canvas x coordinate at the left edge of the window is always an even multiple of **xScrollIncrement**; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be **xScrollIncrement**. If the value of this option is less than or equal to zero, then horizontal scrolling is unconstrained. 

<a name="-yscrollincrement"></a>
Command-Line Name: **-yscrollincrement**  
Database Name: **yScrollIncrement**  
Database Class: **ScrollIncrement**

> Specifies an increment for vertical scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the vertical view in the window will be constrained so that the canvas y coordinate at the top edge of the window is always an even multiple of **yScrollIncrement**; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be **yScrollIncrement**. If the value of this option is less than or equal to zero, then vertical scrolling is unconstrained. 

<a name="DESCRIPTION"></a>
## DESCRIPTION

The **path** command creates a new window (given by the pathName argument) and makes it into a canvas widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the canvas such as its colors and 3-D relief. The **path** command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.

Canvas widgets implement structured graphics. A canvas displays any number of items, which may be things like rectangles, circles, lines, and text. Items may be manipulated (e.g. moved or re-colored) and commands may be associated with items in much the same way that the [bind][] command allows commands to be bound to widgets. For example, a particular command may be associated with the <Button-1> event so that the command is invoked whenever button 1 is pressed with the mouse cursor over an item. This means that items in a canvas can have behaviors defined by the Tcl scripts bound to them. 

This widget implements a canvas widget which is modelled after its [SVG][] counterpart. Items are put in a tree structure with a persistent root item with id 0. All other items are descendants of this root item. The path items, described below, are by default a child of the root item, but can be configured to be a child of any group item using the -parent option.

<a name="DISPLAY-LIST"></a>
### DISPLAY LIST

The items in a canvas are ordered for purposes of display, with the first item in the display list being displayed first, followed by the next item in the list, and so on. Items later in the display list obscure those that are earlier in the display list and are sometimes referred to as being "on top" of earlier items. When a new item is created it is placed at the end of the display list, on top of everything else. Widget commands may be used to re-arrange the order of the display list.

Window items are an exception to the above rules. The underlying window systems require them always to be drawn on top of other items. In addition, the stacking order of window items is not affected by any of the canvas widget commands; you must use the Tk [raise][] command and [lower][] command instead. 

Items can be structured using groups.

A group item is merely a placeholder for other items, similar to how a frame widget is a container for other widgets. It is a building block for the tree structure. Unlike other items, and unlike frame widgets, it doesn't display anything. It has no coordinates which is an additional difference. The root item is a special group item with id 0 and tags equal to "root". The root group can be configured like other items, but its -tags and -parent options are read only. Group items define the canvas tree structure:

      0----
          1
          2
          3
          4
          5----
              6
              7
          8----
              9
             10
         11
         12

Antialiasing, if available, is controlled by the variable **path::antialias**. To switch on set it to 1.

<a name="ITEM-IDS-AND-TAGS"></a>
### ITEM IDS AND TAGS

Items in a canvas widget may be named in either of two ways: by id or by tag. Each item has a unique identifying number, which is assigned to that item when it is created. The id of an item never changes and id numbers are never re-used within the lifetime of a canvas widget. 
Each item may also have any number of tags associated with it. A tag is just a string of characters, and it may take any form except that of an integer. For example, "x123" is OK but "123" is not. The same tag may be associated with many different items. This is commonly done to group items in various interesting ways; for example, all selected items might be given the tag "selected". 

The tag **all** is implicitly associated with every item in the canvas; it may be used to invoke operations on all the items in the canvas. Note that this presently also includes the root item which can result in some unexpected behavior. In many case you can operate on the root item (0) instead. As an example, if you want to move, scale etc. all items in canvas, then do:

> <code>
    pathName move 0 x y  
</code>

The tag **current** is managed automatically by Tk; it applies to the current item, which is the topmost item whose drawn area covers the position of the mouse cursor (different item types interpret this in varying ways; see the individual item type documentation for details). If the mouse is not in the canvas widget or is not over an item, then no item has the **current** tag. 

When specifying items in canvas widget commands, if the specifier is an integer then it is assumed to refer to the single item with that id. If the specifier is not an integer, then it is assumed to refer to all of the items in the canvas that have a tag matching the specifier. The symbol *tagOrId* is used below to indicate that an argument specifies either an id that selects a single item or a tag that selects zero or more items. 

*tagOrId* may contain a logical expressions of tags by using operators: "**&&**", "**\|\|**", "**^**", "**!**", and parenthesized subexpressions. For example: 

> <code>
    .c find withtag {(a&&!b)||(!a&&b)}  
</code>

or equivalently:
 
> <code>
    .c find withtag {a^b}  
</code>

will find only those items with either "a" or "b" tags, but not both. 

Some widget commands only operate on a single item at a time; if *tagOrId* is specified in a way that names multiple items, then the normal behavior is for the command to use the first (lowest) of these items in the display list that is suitable for the command. Exceptions are noted in the widget command descriptions below. 

<a name="COORDINATES"></a>
### COORDINATES

All coordinates related to canvases are stored as floating-point numbers. Coordinates and distances are specified in screen units, which are floating-point numbers optionally followed by one of several letters. If no letter is supplied then the distance is in pixels. If the letter is **m** then the distance is in millimeters on the screen; if it is **c** then the distance is in centimeters; **i** means inches, and **p** means printers points (1/72 inch). Larger y-coordinates refer to points lower on the screen; larger x-coordinates refer to points farther to the right. Coordinates can be specified either as an even number of parameters, or as a single list parameter containing an even number of x and y coordinate values. 

The command **path::pixelalign** says how the platform graphics library draw when we specify integer coordinates. Some libraries position a one pixel wide line exactly at the pixel boundaries, and smears it out, if antialiasing, over the adjecent pixels. This can look blurred since a one pixel wide black line suddenly becomes a two pixel wide grey line.  It seems that cairo and quartz (MacOSX) do this, while gdi+ on Windows doesn't. This command just provides the info for you so you may take actions. Either you can manually position lines with odd integer widths at the center of pixels (adding 0.5), or set the **path::depixelize** equal to 1, see below.

With the boolean variable **path::depixelize** equal to 1 we try to adjust coordinates for objects with integer line widths.

There can be subtle differences compared to the original canvas. One such situation is where an option value has switched from an integer to float (double).

<a name="TEXT-INDICES"></a>
### TEXT INDICES

Text items support the notion of an index for identifying particular positions within the item. In a similar fashion, line and polygon items support index for identifying, inserting and deleting subsets of their coordinates. Indices are used for commands such as inserting or deleting a range of characters or coordinates, and setting the insertion cursor position. An index may be specified in any of a number of ways, and different types of items may support different forms for specifying indices. Text items support the following forms for an index; if you define new types of text-like items, it would be advisable to support as many of these forms as practical. Note that it is possible to refer to the character just after the last one in the text item; this is necessary for such tasks as inserting new text at the end of the item. Lines and Polygons do not support the insertion cursor and the selection. Their indices are supposed to be even always, because coordinates always appear in pairs. 

*number*

> A decimal number giving the position of the desired character within the text item. 0 refers to the first character, 1 to the next character, and so on. If indexes are odd for lines and polygons, they will be automatically decremented by one. A number less than 0 is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item. For polygons, numbers less than 0 or greater then the length of the coordinate list will be adjusted by adding or subtracting the length until the result is between zero and the length, inclusive. 

**end**

> Refers to the character or coordinate just after the last one in the item (same as the number of characters or coordinates in the item). 

**insert**

> Refers to the character just before which the insertion cursor is drawn in this item. Not valid for lines and polygons. 

**sel.first**

> Refers to the first selected character in the item. If the selection is not in this item then this form is illegal. 

**sel.last**

> Refers to the last selected character in the item. If the selection is not in this item then this form is illegal. 

*@x,y*

> Refers to the character or coordinate at the point given by x and y, where x and y are specified in the coordinate system of the canvas. If x and y lie outside the coordinates covered by the text item, then they refer to the first or last character in the line that is closest to the given point. 

<a name="TRANSFORMATIONS"></a>
### TRANSFORMATIONS

Normally the origin of the canvas coordinate system is at the upper-left corner of the window containing the canvas. It is possible to adjust the origin of the canvas coordinate system relative to the origin of the window using the **xview** and **yview** widget commands; this is typically used for scrolling. Canvases do not support scaling or rotation of the canvas coordinate system relative to the window coordinate system. 
Individual items may be moved or scaled using widget commands described below, but they may not be rotated. 

Note that the default origin of the canvas's visible area is coincident with the origin for the whole window as that makes bindings using the mouse position easier to work with; you only need to use the **canvasx** and **canvasy** widget commands if you adjust the origin of the visible area. However, this also means that any focus ring (as controlled by the **-highlightthickness** option) and window border (as controlled by the **-borderwidth** option) must be taken into account before you get to the visible area of the canvas. 

Each path item has a **-matrix** option which defines the local coordinate system for that item. It is defined as a double list {a b c d tx ty} where a simple scaling is {sx 0 0 sy 0 0}, a translation {1 0 0 1 tx ty}, and a rotation around origin with an angle 'a' is {cos(a) sin(a) -sin(a) cos(a) 0 0}. The simplest way to interpret this is to design an extra coordinate system according to the matrix, and then draw the item in that system.

Inheritance works differently for the **-matrix** option than for the other options which are just overwritten. Instead any set -matrix option starting from the root, via any number of group items, to the actual item being displayed, are nested. That is, any defined matrices from the root down define a sequence of coordinate transformations.

The following functions provide some basic matrix operations such as rotation, translation etc.. All function return a matrix which can be used as value for the *-matrix* option.


<a name="path::matrix-rotate"></a>
**path::matrix rotate** *angle ?cx? ?cy?*

> Return matrix with rotation of *angle* around *cx, cy*.

<a name="path::matrix-scale"></a>
**path::matrix scale** *sx ?sy?*

> Return scaling matrix. If *sy* is not provided use *sx* for x and y direction.

<a name="path::matrix-flip"></a>
**path::matrix flip** *?cx? ?cy? ?fx? ?fy?*

> Return matrix with translation of *cx, cy* and flip with *fx* and *fy*.

<a name="path::matrix-rotateflip"></a>
**path::matrix rotateflip** *?angle? ?cx? ?cy? ?fx? ?fy?*

> Return matrix with rotation of *angle* around *cx, cy* and flip with *fx* and *fy*.

<a name="path::matrix-skewx"></a>
**path::matrix skewx** *?angle?*

> Return matrix with skew in x-direction of *angle*

<a name="path::matrix-skewy"></a>
**path::matrix skewy** *?angle?*

> Return matrix with skew in y-direction of *angle*

<a name="path::matrix-move"></a>
**path::matrix move** *dx dy*

> Return matrix with translation of *dx* in x-direction and *dy* in y-direction.

<a name="path::matrix-mult"></a>
**path::matrix mult** *ma mb*

> Return product of matrix multiplication of *ma* and *mb*.

<a name="STYLES"></a>
### STYLES

Styles are created and configured using:

> <code>
    path::style command ?options?  
</code>

<a name="path::style-cget"></a>
**path::style cget** *token option*

> Returns the value of an option.

<a name="path::style-configure"></a>
**path::style configure** *token ?option? ?value option value...?*

> Configures the object in the usual tcl way.

<a name="path::style-create"></a>
**path::style create** *?fillOptions strokeOptions?*

> Creates a style object and returns its token.

<a name="path::style-delete"></a>
**path::style delete** *token*

> Deletes the object.

<a name="path::style-inuse"></a>
**path::style inuse** *token*

> If any item is configured with the style token 1 is returned, else 0.

<a name="path::style-names"></a>
**path::style names**

> Returns all existing tokens.

The same options as for the item are supported with the exception of **-style**, **-state**, and **-tags**.

<a name="GRADIENTS"></a>
### GRADIENTS

Gradients are created and configured using:

> <code>
    path::gradient command ?options?  
</code>

<a name="path::gradient-cget"></a>
**path::gradient cget** *token option*

> Returns the value of an option.

<a name="path::gradient-configure"></a>
**path::gradient configure** *token ?option? ?value option value...?*

> Configures the object in the usual tcl way.

<a name="path::gradient-create"></a>
**path::gradient create** *type ?-key value ...?*

> Creates a linear gradient object with type any of linear or radial and returns its token.

<a name="path::gradient-delete"></a>
**path::gradient delete** *token*

> Deletes the object.

<a name="path::gradient-inuse"></a>
**path::gradient inuse** *token*

> If any item is configured with the gradient token 1 is returned, else 0.

<a name="path::gradient-names"></a>
**path::gradient names**

> Returns all existing tokens.

<a name="path::gradient-type"></a>
**path::gradient type** *token*

> Returns the type (linear\|radial) of the gradient. The options for linear gradients are:

> **-method** pad\|repeat\|reflect

> > Partial implementation; defaults to pad

> **-stops** *{stopSpec ?stopSpec...?}*

> > Where *stopSpec* is a list {offset color ?opacity?}. All offsets must be ordered and run from 0 to 1.

> **-lineartransition** *{x1 y1 x2 y2}*

> > Specifies the transtion vector relative the items bounding box. Depending on **-units** it gets interpreted differently. If **-units** is 'bbox' coordinates run from 0 to 1 and are relative the items bounding box. If **-units** is 'userspace' then they are defined in absolute coordinates but in the space of the items coordinate system. It defaults to {0 0 1 0}, left to right.

> **-matrix** *{a b c d tx ty}*

> > Sets a specific transformation for the gradient pattern only. NB: not sure about the order transforms, see **-units**.

> **-units** bbox\|userspace

> > Sets the units of the transition coordinates. See above. Defaults to 'bbox'.

The options for radial gradients are the same as for linear gradients except that the **-lineartransition** is replaced by a **-radialtransition**:

> **-radialtransition** *{cx cy ?r? ?fx fy?}*

> > Specifies the transition circles relative the items bounding box and run from 0 to 1. They default to {0.5 0.5 0.5 0.5 0.5}. *cx,cy* is the center of the end circle and *fx,fy* the center of the start point.

> **path::gradientstopstyle** *name args*

> Currently is only 'rainbow' as name supported. The function illustrate the  definition of gradients.

<a name="SURFACE"></a>
### SURFACE

In memory drawing surface.

<a name="path::surface-names"></a>
**path::surface names**

> Lists the existing surface tokens.

<a name="path::surface-new"></a>
**path::surface new** *width height*

> Creates an in memory drawing surface. Its format is platform dependent. It returns a *surfaceToken* which is a new command.

The surface token commands are:

> *surfaceToken* **copy** *imageName*

> > Copies the surface to an existing image (photo) and returns the name of
the image so you can do:

> > <code>
    set image [$token copy [image create photo]]  
</code>

> > See [Tk_PhotoPutBlock][] for how it affects the existing image.

> > The boolean variable **path::premultiplyalpha** controls how the copy action handles surfaces with the alpha component premultiplied. If 1 the copy process correctly handles any format with premultiplied alpha. This gets the highest quality for antialiasing and correct results for partial transparency. It is also slower. If 0 the alpha values are not remultiplied and the result is wrong for transparent regions, and gives poor antialiasing effects. But it is faster. The default is 1.

> *surfaceTtoken* **create** *type coords ?options?*

> > Draws the item of type to the surface. All item types except the group and the corresponding options as described above are supported, except the canvas specific **-tags** and **-state**.

> *surfaceToken* **destroy**

> > Destroys surface.

> *surfaceToken* **erase** *x y width height*

> > Erases the indicated area to transparent.

> *surfaceToken* **height**

> > Returns height.

> *surfaceToken* **width**

> > Returns width.

> Note that the surface behaves different from the canvas widget. When you have put an item there there is no way to configure it or to remove it. If you have done a mistake then you have to erase the complete surface and start all over. Better to experiment on the canvas and then reproduce your drawing to a surface when you are satisfied with it.

> NB: gdi+ seems unable to produce antialiasing effects here but there seems to be no gdi+ specific way of drawing in memory bitmaps but had to call CreateDIBSection() which is a Win32 GDI API.

<a name="WIDGET COMMAND"></a>
## WIDGET COMMAND

<a name="pathName-addtag"></a>
*pathName* **addtag** *tag searchSpec ?arg arg ...?*

> For each item that meets the constraints specified by *searchSpec* and the *args*, add *tag* to the list of tags associated with the item if it is not already present on that list. It is possible that no items will satisfy the constraints given by searchSpec and args, in which case the command has no effect. This command returns an empty string as result. *SearchSpec* and *arg'*s may take any of the following forms: 

> **above** *tagOrId*
	
> > Selects the item just after (above) the one given by *tagOrId* in the display list. If *tagOrId* denotes more than one item, then the last (topmost) of these items in the display list is used. The command is constrained to siblings.

> **all**

> > Selects all the items in the canvas. 

> **below** *tagOrId*

> > Selects the item just before (below) the one given by *tagOrId* in the display list. If *tagOrId* denotes more than one item, then the first (lowest) of these items in the display list is used. The command is constrained to siblings.

> **closest** *x y ?halo? ?start?*

> > Selects the item closest to the point given by *x* and *y*. If more than one item is at the same closest distance (e.g. two items overlap the point), then the topmost of these items (the last one in the display list) is used. If *halo* is specified, then it must be a non-negative value. Any item closer than *halo* to the point is considered to overlap it. The *start* argument may be used to step circularly through all the closest items. If *start* is specified, it names an item using a tag or id (if by tag, it selects the first item in the display list with the given tag). Instead of selecting the topmost closest item, this form will select the topmost closest item that is below start in the display list; if no such item exists, then the selection behaves as if the start argument had not been specified. 

> **enclosed** *x1 y1 x2 y2*

> > Selects all the items completely enclosed within the rectangular region given by *x1, y1, x2, and y2*. *X1* must be no greater then *x2* and *y1* must be no greater than *y2*. 

> **overlapping** *x1 y1 x2 y2*

> > Selects all the items that overlap or are enclosed within the rectangular region given by *x1, y1, x2,* and *y2*. *X1* must be no greater then *x2* and *y1* must be no greater than *y2*. 

> **withtag** *tagOrId*

> > Selects all the items given by *tagOrId*. 

<a name="pathName-ancestors"></a>
*pathName* **ancestors** *tagOrId*

> Returns a list of item id's of the first item matching *tagOrId* starting with the root item with id 0.

*pathName* **bbox** *tagOrId ?tagOrId tagOrId ...?*

> Returns a list with four elements giving an approximate bounding box for all the items named by the *tagOrId* arguments. The list has the form *x1 y1 x2 y2* such that the drawn areas of all the named elements are within the region bounded by *x1* on the left, *x2* on the right, *y1* on the top, and *y2* on the bottom. The return value may overestimate the actual bounding box by a few pixels. If no items match any of the *tagOrId* arguments or if the matching items have empty bounding boxes (i.e. they have nothing to display) then an empty string is returned. 

<a name="pathName-bind"></a>
*pathName* **bind** *tagOrId ?sequence? ?command?*

> This command associates *command* with all the items given by *tagOrId* such that whenever the event sequence given by *sequence* occurs for one of the items the command will be invoked. This widget command is similar to the [bind][] command except that it operates on items in a canvas rather than entire widgets. See the [bind][] manual entry for complete details on the syntax of sequence and the substitutions performed on command before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same *sequence* and *tagOrId* (if the first character of *command* is “+” then *command* augments an existing binding rather than replacing it). In this case the return value is an empty string. If *command* is omitted then the command returns the *command* associated with *tagOrId* and *sequence* (an error occurs if there is no such binding). If both *command* and *sequence* are omitted then the command returns a list of all the sequences for which bindings have been defined for *tagOrId*. 

> The only events for which bindings may be specified are those related to the mouse and keyboard (such as **Enter**, **Leave**, **ButtonPress**, **Motion**, and **KeyPress**) or virtual events. The handling of events in canvases uses the current item defined in [ITEM IDS AND TAGS][] above. **Enter** and **Leave** events trigger for an item when it becomes the current item or ceases to be the current item; note that these events are different than **Enter** and **Leave** events for windows. Mouse-related events are directed to the current item, if any. Keyboard-related events are directed to the focus item, if any (see the **focus** widget command below for more on this). If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event. 

> It is possible for multiple bindings to match a particular event. This could occur, for example, if one binding is associated with the item's id and another is associated with one of the item's tags. When this occurs, all of the matching bindings are invoked. A binding associated with the **all** tag is invoked first, followed by one binding for each of the item's tags (in order), followed by a binding associated with the item's id. If there are multiple matching bindings for a single tag, then only the most specific binding is invoked. A [continue][] command in a binding script terminates that script, and a [break][] command terminates that script and skips any remaining scripts for the event, just as for the [bind][] command. 

> If bindings have been created for a canvas window using the [bind][] command, then they are invoked in addition to bindings created for the canvas's items using the **bind** widget command. The bindings for items will be invoked before any of the bindings for the window as a whole. 

<a name="pathName-canvasx"></a>
*pathName* **canvasx** *screenx ?gridspacing?*

> Given a window x-coordinate in the canvas *screenx*, this command returns the canvas x-coordinate that is displayed at that location. If *gridspacing* is specified, then the canvas coordinate is rounded to the nearest multiple of *gridspacing* units. 

<a name="pathName-canvasy"></a>
*pathName* **canvasy** *screeny ?gridspacing?*

> Given a window y-coordinate in the canvas *screeny*, this command returns the canvas y-coordinate that is displayed at that location. If *gridspacing* is specified, then the canvas coordinate is rounded to the nearest multiple of *gridspacing* units. 

<a name="pathName-cget"></a>
*pathName* **cget** *option*

> Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **path** command. 

<a name="pathName-children"></a>
*pathName* **children** *tagOrId*

> Lists all children of the first item matching *tagOrId*.

<a name="pathName-configure"></a>
*pathName* **configure** *?option? ?value? ?option value ...?*

> Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for pathName (see [Tk_ConfigureInfo][] for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **path** command. 

<a name="pathName-coords"></a>
*pathName* **coords** *tagOrId ?x0 y0 ...?*

*pathName* **coords** *tagOrId ?coordList?*

> Query or modify the coordinates that define an item. If no coordinates are specified, this command returns a list whose elements are the coordinates of the item named by *tagOrId*. If coordinates are specified, then they replace the current coordinates for the named item. If *tagOrId* refers to multiple items, then the first one in the display list is used. 

<a name="pathName-create"></a>
*pathName* **create** *type x y ?x y ...? ?option value ...?*

*pathName* **create** *type coordList ?option value ...?*

> Create a new item in pathName of type *type*. The exact format of the arguments after type depends on *type*, but usually they consist of the coordinates for one or more points, followed by specifications for zero or more item options. See the subsections on individual item types below for more on the syntax of this command. This command returns the id for the new item. 

> For further informations about useable items see section [ITEM TYPES](#ITEM-TYPES).

<a name="pathName-dchars"></a>
*pathName* **dchars** *tagOrId first ?last?*

> For each item given by *tagOrId*, delete the characters, or coordinates, in the range given by *first* and *last*, inclusive. If some of the items given by *tagOrId* do not support indexing operations then they ignore this operation. Text items interpret *first* and *last* as indices to a character, line and polygon items interpret them as indices to a coordinate (an x,y pair). Indices are described in [INDICES][] above. If *last* is omitted, it defaults to *first*. This command returns an empty string. 

<a name="pathName-delete"></a>
*pathName* **delete** *?*tagOrId* *tagOrId* ...?*

> Delete each of the items given by each *tagOrId*, and return an empty string. 

<a name="pathName-depth"></a>
*pathName* **depth** *tagOrId*

> Returns the depth in the tree hierarchy of the first item matching *tagOrId*. The root item has depth 0 and children of the root has depth 1 and so on.

<a name="pathName-distance"></a>
*pathName* **distance** *tagOrId x y*

> Returns the closest distance between the point (*x, y*) and the first item matching *tagOrId*.

<a name="pathName-dtag"></a>
*pathName* **dtag** *tagOrId ?tagToDelete?*

> For each of the items given by *tagOrId*, delete the tag given by *tagToDelete* from the list of those associated with the item. If an item does not have the tag *tagToDelete* then the item is unaffected by the command. If *tagToDelete* is omitted then it defaults to *tagOrId*. This command returns an empty string. 

<a name="pathName-find"></a>
*pathName* **find** *searchCommand ?arg arg ...?*

> This command returns a list consisting of all the items that meet the constraints specified by *searchCommand* and *arg'*s. *SearchCommand* and *args* have any of the forms accepted by the **addtag** command. The items are returned in stacking order, with the lowest item first. 

<a name="pathName-firstchild"></a>
*pathName* **firstchild** *tagOrId*

> Returns the first child item of the first item matching *tagOrId*. Applies only for groups.

<a name="pathName-focus"></a>
*pathName* **focus** *?*tagOrId*?*

> Set the keyboard focus for the canvas widget to the item given by *tagOrId*. If *tagOrId* refers to several items, then the focus is set to the first such item in the display list that supports the insertion cursor. If *tagOrId* does not refer to any items, or if none of them support the insertion cursor, then the focus is not changed. If *tagOrId* is an empty string, then the focus item is reset so that no item has the focus. If *tagOrId* is not specified then the command returns the id for the item that currently has the focus, or an empty string if no item has the focus. 

> Once the focus has been set to an item, the item will display the insertion cursor and all keyboard events will be directed to that item. The focus item within a canvas and the focus window on the screen (set with the focus command) are totally independent: a given item does not actually have the input focus unless (a) its canvas is the focus window and (b) the item is the focus item within the canvas. In most cases it is advisable to follow the focus widget command with the focus command to set the focus window to the canvas (if it was not there already). 

<a name="pathName-gettags"></a>
*pathName* **gettags** *tagOrId*

> Return a list whose elements are the tags associated with the item given by *tagOrId*. If *tagOrId* refers to more than one item, then the tags are returned from the first such item in the display list. If *tagOrId* does not refer to any items, or if the item contains no tags, then an empty string is returned. 

<a name="pathName-gradient"></a>
*pathName* **gradient** *command ?options?*

> See [GRADIENTS][] for the commands. The gradients created with this command are local to the canvas instance. Only gradients defined this way can be used.

<a name="pathName-icursor"></a>
*pathName* **icursor** *tagOrId index*

> Set the position of the insertion cursor for the item(s) given by *tagOrId* to just before the character whose position is given by *index*. If some or all of the items given by *tagOrId* do not support an insertion cursor then this command has no effect on them. See INDICES above for a description of the legal forms for *index*. Note: the insertion cursor is only displayed in an item if that item currently has the keyboard focus (see the focus widget command, above), but the cursor position may be set even when the item does not have the focus. This command returns an empty string. 

<a name="pathName-imove"></a>
*pathName* **imove** *tagOrId index x y*

> This command causes the *index*'th coordinate of each of the items indicated by *tagOrId* to be relocated to the location (*x,y*). Each item interprets *index *independently according to the rules described in [INDICES][] above. Out of the standard set of items, only line and polygon items may have their coordinates relocated this way. 

> If you apply move on a group item it will apply this to all its descendants, also to child group items in a recursive way.

<a name="pathName-index"></a>
*pathName* **index** *tagOrId index*

> This command returns a decimal string giving the numerical index within *tagOrId* corresponding to *index*. Index gives a textual description of the desired position as described in INDICES above. Text items interpret *index* as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). The return value is guaranteed to lie between 0 and the number of characters, or coordinates, within the item, inclusive. If *tagOrId* refers to multiple items, then the *index* is processed in the first of these items that supports indexing operations (in display list order). 

<a name="pathName-insert"></a>
*pathName* **insert** *tagOrId beforeThis string*

> For each of the items given by *tagOrId*, if the item supports text or coordinate, insertion then string is inserted into the item's text just before the character, or coordinate, whose index is *beforeThis*. Text items interpret *beforeThis* as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). For lines and polygons the string must be a valid coordinate sequence. See INDICES above for information about the forms allowed for *beforeThis*. This command returns an empty string. 

<a name="pathName-itemcget"></a>
*pathName* **itemcget** *tagOrId option*

> Returns the current value of the configuration option for the item given by *tagOrId* whose name is *option*. This command is similar to the **cget** widget command except that it applies to a particular item rather than the widget as a whole. *Option* may have any of the values accepted by the **create** widget command when the item was created. If *tagOrId* is a tag that refers to more than one item, the first (lowest) such item is used. 

<a name="pathName-itemconfigure"></a>
*pathName* **itemconfigure** *tagOrId ?option? ?value? ?option value ...?*

> This command is similar to the **configure** widget command except that it modifies item-specific options for the items given by *tagOrId* instead of modifying options for the overall canvas widget. If no *option* is specified, returns a list describing all of the available options for the first item given by *tagOrId* (see [Tk_ConfigureInfo][] for information on the format of this list). If *option* is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s) in each of the items given by *tagOrId*; in this case the command returns an empty string. The *options* and *values* are the same as those permissible in the **create** widget command when the item(s) were created; see the sections describing individual item types below for details on the legal options. 

<a name="pathName-itempdf"></a>
*pathName* **itempdf** *tagOrId ?extgsProc objProc gradProc?*

> The command return pdf code describing the given *tagOrId*. The function is optimised to work with [pdf4tcl][]. To create pdf from a **path** just call the **canvas** method from the pdf object p.e.:

    $pdf canvas $pathName -bbox [$pathName bbox] -x 0 -y 0

> See function `CanvasDoTkpathItem` in [pdf4tcl][] for details.

> If *extgsProc* is given and item has special graphic state *extgsProc* is called.

> If *objProc* is given and item has special object info *objProc* is called.

> If *gradProc* is given and the item uses a gradient the *gradProc* is called.

<a name="pathName-lastchild"></a>
*pathName* **lastchild** *tagOrId*

> Returns the last child item of the first item matching *tagOrId*. Applies only for groups.

<a name="pathName-lower"></a>
*pathName* **lower** *tagOrId ?belowThis?*

> Move all of the items given by *tagOrId* to a new position in the display list just before the item given by *belowThis*. If *tagOrId* refers to more than one item then all are moved but the relative order of the moved items will not be changed. *BelowThis* is a tag or id; if it refers to more than one item then the first (lowest) of these items in the display list is used as the destination location for the moved items. Note: this command has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the [raise][] command and [lower][] command, not the **raise** widget command and **lower** widget command for canvases. This command returns an empty string.

> Movement is constrained to siblings. If reference *tagOrId* not given it defaults to first/last item of the root items children. Items which are not siblings to the reference *tagOrId* are silently ignored.

<a name="pathName-move"></a>
*pathName* **move** *tagOrId xAmount yAmount*

> Move each of the items given by *tagOrId* in the canvas coordinate space by adding *xAmount* to the x-coordinate of each point associated with the item and *yAmount* to the y-coordinate of each point associated with the item. This command returns an empty string. 

<a name="pathName-moveto"></a>
*pathName* **moveto** *tagOrId xPos yPos*

Move the items given by *tagOrId* in the canvas coordinate space so that the first coordinate pair of the bottommost item with tag *tagOrId* is located at position (*xPos,yPos*). *xPos* and *yPos* may be the empty string, in which case the corresponding coordinate will be unchanged. All items matching *tagOrId* remain in the same positions relative to each other. This command returns an empty string. 

<a name="pathName-nextsibling"></a>
*pathName* **nextsibling** *tagOrId*

> Returns the next sibling item of the first item matching *tagOrId*. If *tagOrId* is the last child we return empty.

<a name="pathName-parent"></a>
*pathName* **parent** *tagOrId*

> Returns the parent item of the first item matching *tagOrId*. This command works for all items, also for the standard ones. It is therefore better to use this than `cget id -parent` which is only supported for the new path items.

<a name="pathName-prevsibling"></a>
*pathName* **prevsibling** *tagOrId*

> Returns the previous sibling item of the first item matching *tagOrId*. If *tagOrId* is the first child we return empty.

<a name="pathName-raise"></a>
*pathName* **raise** *tagOrId ?aboveThis?*

> Move all of the items given by *tagOrId* to a new position in the display list just after the item given by aboveThis. If *tagOrId* refers to more than one item then all are moved but the relative order of the moved items will not be changed. AboveThis is a tag or id; if it refers to more than one item then the last (topmost) of these items in the display list is used as the destination location for the moved items. This command returns an empty string. 

> Movement is constrained to siblings. If reference *tagOrId* not given it defaults to first/last item of the root items children. Items which are not siblings to the reference *tagOrId* are silently ignored.

> Note: this command has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the raise command and lower command, not the raise widget command and lower widget command for canvases. 

<a name="pathName-rchars"></a>
*pathName* **rchars** *tagOrId first last string*

> This command causes the text or coordinates between *first* and *last* for each of the items indicated by *tagOrId* to be replaced by string. Each item interprets *first* and *last* independently according to the rules described in [INDICES][] above. Out of the standard set of items, text items support this operation by altering their text as directed, and line and polygon items support this operation by altering their coordinate list (in which case string should be a list of coordinates to use as a replacement). The other items ignore this operation. 

<a name="pathName-scale"></a>
*pathName* **scale** *tagOrId xOrigin yOrigin xScale yScale*

> Rescale the coordinates of all of the items given by *tagOrId* in canvas coordinate space. *XOrigin* and *yOrigin* identify the origin for the scaling operation and *xScale* and *yScale* identify the scale factors for x- and y-coordinates, respectively (a scale factor of 1.0 implies no change to that coordinate). For each of the points defining each item, the x-coordinate is adjusted to change the distance from *xOrigin* by a factor of *xScale*. Similarly, each y-coordinate is adjusted to change the distance from *yOrigin* by a factor of *yScale*. This command returns an empty string. 

> Note that some items have only a single pair of coordinates (e.g. windows) and so scaling of them by this command can only move them around.

> If you apply scale on a group item it will apply this to all its descendants, also to child group items in a recursive way. 

<a name="pathName-scan"></a>
*pathName* **scan** *option args*

> This command is used to implement scanning on canvases. It has two forms, depending on option: 

> *pathName* **scan mark** *x y*

> > Records *x* and *y* and the canvas's current view; used in conjunction with later scan dragto commands. Typically this command is associated with a mouse button press in the widget and *x* and *y* are the coordinates of the mouse. It returns an empty string. 

> *pathName* **scan dragto** *x y ?gain?*

> > This command computes the difference between its *x* and *y* arguments (which are typically mouse coordinates) and the x and y arguments to the last scan mark command for the widget. It then adjusts the view by *gain* times the difference in coordinates, where *gain* defaults to 10. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the canvas at high speed through its window. The return value is an empty string. 

<a name="pathName-select"></a>
*pathName* **select** *option ?*tagOrId* arg?*

> Manipulates the selection in one of several ways, depending on *option*. The command may take any of the forms described below. In all of the descriptions below, *tagOrId* must refer to an item that supports indexing and selection; if it refers to multiple items then the first of these that supports indexing and the selection is used. Index gives a textual description of a position within *tagOrId*, as described in [INDICES][] above. 

> *pathName* **select adjust** *tagOrId index*

> > Locate the end of the selection in *tagOrId* nearest to the character given by *index*, and adjust that end of the selection to be at *index* (i.e. including but not going beyond index). The other end of the selection is made the anchor point for future select to commands. If the selection is not currently in *tagOrId* then this command behaves the same as the select to widget command. Returns an empty string. 

> *pathName* **select clear**

> > Clear the selection if it is in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. 

> *pathName* **select from** *tagOrId index*

> > Set the selection anchor point for the widget to be just before the character given by *index* in the item given by *tagOrId*. This command does not change the selection; it just sets the fixed end of the selection for future select to commands. Returns an empty string. 

>  *pathName* **select item**

> > Returns the id of the selected item, if the selection is in an item in this canvas. If the selection is not in this canvas then an empty string is returned. 

> *pathName* **select to** *tagOrId index*

> > Set the selection to consist of those characters of *tagOrId* between the selection anchor point and *index*. The new selection will include the character given by *index*; it will include the character given by the anchor point only if *index* is greater than or equal to the anchor point. The anchor point is determined by the most recent select adjust or select from command for this widget. If the selection anchor point for the widget is not currently in *tagOrId*, then it is set to the same character given by *index*. Returns an empty string. 

<a name="pathName-style"></a>
*pathName* **style** *cmd ?options?*

> See [STYLES](#STYLES) for the commands. The styles created with this command are local to the canvas instance. Only styles defined this way can be used.

> The styleToken is a style created with 'pathName style create'. It's options take precedence over any other options set directly. This is how SVG works (bad?). Currently all a style's options ever set are recorded in a cumulative way using a mask. Even if an option is set to its default it takes precedence over an items option.

<a name="pathName-type"></a>
*pathName* **type** *tagOrId*

> Returns the type of the item given by *tagOrId*, such as rectangle or text. If *tagOrId* refers to more than one item, then the type of the first item in the display list is returned. If *tagOrId* does not refer to any items at all then an empty string is returned. 

<a name="pathName-types"></a>
*pathName* **types**

> List all item types defined in canvas.

<a name=*pathName-xview"></a>
*pathName* **xview** *?args?*

> This command is used to query and change the horizontal position of the information displayed in the canvas's window. It can take any of the following forms: 

> *pathName* **xview**

> > Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the canvas's area (as defined by the **-scrollregion** option) is off-screen to the left, the middle 40% is visible in the window, and 40% of the canvas is off-screen to the right. These are the same values passed to scrollbars via the **-xscrollcommand** option. 

> *pathName* **xview moveto** *fraction*

> > Adjusts the view in the window so that *fraction* of the total width of the canvas is off-screen to the left. *Fraction* must be a fraction between 0 and 1. 

> *pathName* **xview scroll** *number what*

> > This command shifts the view in the window left or right according to *number* and *what*. *Number* must be an integer. *What* must be either **units** or **pages** or an abbreviation of one of these. If *what* is units, the view adjusts left or right in **units** of the **xScrollIncrement** option, if it is greater than zero, or in units of one-tenth the window's width otherwise. If what is **pages** then the view adjusts in units of nine-tenths the window's width. If *number* is negative then information farther to the left becomes visible; if it is positive then information farther to the right becomes visible. 

<a name="pathName-yview"></a>
*pathName* **yview** *?args?*

> This command is used to query and change the vertical position of the information displayed in the canvas's window. It can take any of the following forms: 

> *pathName* **yview**

> > Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the vertical span that is visible in the window. For example, if the first element is .6 and the second element is 1.0, the lowest 40% of the canvas's area (as defined by the **-scrollregion** option) is visible in the window. These are the same values passed to scrollbars via the **-yscrollcommand** option. 

> *pathName* **yview moveto** *fraction*

> > Adjusts the view in the window so that *fraction* of the canvas's area is off-screen to the top. *Fraction* is a fraction between 0 and 1. 

> *pathName* **yview scroll** *number what*

> > This command adjusts the view in the window up or down according to *number* and *what*. *Number* must be an integer. *What* must be either **units** or **pages**. If *what* is **units**, the view adjusts up or down in units of the **yScrollIncrement** option, if it is greater than zero, or in units of one-tenth the window's height otherwise. If what is pages then the view adjusts in units of nine-tenths the window's height. If *number* is negative then higher information becomes visible; if it is positive then lower information becomes visible. 

<a name="ITEM-TYPES"></a>
## 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 do not 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. At present, text, line and polygon items provide this support. For lines and polygons the indexing facility is used to manipulate the coordinates of the item. 

<a name="COMMON-ITEM-OPTIONS"></a>
### COMMON ITEM OPTIONS

The options can be separated into a few groups depending on the nature of an item for which they apply. Not all are implemented.

Arrow options accepted by line, polyline and path objects. Arrows are not
implemented on surfaces (see path::surface).

Options set in a group are inherited by its children but they never override
options explicitly set in children. This also applies to group items configured
with a -style.

    .c create group ?fillOptions strokeOptions genericOptions?

<a name="ITEM-fill"></a>
**-fill** *color\|gradientToken*

> This is either a usual tk color or the name of a gradient.

<a name="ITEM-fillopacity"></a>
**-fillopacity** *value*

> The given *value* is a float value between 0.0 and 1.0

<a name="ITEM-fillrule"></a>
**-fillrule** *nonzero\|evenodd*

<a name="ITEM-stroke"></a>
**-stroke** *color*

<a name="ITEM-strokedasharray"></a>
**-strokedasharray** *dashArray*

> The *dashArray* is a list of integers. Each element represents the number of pixels of a line segment. Only the odd segments are drawn using the "outline" color. The other segments are drawn transparent. 

<a name="ITEM-strokelinecap"></a>
**-strokelinecap** *butt\|round\|square*

<a name="ITEM-strokelinejoin"></a>
**-strokelinejoin** *miter\|round\|bevel*

<a name="ITEM-strokemiterlimit"></a>
**-strokemiterlimit** *float*

<a name="ITEM-strokeopacity"></a>
**-strokeopacity** *value*

> The given *value* is a float value between 0.0 and 1.0

<a name="ITEM-strokewidth"></a>
**-strokewidth** *float*

<a name="ITEM-matrix"></a>
**-matrix** *{a b c d tx ty}*

<a name="ITEM-parent"></a>
**-parent** *tagOrId*

<a name="ITEM-state"></a>
**-state** *active\|disabled\|normal\|hidden*

<a name="ITEM-style"></a>
**-style** *styleToken*

<a name="ITEM-tags"></a>
**-tags** *tagList*

<a name="ITEM-startarrow"></a>
**-startarrow** *boolean*

> Arrowhead on/off; the default value is off.

<a name="ITEM-startarrowlength"></a>
**-startarrowlength** *float*

> Length of the arrowhead.
  * 0.0 is special and draws '|-----'
  * negative values draw '>----'

<a name="ITEM-startarrowwidth"></a>
**-startarrowwidth** *float*

> Arrow width; must be positive.

<a name="ITEM-startarrowfill"></a>
**-startarrowfill** *float*

> Relative to startarrowlength; for example:
  * 0.0: do not fill arrowhead, arrowhead will be two lines
  * 1.0: '<|-------'
  * 2.0: '<>-------'

<a name="ITEM-endarrow"></a>
**-endarrow** *boolean*

> See **-startarrow**.

<a name="ITEM-endarrowlength"></a>
**-endarrowlength** *float*

> See **-startarrowlength**.

<a name="ITEM-endarrowwidth"></a>
**-endarrowwidth** *float*

> See **-startarrowwidth**.

<a name="ITEM-endarrowfill"></a>
**-endarrowfill** *float*

> See **-startarrowfill**.

<a name="GROUP-ITEM"></a>
### GROUP ITEM

<a name="pathName-create-group"></a>
*pathName* **create group** *?fillOptions strokeOptions genericOptions?*

A group item is merely a placeholder for other items, similar to how a
frame widget is a container for other widgets. It is a building block for
the tree structure. Unlike other items, and unlike frame widgets, it
doesn't display anything. It has no coordinates which is an additional
difference. The root item is a special group item with id 0 and tags
equal to "root". The root group can be configured like other items, but
its -tags and -parent options are read only.
Options set in a group are inherited by its children but they never override
options explicitly set in children. This also applies to group items configured
with a -style.

<a name="PATH-ITEM"></a>
### PATH ITEM

<a name="pathName-create-path"></a>
*pathName* **create path** *pathSpec ?fillOptions strokeOptions arrowOptions genericOptions?*

The path specification must be a single list and not concateneted with the rest of the command:

    pathName create path {M 10 10 h 10 v 10 h -10 z} -fill blue
    pathName create path M 10 10 h 10 v 10 h -10 z -fill blue    ;# Error

Furthermore, coordinates are pixel coordinates and nothing else.
SVG: It implements the complete syntax of the path elements d attribute with
one major difference: all separators must be whitespace, no commas, no
implicit assumptions; all instructions and numbers must form a tcl list.

All path specifications are normalized initially to the fundamental atoms
M, L, A, Q, and C, all upper case. When you use the canvas 'coords' command
it is the normalized path spec that is returned. Bad?

Visualize this as a pen which always has a current coordinate after
the first M. Coordinates are floats:

* M x y

> Put the pen on the paper at specified coordinate. Must be the first atom but can appear any time later. The pen doesn't draw anything when moved to this point.

* L x y

> Draw a straight line to the given coordinate. 

* H x

> Draw a horizontal line to the given x coordinate.

* V y

> Draw a vertical line to the given y coordinate.

* A rx ry phi largeArc sweep x y

> Draw an elliptical arc from the current point to (x, y). The points are on an ellipse with x-radius rx and y-radius ry. The ellipse is rotated by phi degrees. If the arc is less than 180 degrees, largeArc is zero, else it is one. If the arc is to be drawn in cw direction, sweep is one, and zero for the ccw direction.

> NB: the start and end points may not coincide else the result  is undefined. If you want to make a circle just do two 180 degree arcs.

* Q x1 y1 x y

> Draw a qadratic Bezier curve from the current point to (x, y) using control point (x1, y1).

* T x y

> Draw a qadratic Bezier curve from the current point to (x, y) The control point will be the reflection of the previous Q atoms control point. This makes smooth paths.

* C x1 y1 x2 y2 x y

> Draw a cubic Bezier curve from the current point to (x, y) using control points (x1, y1) and (x2, y2).

* S x2 y2 x y

> Draw a cubic Bezier curve from the current point to (x, y), using (x2, y2) as the control point for this new endpoint. The first control point will be the reflection of the previous C atoms ending control point. This makes smooth paths.

* Z
   
> Close path by drawing from the current point to the preceeding M point.

You may use lower case characters for all atoms which then means that all
coordinates, where relevant, are interpreted as coordinates relative the
current point.

Helper function for making path definitions:

> **path::path ellipse** *x y rx ry*

> > The function return a path definition of an ellipse with a middle point at *x* and *y* and a radius in x-disrection of *rx* and a radius in y-direction of *ry*.

> **path::path circle** *x y r*

> > The function return a path definition of an circle with a middle point at *x* and *y* and a radius of *r*.

<a name="LINE-ITEM"></a>
### LINE ITEM

<a name="pathName-create-line"></a>
*pathName* **create line** *x1 y1 x2 y2 ?strokeOptions arrowOptions genericOptions?*

Makes a single-segment straight line.

<a name="POLYLINE-ITEM"></a>
### POLYLINE ITEM

<a name="pathName-create-polyline"></a>
*pathName* **create polyline** *x1 y1 x2 y2 .... ?strokeOptions arrowOptions genericOptions?*

Makes a multi-segment line with open ends.

<a name="POLYGON-ITEM"></a>
### POLYGON ITEM

<a name="pathName-create-polygon"></a>
*pathName* **create polygon** *x1 y1 x2 y2 .... ?fillOptions strokeOptions genericOptions?*

Makes a closed polygon.

<a name="RECT-ITEM"></a>
### RECT ITEM

<a name="pathName-create-rect"></a>
*pathName* **create rect** *x1 y1 x2 y2 ?-rx value? ?-ry value? ?fillOptions strokeOptions genericOptions?*

This is a rectangle item with optionally rounded corners.
Item specific options:

**-rx** *value*

> Corner x-radius, or if -ry not given it sets the uniform radius.

**-ry** *value*

> Corner y-radius

<a name="CIRCLE-ITEM"></a>
### CIRCLE ITEM

<a name="pathName-create-circle"></a>
*pathName* **create circle** *cx cy ?-r fillOptions strokeOptions genericOptions?*

A plain circle item. Item specific options:

**-r** *value*

> Its radius; defaults to zero

<a name="ELLIPSE-ITEM"></a>
### ELLIPSE ITEM

<a name="pathName-create-ellipse"></a>
*pathName* **create ellipse** *cx cy ?-rx value? ?-ry value? ?fillOptions strokeOptions genericOptions?*

An ellipse item. Item specific options:

**-rx** *value*

> Its x-radius

**-ry** *value*

> Its y-radius


<a name="IMAGE-ITEM"></a>
### IMAGE ITEM

<a name="pathName-create-image"></a>
*pathName* **create image** *x y ?-image -width -height genericOptions?*

This displays an image in the canvas anchored nw. If -width or -height is
nonzero then the image is scaled to this size prior to any affine transform.

image extra options:

**-anchor** *n\|w\|s\|e\|nw\|ne\|sw\|se\|c*

> Default value is nw

**-tintcolor** *color*

> Tint color; the default value is "" which means no tinting

**-tintamount** *value*

*Value* is amount for tinting between 0. and 1.

**-interpolation** *mode*

> Image interpolation *mode* is one of **none, fast** or **best**

**-srcregion** *{x1 y1 x2 y2}*

> Shows only the specified region of image; if x2 or y2 are larger than the image bounds, then the image will be repeated (tiling)

These options are not implemented on surfaces (see path::surface).

<a name="TEXT-ITEM"></a>
### TEXT ITEM

<a name="pathName-create-text"></a>
*pathName* **create text** *x y ?-text string? ?-textanchor start\|middle\|end\|n\|w\|s\|e\|nw\|ne\|sw\|se\|c? ?-fontfamily fontname -fontsize float? ?-fontslant normal\|italic\|oblique? ?-fontweight normal\|bold? ?fillOptions strokeOptions genericOptions? ?-filloverstroke BOOLEAN?*

Displays text as expected. Note that the x coordinate marks the baseline
of the text. Gradient fills are unsupported so far. Especially the font
handling and settings will likely be developed further.
Editing not implemented. The default font family and size is platform dependent.

text extra options:

**-textanchor** *n\|w\|s\|e\|nw\|ne\|sw\|se\|c\|start\|middle\|end*

> Textanchor extended with points of compass.

**-fontslant** *normal\|italic\|oblique*

> Default value is normal

**-fontweight** *normal\|bold*

> Default value is normal

**-filloverstroke** *boolean*

> Fill drawn over the stroke; default value is false

These options are not implemented on surface items (path::surface), except for

**-textanchor** *start\|middle\|end*

<a name="WINDOW-ITEM"></a>
### WINDOW ITEM

Items of type window cause a particular window to be displayed at a given position on the canvas. Window items are created with widget commands of the following form: 

<a name="pathName-create-window"></a>
*pathName* **create window** *x y ?option value ...?*

*pathName* **create window** *coordList ?option value ...?*

The arguments x and y or coordList (which must have two elements) specify the coordinates of a point used to position the window on the display, as controlled by the -anchor option. 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. Theoretically, a window item becomes the current item when the mouse pointer is over any part of its bounding box, but in practice this typically does not happen because the mouse pointer ceases to be over the canvas at that point. 

The following standard options are supported by window items: 

> **-anchor**

> **-state**

> **-tags**

The following extra options are supported for window items: 

**-height** *pixels*

> Specifies the height to assign to the item's window. Pixels may have any of the forms described in the [COORDINATES][] section above. If this option is not specified, or if it is specified as zero, then the window is given whatever height it requests internally. 

**-width** *pixels*

> Specifies the width to assign to the item's window. Pixels may have any of the forms described in the [COORDINATES][] section above. If this option is not specified, or if it is specified as zero, then the window is given whatever width it requests internally. 

**-window** *pathName*

> Specifies the window to associate with this item. The window specified by pathName must either be a child of the canvas widget or a child of some ancestor of the canvas widget. PathName may not refer to a top-level window. 

Note: due to restrictions in the ways that windows are managed, it is not possible to draw other graphical items (such as lines and images) on top of window items. A window item always obscures any graphics that overlap it, regardless of their order in the display list. Also note that window items, unlike other canvas items, are not clipped for display by their containing canvas's border, and are instead clipped by the parent widget of the window specified by the -window option; when the parent widget is the canvas, this means that the window item can overlap the canvas's border. 

<a name="BINDINGS"></a>
## BINDINGS

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

<a name="CREDITS"></a>
## 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.

[Tkpath][] was originally developed by Matts Bengtsson.

User visisble changes to the original [Tkpath][] code are:

- changed widget name in **path** and use of namespace **::path**
- -matrix is now a flat list
- tk canvas items removed, only exception is **window** item
- changed item names to match [SVG][] names:
  - **pimage** => **image**
  - **pline** => **line**
  - **ppolygon** => **polygon**
  - **prect** => **rect**
  - **ptext** => **text**
- no unique abbreviations of widget commands

<a name="KEYWORDS"></a>
## KEYWORDS

canvas, svg, widget

<a name="COPYRIGHT"></a>
## COPYRIGHT

&copy; 2005-2008 Mats Bengtsson

&copy; 2015- Christian Werner <[email protected]>

&copy; 2016- René Zaumseil <[email protected]>

BSD style license.

<a name="SEE-ALSO"></a>
## SEE ALSO

[bind][], [font][], [image][], [scrollbar][], [pdf4tcl][], [SVG][], [Cairo][]

<a name="KEYWORDS"></a>
## KEYWORDS

canvas, pdf, svg, widget

[bind]: bind.htm
[break]: break.htm
[continue]: continue.htm
[font]: font.htm
[image]: image.htm
[options]: options.htm
[raise]: raise.htm
[scrollbar]: scrollbar.htm
[lower]: lower.htm
[Tk_ConfigureInfo]: ConfigWidg.htm
[Tkpath]: <https://sourceforge.net/projects/tclbitprint/>
[pdf4tcl]: <https://sourceforge.net/projects/pdf4tcl/>
[SVG]: <http://www.w3.org/TR/SVG11/>
[Cairo]: <http://cairographics.org>

# tkoWidget(3) -- oo class like widgets

*   [NAME](#NAME)
*   [SYNOPSIS](#SYNOPSIS)
*   [ARGUMENTS](#ARGUMENTS)  
*   [DESCRIPTION](#DESCRIPTION)  
*   [SEE ALSO](#SEE-ALSO)  
*   [KEYWORDS](#KEYWORDS)  
*   [COPYRIGHT](#COPYRIGHT)  

<a name="NAME"></a>
## NAME

TkoWidgetClassDefine,
TkoWidgetOptionVar,
TkoWidgetOptionGet,
TkoWidgetOptionSet,
TkoWidgetWindow -- tko widget class commands

<a name="SYNOPSIS"></a>
## SYNOPSIS

**#include "tkoWidget.h"**

int  
**TkoWidgetClassDefine**(*interp,clazz,classname,methods,options*)  
Tk\_Window \*  
**TkoWidgetWindow**(*object*)  
Tcl\_Obj \*  
**TkoWidgetOptionVar**(*object*)  
Tcl\_Obj \*  
**TkoWidgetOptionGet**(*interp,object,option*)  
int  
**TkoWidgetOptionSet**(*interp,context,option,type,meta,offset*)  

<a name="ARGUMENTS"></a>
## ARGUMENTS

| Tcl\_Interp **\*interp** | Used interpreter.  
| Tcl\_Class **clazz** | Oo class of widget.  
| Tcl\_Obj **\*classname** |Oo class name of widget.  
| const Tcl\_MethodType **\*methods** | This array defines class methods to create. For creation methods see [Tcl_NewMethod] manpage. If the method name of the first array entry is not NULL it will be used as **constructor**, if the second method name is not NULL it used as **destructor**. Then follow public methods until an entry with an method name equal NULL comes. Then follow private methods until an entry with an method name equal NULL comes.  
| const tkoWidgetOptionDefine **\*options** | This array contain option definitions.  
| Tcl\_Object **object** | This is the current object reference.  
| Tcl\_Obj **\*option** | The name of the used option.  
| Tcl\_ObjectContext **context** | The context of the current object. Used to get associated object data.  
| tkoWidgetOptionType **type** | A type used in the common option setting routine.  
| Tcl\_ObjectMetadataType **\*meta** | The type of metadata attaches to the current object.  
| size\_t **offset** | Offset of variable to set in the attaches meta data record.  

<a name="DESCRIPTION"></a>
## DESCRIPTION

The **TkoWidgetClassDefine** function can be used to define options and methods of an **tko::widget** subclass. The function is used in the widget class definition of a new tko widget class.

The **TkoWidgetWindow** function return the address of the internally created Tk\_Window. Subclasses should check the address on NULL after creation. If the Tk\_Window\* at these address is NULL the widget is destroyed and it should not be used.

The **TkoWidgetOptionVar** function return the globally accessible name of the array variable holding the option values. Additionall there is an field "**.**" containing the tk widget path name of the widget.

The **TkoWidgetOptionGet** function returns the current value of the given option.

The **TkoWidgetOptionSet** function can be used to check given *option* values and set C record structure fields at the given *offset*. The record will be retrieved using the given *meta* metadata. The *type* must be one of the **tkoWidgetOptionType** described below.

### Struct: `tkoWidgetOptionDefine`

    typedef struct tkoWidgetOptionDefine {
      const char *option;    /* Name of option. Starts with "-" minus sign */
      const char *dbname;    /* Option DB name or synonym option if dbclass is NULL */
      const char *dbclass;   /* Option DB class name or NULL for synonym options. */
      const char *defvalue;  /* Default value. */
      int flags;             /* bit array of TKO_OPTION_* values to configure option behaviour */
      Tcl_Obj *optionPtr;    /* tko internally used, always init with NULL! */
      const char *proc;      /* If not NULL it is the body of the newly created -option method */
      Tcl_MethodCallProc *method;     /* If not NULL it is the function name of the -option method */
      tkoWidgetOptionType type;       /* if greater 0 then option type used in common option set method */
      Tcl_ObjectMetadataType *meta;   /* meta data address used in common option set method */
      int offset;            /* offset in meta data struct */
    } tkoWidgetOptionDefine;
    #define TKO_OPTION_READONLY 0x1 /* option is only setable at creation time */
    #define TKO_OPTION_HIDE     0x2 /* option is hidden in configure method */ 

### Enum: `tkoWidgetOptionType`

Suported enum type in the TkowidgetOptinSet() function. In comments is the type of the address provided in the **TkoWidgetOptionSet** funtion.

    typedef enum tkoWidgetOptionType {
        TKO_SET_CLASS = 1,     /* (Tcl_Obj **)address */
        TKO_SET_VISUAL, /* (Tcl_Obj **)address */
        TKO_SET_COLORMAP,       /* (Tcl_Obj **)address */
        TKO_SET_USENULL,        /* (Tcl_Obj **)address */
        TKO_SET_CONTAINER,      /* (int *)address */
        TKO_SET_TCLOBJ, /* (Tcl_Obj **)address */
        TKO_SET_XCOLOR, /* (Xcolor **)address */
        TKO_SET_3DBORDER,       /* (Tk_3DBorder *)address */
        TKO_SET_PIXEL,  /* (int *)address */
        TKO_SET_PIXELNONEGATIV, /* (int *)address */
        TKO_SET_PIXELPOSITIV,   /* (int *)address */
        TKO_SET_DOUBLE, /* (double *)address */
        TKO_SET_BOOLEAN,        /* (int *)address */
        TKO_SET_CURSOR, /* (Tk_Cursor *)address */
        TKO_SET_INT,    /* (int *)address */
        TKO_SET_RELIEF, /* (int *)address */
        TKO_SET_ANCHOR, /* (int *)address */
        TKO_SET_WINDOW, /* (Tk_Window *)address */
        TKO_SET_FONT,   /* (Tk_Font *)address */
        TKO_SET_STRING, /* (char **)address */
        TKO_SET_STRINGNULL,     /* (char **)address */
        TKO_SET_SCROLLREGION,   /* (int *[4])address */
        TKO_SET_JUSTIFY /* (Tk_Justify *)address */
    } tkoWidgetOptionType;

<a name="SEE-ALSO"></a>
## SEE ALSO

[frame][], [labelframe][], [toplevel][], [oo::class][]

<a name="KEYWORDS"></a>
## KEYWORDS

oo widget method option

<a name="COPYRIGHT"></a>
## COPYRIGHT

&copy; 2019- René Zaumseil <[email protected]>

BSD style license.

[options]: options.htm
[frame]: frame.htm
[labelframe]: labelframe.htm
[toplevel]: toplevel.htm
[oo::class]: class.htm
[graph]: graph.htm
[path]: path.htm
[Tkpath]: <https://sourceforge.net/projects/tclbitprint/>
[Rbc]: <https://sourceforge.net/projects/rbctoolkit/>

# tko::widget(n) -- oo class like widgets

*   [SYNOPSIS](#SYNOPSIS)
*   [TKO STANDARD OPTIONS](#TKO-STANDARD-OPTIONS)  
  [-class, class, Class](#-class)  
  [-screen, screen, Screen](#-screen)  
*   [DESCRIPTION](#DESCRIPTION)  
*   [WIDGET METHODS](#WIDGET-METHODS)  
*   [WIDGET OPTIONS](#WIDGET-OPTIONS)  
*   [EXAMPLES](#EXAMPLES)  
*   [SEE ALSO](#SEE-ALSO)  
*   [KEYWORDS](#KEYWORDS)  
*   [COPYRIGHT](#COPYRIGHT)  

<a name="SYNOPSIS"></a>
## SYNOPSIS

    oo::class create myWidget {
      {*}$::tko::unknown    ;# define unknown method to support common tk widget style
      superclass "tkoClass" ;# one of the provided tko widget class's
      variable tko          ;# array with options *$tko(-option)* and widget path *$tko(.)*
      method -myoption {...};# deal with option when set
      ...
      constructor {optionlist arglist} {
        next [concat {
          {-myoption myOption MyOption value}
          ...
        } $optionlist] $arglist
        ...
      }
      destructor {next}
    }

The command creates a new Tcl class whose name is *widgetClass*. This command may be used to create new widgets. Each new widget class has as a *tkoClass* as superclass. The common functionality is in the **tko::widget** class. Currently the following *tkoClass* superclasses are provided:

**::tko::toplevel** *pathName ?option value? ..*

**::tko::frame** *pathName ?option value? ..*

**::tko::labelframe** *pathName ?option value? ..*

**::graph** *pathName ?option value? ..*

**::path** *pathName ?option value? ..*

<a name="TKO-STANDARD-OPTIONS"></a>
## TKO STANDARD OPTIONS

<a name="-class"></a>
Command-Line Name: **-class**  
Database Name: **class**  
Database Class: **Class**

> > Define class for use in getting values from option database. Can only be set on widget creation time.

<a name="-screen"></a>
Command-Line Name: **-screen**  
Database Name: **screen**  
Database Class: **Screen**

> > Affect creation of underlying widget structure. If given the created widget will be a toplevel widget.

<a name="DESCRIPTION"></a>
## DESCRIPTION

The **tko::widget** class contain the common widget functionality. To get these functionality you have to create a subclass of the **tko::widget** class. This can only be done in C. To use the functionality on tcl script level the following classes are provided.

<a name="tko-toplevel"></a>
## tko::toplevel

These class contain the functionality of the [toplevel][] widget command.

<a name="tko-frame"></a>
## tko::frame

These class contain the functionality of the [frame][] widget command.

<a name="tko-labelframe"></a>
## tko::labelframe

These class contain the functionality of the [labelframe][] widget command.

<a name="tko-graph"></a>
## graph

These class contain the functionality of the [Rbc][] graph widget command. It is described in detail in the [graph][] manpage.

<a name="tko-path"></a>
## path

These class contain the functionality of the [Tkpath][] widget command. It is described in detail in the [path][] manpage.

<a name="WIDGET-METHODS"></a>
### WIDGET METHODS

Widget methods can be dynamically added and removed at class or object level.

**NOTE** Do not change *tkoClass*'s behaviour. Instead create your own class and modify it to your need! Or change created widget objects behaviour.

The **tko::widget** class provides the following methods.

<a name="method-constructor"></a>
**constructor {optionlist arglist}**

> The *optionlist* contain a sorted list off option descriptions as described in **configure optonadd**. It will be processed in the **tko::widget** constructor in the given order. It should always start with the "-class" option definition. The necessary *-option* method's should already be exist.

> The *arglist* is the normal *-option value ..* list of all tk widgets.

> Each widget class constructor should call **next** *$optionlist $arglist*!


<a name="method-destructor"></a>
**destructor {}**

> Here you can free your own ressources. Don't forget to call **next**! After **next** the **tko::widget** data are gone (widget path, tko array variable).

<a name="method-cget"></a>
**cget** *option*

> Return the current vlaue of the given *option*.

<a name="method-configure"></a>
**configure** *args*

> **configure**

> > If *args* is empty the method will return a sorted list of all configuration options.

> **configure** *-option*

> > If we have one element in *args* starting with a minus sign ("-") then the method return the configuration list including the current value of the given *-option*.

> **configure** *-option value ..*

> > If we have an even number list in *args* and the first element starts with a minus sign ("-") then the method does configure all the given option-value pairs. If an error occurs the the corresponding element is not set and the method gives an error. Alrready successfull set options remain.

> **configure init**

> > This is an internal function used in constructing new widgets. It is used in the *unknown* method to initialize all options.

> **configure optionadd** *-synonym -option*

> > Add a *-synonym* for a given *-option*. The *-option* needs not to be defined at this time.

> **configure optionadd** *-synonym dbnam dbclass ?default? ?flags?*

> > Add a new option. If ?flags? is equal "1" then the option is readonly and can only be set in this call. Before adding a new option a *-option* method must created. The method will be called without any arguments. The method can access the new value using the *tko(-option)* array variable. If the method throws a n error the array variable will be reset to the old value.

> **configure optiondel** *-option*

> > Delete the given option and unset the entry in the tko array variable. The created *-option* method's are not deleted. This is the task of the caller.

> **configure optionhide** *?-option? ..*

> > If no *-option* is given return a list of all not configure'able options. Otherwise hide all of the given options.

> **configure optionshow** *?-option? ..*

> > If no *-option* is given return a list of all configure'able options. Otherwise make all of the given options configure'able.

> **configure optionvar**

> > The method return the global varname of the tko array variable holding all option values.

<a name="method-cget"></a>
**\_tko\_configure**

> This is an virtuel method of the **tko::widget** class. This method will be called at the end of each **configure** *-option value ..* call. It can be implemented in each class to amke necessary changes. If it is implemented it should also call **next** to notify underlying classes.

<a name="WIDGET-OPTIONS"></a>
### WIDGET OPTIONS

Widget option values are saved in an option array. The option name is the field name in the array. Additionally is an field "**.**" containing the tk widget path name of the widget. The name of the option array variable can be retrieved using the following code:
    set myVar [.w configure optionvar]
    parray $myVar

Widget options can be dynamically added and removed at class or object level.
It is possible to hide and unhide options.

<a name="EXAMPLES"></a>
### EXAMPLES

    # Add options at class creation:
    oo::class create ::myWidget {
      {*}$::tko::unknown
      superclass ::tko::frame
      variable tko
      method -myoption {} {puts $tko(-myoption)}
      method -myreadonly {} {puts $tko(-myreadonly)}
      constructor {optionlist arglist} {
        next [concat {
          {-myoption myOption MyOption value}
          {-myreadonly myReadonly MyReadonly value 1}
        } $optionlist] $arglist
      }
    }
    proc output {} {
      puts "config: [.w configure]"
      puts "normal: [.w configure optionhide]"
      puts "hidden: [.w configure optionshow]"
    }
    # Add options at object level:
    ::myWidget .w
    oo::objdefine .w method -o1 {} {my variable tko; puts $tko(-o1)}
    oo::objdefine .w method -o2 {} {my variable tko; puts $tko(-o2)}
    .w configure optionadd -o1 o1 O1 v1 1 ;#->
    .w configure optionadd -o2 o2 O2 v2
    output
    # Remove one and hide rest
    .w configure optiondel -o2
    .w configure optionhide {*}[.w configure optionshow]
    output
    # Reverse state
    .w configure optionshow {*}[.w configure optionhide]
    output


<a name="SEE-ALSO"></a>
## SEE ALSO

[frame][], [labelframe][], [toplevel][], [oo::class][]

<a name="KEYWORDS"></a>
## KEYWORDS

oo widget method option

<a name="COPYRIGHT"></a>
## COPYRIGHT

&copy; 2019- René Zaumseil <[email protected]>

BSD style license.

[options]: options.htm
[frame]: frame.htm
[labelframe]: labelframe.htm
[toplevel]: toplevel.htm
[oo::class]: class.htm
[graph]: graph.htm
[path]: path.htm
[Tkpath]: <https://sourceforge.net/projects/tclbitprint/>
[Rbc]: <https://sourceforge.net/projects/rbctoolkit/>

# graph::vector(n) -- Vector data type for graph widgets

*   [SYNOPSIS](#SYNOPSIS)
*   [DESCRIPTION](#DESCRIPTION)
*   [SYNTAX](#SYNTAX)
  * [graph::vector configure](#graph::vector-configure) *?option value?...*
  * [graph::vector create](#graph::vector-create) *vectorName?(...)? ?option value?...*
  * [graph::vector destroy](#graph::vector-destroy) *vectorName ?vectorName?...*
  * [graph::vector expression](#graph::vector-expression) *expression*
  * [graph::vector names](#graph::vector-names) *?pattern...?*
  * [graph::vector op](#graph::vector-op) *operation vectorName ?arg?...*
*   [VECTOR INDICES](#VECTOR-INDICES)
*   [VECTOR OPERATIONS](#VECTOR-OPERATIONS)
  * [vectorName +](#vectorName-plus") *item*
  * [vectorName -](#vectorName-minus") *item*
  * [vectorName `*`](#vectorName-mult") *item*
  * [vectorName /](#vectorName-div") *item*
  * [vectorName append](#vectorName-append) *item ?item?...*
  * [vectorName binread](#vectorName-binread) *channel ?length? ?switches?*
  * [vectorName binwrite](#vectorName-binwrite) *channel ?length? ?-at index?*
  * [vectorName clear](#vectorName-clear)
  * [vectorName delete](#vectorName-delete) *index ?index?...*
  * [vectorName dup](#vectorName-dup) *destName*
  * [vectorName expr](#vectorName-expr) *expression*
  * [vectorName index](#vectorName-index) *index ?value?...*
  * [vectorName insert](#vectorName-insert) *index item ?item?...*
  * [vectorName length](#vectorName-length) *?newSize?*
  * [vectorName matrix](#vectorName-matrix) *...*
    * [vectorName matrix copy](#vectorName-matrix-copy) *dstcolumn srccolumn ?srcVec?*
    * [vectorName matrix delete](#vectorName-matrix-delete) *column*
    * [vectorName matrix get](#vectorName-matrix-get) *column*
    * [vectorName matrix insert](#vectorName-matrix-insert) *column ?initvalue?*
    * [vectorName matrix multiply](#vectorName-matrix-multiply) *srcVec ?dstVec?*
    * [vectorName matrix numcols](#vectorName-matrix-numcols) *?size?*
    * [vectorName matrix numrows](#vectorName-matrix-numrows) *?size?*
    * [vectorName matrix set](#vectorName-matrix-set) *column ?valuelist?*
    * [vectorName matrix shift](#vectorName-matrix-shift) *column amount ?startoffset?*
    * [vectorName matrix sort](#vectorName-matrix-sort) *column ?-reverse?*
    * [vectorName matrix transpose](#vectorName-matrix-transpose)
  * [vectorName merge](#vectorName-merge) *srcName ?srcName?...*
  * [vectorName notify](#vectorName-notify) *?keyword? ?script?*
  * [vectorName populate](#vectorName-populate) *destName ?density?*
  * [vectorName range](#vectorName-range) *firstIndex ?lastIndex?...*
  * [vectorName search](#vectorName-search) *value ?value?*
  * [vectorName set](#vectorName-set) *item*
  * [vectorName seq](#vectorName-seq) *start ?finish? ?step?*
  * [vectorName sort](#vectorName-sort) *?-reverse? ?argName?...*
  * [vectorName split](#vectorName-split) *dstName ?dstName?...*
  * [vectorName variable](#vectorName-variable) *varName*
* [C LANGUAGE API](#C-LANGUAGE-API)
* [LIBRARY ROUTINES](#LIBRARY-ROUTINES)
* [C API EXAMPLE](#C-API-EXAMPLE)
* [INCOMPATIBILITIEA](#INCOMPATIBILITIES)
* [EXAMPLE](#EXAMPLE)
* [CREDITS](#CREDITS)  
* [KEYWORDS](#KEYWORDS)
* [COPYRIGHT](#COPYRIGHT)

<a name="SYNOPSIS"></a>
## SYNOPSIS 

**[graph::vector configure](#graph::vector-configure)** *?option value? ...*

**[graph::vector create](#graph::vector-create)** *vectorName?(...)? ?option value?...*

**[graph::vector destroy](#graph::vector-destroy)** *vectorName ?vectorName...?*

**[graph::vector expr](#graph::vector-expr)** *expression*

**[graph::vector names](#graph::vector-names)** *?pattern...?*

**[graph::vector op](#graph::vector-op)** *operation vectorName ?arg?...*

<a name="DESCRIPTION"></a>
## DESCRIPTION 

The vector command creates a vector of floating point values. The vector's components can be manipulated in three ways: through a Tcl array variable, a Tcl command, or the C API.

A vector is simply an ordered set of numbers. The components of a vector are real numbers, indexed by counting numbers.

Vectors are common data structures for many applications. For example, a graph may use two vectors to represent the X-Y coordinates of the data plotted. The graph will automatically be redrawn when the vectors are updated or changed. By using vectors, you can separate data analysis from the graph widget. This makes it easier, for example, to add data transformations, such as splines. It's possible to plot the same data to in multiple graphs, where each graph presents a different view or scale of the data.

You could try to use Tcl's associative arrays as vectors. Tcl arrays are easy to use. You can access individual elements randomly by specifying the index, or the set the entire array by providing a list of index and value pairs for each element. The disadvantages of associative arrays as vectors lie in the fact they are implemented as hash tables.

- There's no implied ordering to the associative arrays. If you used vectors for plotting, you would want to insure the second component comes after the first, an so on. This isn't possible since arrays are actually hash tables. For example, you can't get a range of values between two indices. Nor can you sort an array.

- Arrays consume lots of memory when the number of elements becomes large (tens of thousands). This is because each element's index and value are stored as strings in the hash table.

- The C programming interface is unwieldy. Normally with vectors, you would like to view the Tcl array as you do a C array, as an array of floats or doubles. But with hash tables, you must convert both the index and value to and from decimal strings, just to access an element in the array. This makes it cumbersome to perform operations on the array as a whole.

The vector command tries to overcome these disadvantages while still retaining the ease of use of Tcl arrays. The vector command creates both a new Tcl command and associate array which are linked to the vector components. You can randomly access vector components though the elements of array. Not all indices are generated for the array, so printing the array (using the parray procedure) does not print out all the component values. You can use the Tcl command to access the array as a whole. You can copy, append, or sort vector using its command. If you need greater performance, or customized behavior, you can write your own C code to manage vectors.

<a name="SYNTAX"></a>
## SYNTAX

<a name="graph::vector-configure"></a>
**graph::vector configure** *?-flush bool -watchunset bool -oldcreate bool -maxsize int -novariable bool -nocommand bool?*

> The configure operation sets the default options used in creating vectors: these options are global to the interpreter. The -maxsize option, when non-zero, limits creation size. The -oldcreate enable the creation shortcut: vector vec1 vec2 .... See the create command for details on the others. By default, these are all disabled or zero.

<a name="graph::vector-create"></a>
**graph::vector create** *vectorName?(...)? ?option value?*

> The create operation creates a new vector vectorName. This creates both a Tcl command and array variable called vectorName. The name vectorName must be unique, so another Tcl command or array variable can not already exist in the current scope. You may access the components of the vector using the variable. If you change a value in the array, or unset an array element, the vector is updated to reflect the changes. When the variable vectorName is unset, the vector and its Tcl command are also destroyed.

> *vectorName*

> > This creates a new vector vectorName which initially has no components.

> *vectorName(size)*

> > This second form creates a new vector which will contain size number of components. The components will be indexed starting from zero (0). The default value for the components is 0.0.

> *vectorName(rows,columns)*

> > This form allows creation of a matrix with the specified columns and `rows*columns` elements. See the matrix section for more details.

> *vectorName(first:last)*

> > The last form creates a new vector of indexed first through last. First and last can be any integer value so long as first is less than last.

> The vector has optional switches that affect how the vector is created. They are as follows:

> **-variable** *varName*

> > Specifies the name of a Tcl variable to be mapped to the vector. If the variable already exists, it is first deleted, then recreated. If varName is the empty string, then no variable will be mapped. You can always map a variable back to the vector using the vector's variable operation.

> **-command** *cmdName*

> > Maps a Tcl command to the vector. The vector can be accessed using cmdName and one of the vector instance operations. A Tcl command by that name cannot already exist. If cmdName is the empty string, no command mapping will be made.

> **-watchunset** *boolean*

> > Indicates that the vector should automatically delete itself if the variable associated with the vector is unset. By default, the vector will not be deleted. This is different from previous releases. Set boolean to "true" to get the old behavior.

> **-flush** *boolean*

> > Indicates that the vector should automatically flush the cached variable elements which unsets all the elements of the Tcl array variable associated with the vector, freeing memory associated with the variable. This includes both the hash table and the hash keys. The down side is that this effectively flushes the caching of vector elements in the array. This means that the subsequent reads of the array will require a decimal to string conversion. By default, flushing is disabled.

> Vector names must start with a letter and consist of letters, digits, or underscores.

> > <code>
	# Error: must start with letter  
	graph::vector create 1abc  
</code>

> You can automatically generate vector names using the "#auto" vector name. The create operation will generate a unique vector name.

> > <code>
	set vec [graph::vector create #auto]  
	puts "$vec has [$vec length] components"  
</code>

> If successful, vector returns the name of the vector. It also creates a new Tcl command by the same name. You can use this command to invoke various operations that query or modify the vector. The general form is:

> **vectorName** *operation ?arg?...*

> Both, operation and its arguments determine the exact behavior of the command. The operations available for the graph are described in section [VECTOR OPERATIONS](#VECTOR-OPERATIONS).

<a name="graph::vector-destroy"></a>
**graph::vector destroy** *vectorName ?vectorName...?*

> Destroy given vectors.

<a name="graph::vector-expr"></a>
**graph::vector expr** *expression*

> All binary operators take vectors as operands (remember that numbers are treated as one-component vectors).The exact action of binary operators depends upon the length of the second operand. If the second operand has only one component, then each element of the first vector operand is computed by that value. For example, the expression "x * 2" multiples all elements of the vector x by 2. If the second operand has more than one component, both operands must be the same length. Each pair of corresponding elements are computed. So "x + y" adds the the first components of x and y together, the second, and so on.

> The valid operators are listed below, grouped in decreasing order of precedence:

> **- !**

> > Unary minus and logical NOT. The unary minus flips the sign of each component in the vector. The logical not operator returns a vector of whose values are 0.0 or 1.0. For each non-zero component 1.0 is returned, 0.0 otherwise.

> **^**

> > Exponentiation.

> **\* / %**

> > Multiply, divide, remainder.

> **+ -**

> > Add and subtract.

> **<< >>**

> > Left and right shift. Circularly shifts the values of the vector

> **< > <= >=**

> > Boolean less, greater, less than or equal, and greater than or equal. Each operator returns a vector of ones and zeros. If the condition is true, 1.0 is the component value, 0.0 otherwise.

> **== !=**

> > Boolean equal and not equal. Each operator returns a vector of ones and zeros. If the condition is true, 1.0 is the component value, 0.0 otherwise.

> **&&**

> > Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise.

> **||**

> > Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.

> **x?y:z**

> > If-then-else, as in C.

> See the C manual for more details on the results produced by each operator. All of the binary operators group left-to-right within the same precedence level.

> Several mathematical functions are supported for vectors. Each of the following functions invokes the math library function of the same name; see the manual entries for the library functions for details on what they do. The operation is applied to all elements of the vector returning the results. All functions take a vector operand. If no vector operand is used in the call, the current vector is assumed. eg.

> <code>
        vector create aVec
        aVec seq 0 100
        aVec expr {2*abs(aVec)-1}
        aVec length 100
        aVec expr {2*row()}
        vector expr {2*row()} ; # ERROR!
</code>

> Standard mathematical functions:

> > **acos	cos	hypot	sinh**  
> > **asin	cosh	log	sqrt**  
> > **atan	exp	log10	tan**    
> > **ceil	floor	sin	tanh**  

> Additional functions are:

> > **abs**

> > > Returns the absolute value of each component.

> > **random**

> > > Returns a vector of non-negative values uniformly distributed between [0.0, 1.0) using drand48. The seed comes from the internal clock of the machine or may be set manual with the srandom function.

> > **round**

> > > Rounds each component of the vector.

> > **srandom**

> > > Initializes the random number generator using srand48. The high order 32-bits are set using the integral portion of the first vector component. All other components are ignored. The low order 16-bits are set to an arbitrary value.

> The following functions return a single value.

> > **adev**

> > > Returns the average deviation (defined as the sum of the absolute values of the differences between component and the mean, divided by the length of the vector).

> > **kurtosis**

> > > Returns the degree of peakedness (fourth moment) of the vector.

> > **length**

> > > Returns the number of components in the vector.

> > **max**

> > > Returns the vector's maximum value.

> > **mean**

> > > Returns the mean value of the vector.

> > **median**

> > > Returns the median of the vector.

> > **min**

> > > Returns the vector's minimum value.

> > **q1**

> > > Returns the first quartile of the vector.

> > **q3**

> > > Returns the third quartile of the vector.

> > **prod**

> > > Returns the product of the components.

> > **sdev**

> > > Returns the standard deviation (defined as the square root of the variance) of the vector.

> > **skew**

> > > Returns the skewness (or third moment) of the vector. This characterizes the degree of asymmetry of the vector about the mean.

> > **sum**

> > > Returns the sum of the components.

> > **var**

> > > Returns the variance of the vector. The sum of the squared differences between each component and the mean is computed. The variance is the sum divided by the length of the vector minus 1.

> This last set of functions returns a vector of the same length as the argument.

> > **invert**

> > > Returns vector with elements in reversed order.

> > **norm**

> > > Scales the values of the vector to lie in the range [0.0..1.0].

> > **row**

> > > Psuedo function to get the current row.

> > **sort**

> > > Returns the vector components sorted in ascending order.

> > **shift(nVec,N)**

> > > This is the only function taking a second arg. It provides a version of nvec shifted by N places. When N is a scalar or vector with only one element, shift fills vacant area with 0. Otherwise the second element of nVec is used for the fill value. One use for this is providing running totals.

<a name="graph::vector-names"></a>
**graph::vector names** *?pattern?*

> Return names of all defined vectors.

<a name="graph::vector-op"></a>
**graph::vector op** *operation vectorName ?arg?...*

> Invoke instance operation. Supported operations are defined in the next section. Op is the only way to invoke instance operation sub-commands when -command is defined as empty in a vector. It also allows writing vector code that is checkable by a syntax checkers. eg.

> <code>
    graph::vector create v1  
    v1 op append {1 2 3}  
    v1 op modify 1 2.1  
</code>

<a name="VECTOR-INDICES"></a>
## VECTOR INDICES

Vectors are indexed by integers. You can access the individual vector components via its array variable or Tcl command. The string representing the index can be an integer, a numeric expression, a range, or a special keyword.

The index must lie within the current range of the vector, otherwise an an error message is returned. Normally the indices of a vector are start from 0. But you can use the offset operation to change a vector's indices on-the-fly.

> <code>
puts $vectorName(0)  
vectorName offset -5  
puts $vectorName(-5)  
</code>

When matrix numcols is > 1, 2D indexes are supported using ROW,COL form.

> <code>
vectorName matrix numcols 3  
puts vectorName(0,2)  
</code>

You can also use numeric expressions as indices. The result of the expression must be an integer value.

> <code>
set n 21  
set vectorName($n+3) 50.2  
</code>

The following special non-numeric indices are available: min, max, end, and ++end.

> <code>
puts "min = $vectorName($min)"  
set vectorName(end) -1.2  
</code>

The indices min and max will return the minimum and maximum values of the vector. Also available are: prod, sum, and mean. The index end returns the value of the last component in the vector. he index end,0 returns the value of the last row in column 0 of the vector. The index ++end is used to append new value onto the vector. It automatically extends the vector by numcols and sets its value.

> <code>
 # Append an new component to the end  
set vectorName(++end) 3.2  
</code>

A range of indices can be indicated by a colon (:).

> <code>
 # Set the first six components to 1.0  
set vectorName(0:5) 1.0  
</code>

If no index is supplied the first or last component is assumed.

> <code>
 # Print the values of all the components  
puts $vectorName(:)  
</code>

<a name="VECTOR-OPERATIONS"></a>
## VECTOR OPERATIONS

You can also use the vector's Tcl command to query or modify it. The general form is

> **vectorName** *operation arg...*

Note this is equivalent to the form:

> **graph::vector op** *operation vectorName ?arg?...*

Both operation and its arguments determine the exact behavior of the command. The operations available for vectors are listed below.

<a name="vectorName-plus"></a>
**vectorName +** *item*

<a name="vectorName-minus"></a>
**vectorName -** *item*

<a name="vectorName-mult"></a>
**vectorName** `*` *item*

<a name="vectorName-div"></a>
**vectorName /** *item*

> Perform binary op and return result as a list.

<a name="vectorName-append"></a>
**vectorName append** *item ?item?...*

> Appends the component values from item to vectorName. Item can be either the name of a vector or a list of numeric values.

<a name="vectorName-binread"></a>
**vectorName binread** *channel ?length? ?switches?*

> Reads binary values from a Tcl channel. Values are either appended to the end of the vector or placed at a given index (using the -at option), overwriting existing values. Data is read until EOF is found on the channel or a specified number of values length are read (note that this is not necessarily the same as the number of bytes). The following switches are supported:

> **-swap**

> > Swap bytes and words. The default endian is the host machine.

> **-at** *index*

> > New values will start at vector index index. This will overwrite any current values.

> **-format** *format*

> > Specifies the format of the data. Format can be one of the following: "i1", "i2", "i4", "i8", "u1, "u2", "u4", "u8", "r4", "r8", or "r16". The number indicates the number of bytes required for each value. The letter indicates the type: "i" for signed, "u" for unsigned, "r" or real. The default format is "r16".

<a name="vectorName-binwrite"></a>
**vectorName binwrite** *channel ?length? ?-at index?*

> Like binread, but writes data.

<a name="vectorName-clear"></a>
**vectorName clear**

> Clears the element indices from the array variable associated with vectorName. This doesn't affect the components of the vector. By default, the number of entries in the Tcl array doesn't match the number of components in the vector. This is because its too expensive to maintain decimal strings for both the index and value for each component. Instead, the index and value are saved only when you read or write an element with a new index. This command removes the index and value strings from the array. This is useful when the vector is large.

<a name="vectorName-delete"></a>
**vectorName delete** *index ?index?...*

> Deletes the indexth component from the vector vectorName. Index is the index of the element to be deleted. This is the same as unsetting the array variable element index. The vector is compacted after all the indices have been deleted.

<a name="vectorName-dup"></a>
**vectorName dup** *destName*

> Copies vectorName to destName. DestName is the name of a destination vector. If a vector destName already exists, it is overwritten with the components of vectorName. Otherwise a new vector is created.

<a name="vectorName-expr"></a>
**vectorName expr** *expression*

> Computes the expression and resets the values of the vector accordingly. Both scalar and vector math operations are allowed. All values in expressions are either real numbers or names of vectors. All numbers are treated as one component vectors.

<a name="vectorName-index"></a>
**vectorName index** *index ?value?...*

> Get/set individual vector values. This provides element updating when -variable is set to empty.

<a name="vectorName-insert"></a>
**vectorName insert** *index item ?item?...*

> Inserts the component values from item to vectorName at index Item can be either the name of a vector or a list of numeric values.

<a name="vectorName-length"></a>
**vectorName length** *?newSize?*

> Queries or resets the number of components in vectorName. NewSize is a number specifying the new size of the vector. If newSize is smaller than the current size of vectorName, vectorName is truncated. If newSize is greater, the vector is extended and the new components are initialized to 0.0. If no newSize argument is present, the current length of the vector is returned.

<a name="vectorName-matrix"></a>
**vectorName matrix** *...*

> Matrix provides a 2D array view into 1D data. It provides indexing operations in ROW,COL form making it suitable for use with TkTable. Data storage remains unchanged: vectors are still just a single long array. For example, here are two ways to create a 3 column by 10 row matrix:

> <code>
    graph::vector create aVec(10,3)  
    graph::vector create bVec(30)  
    bVec matrix numcols 3  
    set aVec(0,0) 99  
    set bVec(29,2) -99  
    aVec append {5 6 7}; # aVec now has 11 rows.  
    aVec append 1 2;     # Now aVec has 13 rows!  
</code>

> Note that data is appended only in increments of numcols. Elements 0-2 make up the first row, 3-5 the second, etc. Elements will appear only in increments of the column size.

<a name="vectorName-matrix-copy"></a>
**vectorName matrix copy** *dstcolumn srccolumn ?srcVec?*

> Copy a column of element values to column dstcolumn from srccolumn. If vector srcVec is given, and not the same as vectorName, the columns numbers must be different. If the srcVec column is longer, vectorName will be extended. If shorter, remaining destination values are not overwritten.

<a name="vectorName-matrix-delete"></a>
**vectorName matrix delete** *column*

> Delete elements in a column. Note that numcols, which must be greater than 1, will be decremented.

<a name="vectorName-matrix-get"></a>
**vectorName matrix get** *column*

> Get the element in a column: this number must be less than numcols. Note that numcols must be non-zero.

<a name="vectorName-matrix-insert"></a>
**vectorName matrix insert** *column ?initvalue?*

> Insert a new column of elements at column (default 0). The new column is initialized with initvalue, or 0.0 if not specified. Note that numcols will be incremented.

<a name="vectorName-matrix-multiply"></a>
**vectorName matrix multiply** *srcVec ?dstVec?*

> Perform matrix multiplication using srcVec, placing results either in dstVec, or returned as a list. The numrows of srcVec must equal numcols in vectorName. One application for multiply is coordinate transformation.

<a name="vectorName-matrix-numcols"></a>
**vectorName matrix numcols** *?size?*

> Get or set the number of columns for a vectors data. Values >1 enable array variables to accept 2d matrix indexes. For example with a numcols of 10, $vec1(1,2) refers to the 13th element in the vector. A vectors size is also constrained to multiples of numcols, as is it's offset. By default, numcols is 1.

<a name="vectorName-matrix-numrows"></a>
**vectorName matrix numrows** *?size?*

> Get or set the length of rows in a columns for a vector. By default, this is just the vector length/numcols. Setting this value simply provides a convenient way to increase or decrease the vector size by multiples of numcols.

<a name="vectorName-matrix-set"></a>
**vectorName matrix set** *column ?valuelist?*

> Set value elements in a column: this number must be less than numcols. The valuelist is a list values. If this list is shorter than the column, it's last value is used for all remaining columns. The column gets set to the values of item, or 0.0 by default.

<a name="vectorName-matrix-shift"></a>
**vectorName matrix shift** *column amount ?startoffset?*

> Shifts the values of a column by integer inamount. A negative value shifts upward. The startoffset indicates where to start shifting from.

<a name="vectorName-matrix-sort"></a>
**vectorName matrix sort** *column ?-reverse?*

> Sort the vector by the given column.

<a name="vectorName-matrix-transpose"></a>
**vectorName matrix transpose**

> Transpose all columns with rows in matrix. Note that this is a no-op if numcols is 1. Otherwise, numcols will change to vectorLength/numcols.

<a name="vectorName-merge"></a>
**vectorName merge** *srcName ?srcName?...*

> Merges the named vectors into a single vector. The resulting vector is formed by merging the components of each source vector one index at a time.

<a name="vectorName-notify"></a>
**vectorName notify** *?keyword? ?script?*

> Queries or controls how vector clients are notified of changes to the vector. Also allows setting a notifier callback. The exact behavior is determined by keyword.

> **always**

> > Indicates that clients are to be notified immediately whenever the vector is updated.

> **never**

> > Indicates that no clients are to be notified.

> **whenidle**

> > Indicates that clients are to be notified at the next idle point whenever the vector is updated.

> **now**

> > If any client notifications is currently pending, they are notified immediately.

> **cancel**

> > Cancels pending notifications of clients using the vector.

> **pending**

> > Returns 1 if a client notification is pending, and 0 otherwise.

> **callback** *?script?*

> > Query or set a Tcl callback script that is evaluated when a vector is updated.

<a name="vectorName-populate"></a>
**vectorName populate** *destName ?density?*

> Creates a vector destName which is a superset of vectorName. DestName will include all the components of vectorName, in addition the interval between each of the original components will contain a density number of new components, whose values are evenly distributed between the original components values. This is useful for generating abscissas to be interpolated along a spline.

<a name="vectorName-range"></a>
**vectorName range** *firstIndex ?lastIndex?...*

> Returns a list of numeric values representing the vector components between two indices. Both firstIndex and lastIndex are indices representing the range of components to be returned. If lastIndex is less than firstIndex, the components are listed in reverse order.

<a name="vectorName-search"></a>
**vectorName search** *value ?value?*

> Searches for a value or range of values among the components of vectorName. If one value argument is given, a list of indices of the components which equal value is returned. If a second value is also provided, then the indices of all components which lie within the range of the two values are returned. If no components are found, then "" is returned.

<a name="vectorName-set"></a>
**vectorName set** *item*

> Resets the components of the vector to item. Item can be either a list of numeric expressions or another vector.

<a name="vectorName-seq"></a>
**vectorName seq** *start ?finish? ?step?*

> Generates a sequence of values starting with the value start. Finish indicates the terminating value of the sequence. The vector is automatically resized to contain just the sequence. If three arguments are present, step designates the interval.

> With only two arguments (no finish argument), the sequence will continue until the vector is filled. With one argument, the interval defaults to 1.0.

<a name="vectorName-sort"></a>
**vectorName sort** *?-reverse? ?argName?...*

> Sorts the vector vectorName in increasing order. If the -reverse flag is present, the vector is sorted in decreasing order. If other arguments argName are present, they are the names of vectors which will be rearranged in the same manner as vectorName. Each vector must be the same length as vectorName. You could use this to sort the x vector of a graph, while still retaining the same x,y coordinate pairs in a y vector.

<a name="vectorName-split"></a>
**vectorName split** *dstName ?dstName?...*

> Split the vector into a multiple vectors. The resulting N vectors each contain the mod-Nth element from source.

<a name="vectorName-variable"></a>
**vectorName variable** *varName*

> Maps a Tcl variable to the vector, creating another means for accessing the vector. The variable varName can't already exist. This overrides any current variable mapping the vector may have.

<a name="C-LANGUAGE-API"></a>
## C LANGUAGE API

You can create, modify, and destroy vectors from C code, using library routines. You need to include the header file blt.h. It contains the definition of the structure `Rbc_Vector`, which represents the vector. It appears below.

> <code>
typedef struct {  
double valueArr;  
int numValues;  
int arraySize;    
double min, max;  
} **Rbc_Vector**;  
</code>

The field valueArr points to memory holding the vector components. The components are stored in a double precision array, whose size size is represented by arraySize. NumValues is the length of vector. The size of the array is always equal to or larger than the length of the vector. Min and max are minimum and maximum component values.

<a name="LIBRARY-ROUTINES"></a>
## LIBRARY ROUTINES

The following routines are available from C to manage vectors. Vectors are identified by the vector name.

**Rbc_CreateVector**

> Synopsis:

> > `int Rbc_CreateVector(Tcl_Interp *interp; char *vectorName; int length; Rbc_Vector **vecPtrPtr);`

> Description:

> > Creates a new vector vectorName with a length of length. Rbc_CreateVector creates both a new Tcl command and array variable vectorName. Neither a command nor variable named vectorName can already exist. A pointer to the vector is placed into vecPtrPtr.

> Results:

> > Returns TCL_OK if the vector is successfully created. If length is negative, a Tcl variable or command vectorName already exists, or memory cannot be allocated for the vector, then TCL_ERROR is returned and interp->result will contain an error message.

**Rbc_VectorFree**

> Synopsis:

> > `int Rbc_VectorFree(Rbc_Vector *vecPtr);`

> Description:

> > Removes the vector pointed to by vecPtr. VecPtr is a pointer to a vector, typically set by Rbc_GetVector or Rbc_CreateVector. Both the Tcl command and array variable of the vector are destroyed. All clients of the vector will be notified immediately that the vector has been destroyed.

> Results:

> > Returns TCL_OK if the vector is successfully deleted. If vectorName is not the name a vector, then TCL_ERROR is returned.

**Rbc_GetVector**

> Synopsis:

> > `int Rbc_GetVector(Tcl_Interp *interp; char *vectorName; Rbc_Vector **vecPtrPtr);`

> Description:

> > Retrieves the vector vectorName. VecName is the name of a vector which must already exist. VecPtrPtr will point be set to the address of the vector.

> Results:

> > Returns TCL_OK if the vector is successfully retrieved. If vectorName is not the name of a vector, then TCL_ERROR is returned and interp->result will contain an error message.

**Rbc_ResetVector**

> Synopsis:

> > `int Rbc_ResetVector(Rbc_Vector *vecPtr; double *dataArr; int *numValues; int *arraySize; Tcl_FreeProc *freeProc);` 

> Description:

> > Resets the components of the vector pointed to by vecPtr. Calling Rbc_ResetVector will trigger the vector to dispatch notifications to its clients. DataArr is the array of doubles which represents the vector data. NumValues is the number of elements in the array. ArraySize is the actual size of the array (the array may be bigger than the number of values stored in it). FreeProc indicates how the storage for the vector component array (dataArr) was allocated. It is used to determine how to reallocate memory when the vector is resized or destroyed. It must be TCL_DYNAMIC, TCL_STATIC, TCL_VOLATILE, or a pointer to a function to free the memory allocated for the vector array. If freeProc is TCL_VOLATILE, it indicates that dataArr must be copied and saved. If freeProc is TCL_DYNAMIC, it indicates that dataArr was dynamically allocated and that Tcl should free dataArr if necessary. Static indicates that nothing should be done to release storage for dataArr.

> Results:

> > Returns TCL_OK if the vector is successfully resized. If newSize is negative, a vector vectorName does not exist, or memory cannot be allocated for the vector, then TCL_ERROR is returned and interp->result will contain an error message.

**Rbc_ResizeVector**

> Synopsis:

> > `int Rbc_ResizeVector(Rbc_Vector *vecPtr; int newSize);`

> Description:

> > Resets the length of the vector pointed to by vecPtr to newSize. If newSize is smaller than the current size of the vector, it is truncated. If newSize is greater, the vector is extended and the new components are initialized to 0.0. Calling Rbc_ResetVector will trigger the vector to dispatch notifications.

> Results:

> > Returns TCL_OK if the vector is successfully resized. If newSize is negative or memory can not be allocated for the vector, then TCL_ERROR is returned and interp->result will contain an error message.

**Rbc_VectorExists**

> Synopsis:

> > `int Rbc_VectorExists(Tcl_Interp *interp; char *vectorName);` 

> Description:

> > Indicates if a vector named vectorName exists in interp.

> Results:

> > Returns 1 if a vector vectorName exists and 0 otherwise.

If your application needs to be notified when a vector changes, it can allocate a unique client identifier for itself. Using this identifier, you can then register a call-back to be made whenever the vector is updated or destroyed. By default, the call-backs are made at the next idle point. This can be changed to occur at the time the vector is modified. An application can allocate more than one identifier for any vector. When the client application is done with the vector, it should free the identifier.

The call-back routine must of the following type.

> `typedef void (Rbc_VectorChangedProc) (Tcl_Interp *interp, ClientData clientData, Rbc_VectorNotify notify);`

ClientData is passed to this routine whenever it is called. You can use this to pass information to the call-back. The notify argument indicates whether the vector has been updated of destroyed. It is an enumerated type.

> `typedef enum { RBC_VECTOR_NOTIFY_UPDATE=1, RBC_VECTOR_NOTIFY_DESTROY=2 } Rbc_VectorNotify;`

**Rbc_AllocVectorId**

> Synopsis:

> > `Rbc_VectorId Rbc_AllocVectorId(Tcl_Interp *interp; char *vectorName);` 

> Description:

> > Allocates an client identifier for with the vector vectorName. This identifier can be used to specify a call-back which is triggered when the vector is updated or destroyed.

> Results:

> > Returns a client identifier if successful. If vectorName is not the name of a vector, then NULL is returned and interp->result will contain an error message.

**Rbc_GetVectorById**

> Synopsis:

> > `int Rbc_GetVectorById(Tcl_Interp *interp; Rbc_VectorId clientId; Rbc_Vector **vecPtrPtr);` 

> Description:

> > Retrieves the vector used by clientId. ClientId is a valid vector client identifier allocated by Rbc_AllocVectorId. VecPtrPtr will point be set to the address of the vector.

> Results:

> > Returns TCL_OK if the vector is successfully retrieved.

**Rbc_SetVectorChangedProc**

> Synopsis:

> > `void Rbc_SetVectorChangedProc(Rbc_VectorId clientId; Rbc_VectorChangedProc *proc; ClientData *clientData);` 

> Description:

> > Specifies a call-back routine to be called whenever the vector associated with clientId is updated or deleted. Proc is a pointer to call-back routine and must be of the type Rbc_VectorChangedProc. ClientData is a one-word value to be passed to the routine when it is invoked. If proc is NULL, then the client is not notified.

> Results:

> > The designated call-back procedure will be invoked when the vector is updated or destroyed.

**Rbc_FreeVectorId**

> Synopsis:

> > `void Rbc_FreeVectorId(Rbc_VectorId clientId);` 

> Description:

> > Frees the client identifier. Memory allocated for the identifier is released. The client will no longer be notified when the vector is modified.

> Results:

> > The designated call-back procedure will be no longer be invoked when the vector is updated or destroyed.

**Rbc_NameOfVectorId**

> Synopsis:

> > `char *Rbc_NameOfVectorId(Rbc_VectorId clientId);` 

> Description:

> > Retrieves the name of the vector associated with the client identifier clientId.

> Results:

> > Returns the name of the vector associated with clientId. If clientId is not an identifier or the vector has been destroyed, NULL is returned.

<a name="C-API-EXAMPLE"></a>
## C API EXAMPLE

The following example opens a file of binary data and stores it in an array of doubles. The array size is computed from the size of the file. If the vector "data" exists, calling Rbc_VectorExists, Rbc_GetVector is called to get the pointer to the vector. Otherwise the routine Rbc_CreateVector is called to create a new vector and returns a pointer to it. Just like the Tcl interface, both a new Tcl command and array variable are created when a new vector is created. It doesn't make any difference what the initial size of the vector is since it will be reset shortly. The vector is updated when lt_ResetVector is called. Rbc_ResetVector makes the changes visible to the Tcl interface and other vector clients (such as a graph widget).

> <code>
  #include "tcl.h"  
  #include "blt.h"  
  Rbc_Vector *vecPtr;  
  double *newArr;  
  FILE *f;  
  struct stat statBuf;  
  int numBytes, numValues;  
  f = fopen("binary.dat", "r");  
  fstat(fileno(f), &statBuf);  
  numBytes = (int)statBuf.st_size; /* Allocate an array big enough to hold all the data */  
  newArr = (double *)malloc(numBytes);  
  numValues = numBytes / sizeof(double);  
  fread((void *)newArr, numValues, sizeof(double), f);  
  fclose(f);  
  if (Rbc_VectorExists(interp, "data")) {  
    if (Rbc_GetVector(interp, "data", &vecPtr) != TCL_OK) {  
      return TCL_ERROR;  
    }  
  } else {  
    if (Rbc_CreateVector(interp, "data", 0, &vecPtr) != TCL_OK) {  
      return TCL_ERROR;  
    }  
  }  
  /* * Reset the vector. Clients will be notified when Tk is idle.  
   * TCL_DYNAMIC tells the vector to free the memory allocated  
   * if it needs to reallocate or destroy the vector.  
   */  
  if (Rbc_ResetVector(vecPtr, newArr, numValues, numValues, TCL_DYNAMIC) != TCL_OK) {  
    return TCL_ERROR;  
  }  
</code>

<a name="INCOMPATIBILITIES"></a>
## INCOMPATIBILITIES

In previous versions, if the array variable isn't global (i.e. local to a Tcl procedure), the vector is automatically destroyed when the procedure returns.

> <code>
proc doit {} {  
    # Temporary vector x  
    vector x(10)  
    set x(9) 2.0  
      ...  
}  
</code>

This has changed. Variables are not automatically destroyed when their variable is unset. You can restore the old behavior by setting the "-watchunset" switch.

<a name="EXAMPLE"></a>
## EXAMPLE

You create vectors using the vector command and its create operation.

> <code>
 # Create a new vector.  
graph::vector create y(50)  
</code>

This creates a new vector named y. It has fifty components, by default, initialized to 0.0. In addition, both a Tcl command and array variable, both named y, are created. You can use either the command or variable to query or modify components of the vector.

> <code>
 # Set the first value.  
set y(0) 9.25  
puts "y has [y length] components"  
</code>

The array y can be used to read or set individual components of the vector. Vector components are indexed from zero. The array index must be a number less than the number of components. For example, it's an error if you try to set the 51st element of y.

> <code>
 # This is an error. The vector only has 50 components.  
set y(50) 0.02  
</code>

You can also specify a range of indices using a colon (:) to separate the first and last indices of the range.

> <code>
 # Set the first six components of y  
set y(0:5) 25.2  
</code>

If you don't include an index, then it will default to the first and/or last component of the vector.

> <code>
 # Print out all the components of y  
puts "y = $y(:)"  
</code>

There are special non-numeric indices. The index end, specifies the last component of the vector. It's an error to use this index if the vector is empty (length is zero). The index ++end can be used to extend the vector by one component and initialize it to a specific value. You can't read from the array using this index, though.

> <code>
 # Extend the vector by one component.  
set y(++end) 0.02  
</code>

The other special indices are min and max. They return the current smallest and largest components of the vector.

> <code>
 # Print the bounds of the vector  
puts "min=$y(min) max=$y(max)"  
</code>

To delete components from a vector, simply unset the corresponding array element. In the following example, the first component of y is deleted. All the remaining components of y will be moved down by one index as the length of the vector is reduced by one.

> <code>
 # Delete the first component  
unset y(0)  
puts "new first element is $y(0)"  
</code>

The vector's Tcl command can also be used to query or set the vector.

> <code>
 # Create and set the components of a new vector  
graph::vector create x  
x set { 0.02 0.04 0.06 0.08 0.10 0.12 0.14 0.16 0.18 0.20 }  
</code>

Here we've created a vector x without a initial length specification. In this case, the length is zero. The set operation resets the vector, extending it and setting values for each new component.

There are several operations for vectors. The range operation lists the components of a vector between two indices.

> <code>
 # List the components  
puts "x = [x range 0 end]"  
</code>

You can search for a particular value using the search operation. It returns a list of indices of the components with the same value. If no component has the same value, it returns "".

> <code>
 # Find the index of the biggest component  
set indices [x search $x(max)]  
</code>

Other operations copy, append, or sort vectors. You can append vectors or new values onto an existing vector with the append operation.

> <code>
 # Append assorted vectors and values to x  
x append x2 x3 { 2.3 4.5 } x4  
</code>

The sort operation sorts the vector. If any additional vectors are specified, they are rearranged in the same order as the vector. For example, you could use it to sort data points represented by x and y vectors.

> <code>
 # Sort the data points  
x sort y  
</code>

The vector x is sorted while the components of y are rearranged so that the original x,y coordinate pairs are retained.

The expr operation lets you perform arithmetic on vectors. The result is stored in the vector.

> <code>
 # Add the two vectors and a scalar  
x expr { x + y }  
x expr { x * 2 }  
</code>

When a vector is modified, resized, or deleted, it may trigger call-backs to notify the clients of the vector. For example, when a vector used in the graph widget is updated, the vector automatically notifies the widget that it has changed. The graph can then redrawn itself at the next idle point. By default, the notification occurs when Tk is next idle. This way you can modify the vector many times without incurring the penalty of the graph redrawing itself for each change. You can change this behavior using the notify operation.

> <code>
 # Make vector x notify after every change  
x notify always  
	...  
 # Never notify  
x notify never  
	...  
 # Force notification now  
x notify now  
 # Set Tcl callback for update of Tktable widget .t.  
x notify callback {.t conf -padx [.t cget -padx]; .t reread}  
</code>

To delete a vector, use the vector delete command. Both the vector and its corresponding Tcl command are destroyed.

> <code>
 # Remove vector x  
graph::vector destroy x  
</code>

The pseudo vector last can be used at the end of an expression to implement running totals. During execution it resolves to the result from the previous vector element evaluation.

> <code>
graph::vector create A(10)  
graph::vector create B(10)  
graph::vector create S(10)  
graph::vector create T(10)  
graph::S expr A+B  
graph::T expr S+last; # Running total  
</code>

<a name="CREDITS"></a>
## CREDITS

[BLT][] was originally develeoped by George A. Howlett. It can be found at <https://sourceforge.net/projects/blt/>.

Refactored [BLT][] Components ([Rbc][]), includes data vectors and graph widgets from the original [BLT][]. Both can be found at sourceforge.

User visible changes to the original [Rbc][] code are:

- command name is now **graph::vector**

<a name="KEYWORDS"></a>
## KEYWORDS

vector, graph, widget

<a name="COPYRIGHT"></a>
## COPYRIGHT

&copy; 1995-1997 Roger E. Critchlow Jr.

&copy; 2001 George A. Howlett.

&copy; 2018 René Zaumseil <[email protected]>

[BLT]: <https://sourceforge.net/projects/blt/>
[Rbc]: <https://sourceforge.net/projects/rbctoolkit/>

			    int objc, Tcl_Obj *const *objv);
static int		CaretCmd(ClientData dummy, Tcl_Interp *interp,
			    int objc, Tcl_Obj *const *objv);
static int		InactiveCmd(ClientData dummy, Tcl_Interp *interp,
			    int objc, Tcl_Obj *const *objv);
static int		ScalingCmd(ClientData dummy, Tcl_Interp *interp,
			    int objc, Tcl_Obj *const *objv);
#ifndef MAC_OSX_TK
static int		SnapCmd(ClientData dummy, Tcl_Interp *interp,
			    int objc, Tcl_Obj *const *objv);
#endif
static int		UseinputmethodsCmd(ClientData dummy,
			    Tcl_Interp *interp, int objc,
			    Tcl_Obj *const *objv);
static int		WindowingsystemCmd(ClientData dummy,
			    Tcl_Interp *interp, int objc,
			    Tcl_Obj *const *objv);

    {"busy",		Tk_BusyObjCmd, NULL },
    {"caret",		CaretCmd, NULL },
    {"inactive",	InactiveCmd, NULL },
    {"scaling",		ScalingCmd, NULL },
    {"useinputmethods",	UseinputmethodsCmd, NULL },
    {"windowingsystem",	WindowingsystemCmd, NULL },
    {"fontchooser",	NULL, tkFontchooserEnsemble},
#ifndef MAC_OSX_TK
    {"snap",		SnapCmd, NULL},
#endif
    {NULL, NULL, NULL}
};

/*
 *----------------------------------------------------------------------
 *
 * Tk_BellObjCmd --

	Tcl_ResetResult(interp);
    } else {
	Tcl_WrongNumArgs(interp, 1, objv, "?-displayof window? ?reset?");
	return TCL_ERROR;
    }
    return TCL_OK;
}

#ifndef MAC_OSX_TK
int
SnapCmd(
    ClientData clientData,	/* Main window associated with interpreter. */
    Tcl_Interp *interp,		/* Current interpreter. */
    int objc,			/* Number of arguments. */
    Tcl_Obj *const objv[])	/* Argument objects. */
{
    Tk_Window tkwin = clientData;
    int skip = TkGetDisplayOf(interp, objc - 1, objv + 1, &tkwin);

    if (skip < 0) {
	return TCL_ERROR;
    }
    if (objc != 3) {
	Tcl_WrongNumArgs(interp, 1, objv, "window photo");
	return TCL_ERROR;
    }

    return Rbc_SnapWindow(interp, tkwin, Tcl_GetString(objv[1]),
        Tcl_GetString(objv[2]), 0, 0);
}
#endif

/*
 *----------------------------------------------------------------------
 *
 * Tk_TkwaitObjCmd --
 *
 *	This function is invoked to process the "tkwait" Tcl command. See the

/*
 * Themed widget set init function:
 */

MODULE_SCOPE int	Ttk_Init(Tcl_Interp *interp);

/*
 * Used tko widget set functions:
 */
#ifndef MAC_OSX_TK
MODULE_SCOPE int	Tko_Init(Tcl_Interp *interp);
MODULE_SCOPE int	Rbc_SnapWindow(Tcl_Interp *interp,Tk_Window tkmain,
			    const char*pathname, const char *photoimage,
			    int destWidth, int destHeight);
#endif

/*
 * Internal functions shared among Tk modules but not exported to the outside
 * world:
 */

MODULE_SCOPE int	Tk_BellObjCmd(ClientData clientData,
			    Tcl_Interp *interp, int objc,

     */

    code = Ttk_Init(interp);
    if (code != TCL_OK) {
	goto done;
    }

    /*
     * Initialize the tko widget set
     */
#ifndef MAC_OSX_TK
    code = Tko_Init(interp);
    if (code != TCL_OK) {
	goto done;
    }
#endif
    /*
     * Invoke platform-specific initialization. Unlock mutex before entering
     * TkpInit, as that may run through the Tk_Init routine again for the
     * console window interpreter.
     */

    code = TkpInit(interp);

/*
 * tkoFrame.c --
 *
 *	This module implements "frame", "labelframe" and "toplevel" widgets
 *	for the Tk toolkit. Frames are windows with a background color and
 *	possibly a 3-D effect, but not much else in the way of attributes.
 *
 * Copyright (c) 1990-1994 The Regents of the University of California.
 * Copyright (c) 1994-1997 Sun Microsystems, Inc.
 * Copyright (c) 2019 Rene Zaumseil
 *
 * See the file "license.terms" for information on usage and redistribution of
 * this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

#include "tkoWidget.h"

 /*
  * The following enum is used to define the type of the frame.
  */
enum FrameType {
    TYPE_FRAME, TYPE_TOPLEVEL, TYPE_LABELFRAME
};

/*
 * tkoFrame --
 *
 * A data structure of the following type is kept for each
 * frame that currently exists for this process:
 */
typedef struct tkoFrame {
    Tk_Window *win;
    Tcl_Object object;
    Tcl_Interp *interp;
    Display *display;
    enum FrameType type;       /* Type of widget, such as TYPE_FRAME. */
    char *menuName;            /* Textual description of menu to use for
                                * menubar. Malloc-ed, may be NULL. */
    Colormap colormap;         /* If not None, identifies a colormap
                                * allocated for this window, which must be
                                * freed when the window is deleted. */
    Tk_3DBorder border;        /* Structure used to draw 3-D border and
                                * background. NULL means no background or
                                * border. */
    int borderWidth;           /* Width of 3-D border (if any). */
    int relief;                /* 3-d effect: TK_RELIEF_RAISED etc. */
    int highlightWidth;        /* Width in pixels of highlight to draw around
                                * widget when it has the focus. 0 means don't
                                * draw a highlight. */
    XColor *highlightBgColorPtr;
    /* Color for drawing traversal highlight area
     * when highlight is off. */
    XColor *highlightColorPtr; /* Color for drawing traversal highlight. */
    int width;                 /* Width to request for window. <= 0 means
                                * don't request any size. */
    int height;                /* Height to request for window. <= 0 means
                                * don't request any size. */
    Tk_Cursor cursor;          /* Current cursor for window, or None. */
    int isContainer;           /* 1 means this window is a container, 0 means
                                * that it isn't. */
    Tcl_Obj *useThis;          /* If the window is embedded, this points to
                                * the name of the window in which it is
                                * embedded (malloc'ed). For non-embedded
                                * windows this is NULL. */
    int flags;                 /* Various flags; see below for
                                * definitions. */
    int padX;                  /* Integer value corresponding to padXPtr. */
    int padY;                  /* Integer value corresponding to padYPtr. */
    unsigned int mask;
} tkoFrame;

/*
 * tkoLabelframe --
 *
 * A data structure of the following type is kept for each labelframe widget
 * managed by this file:
 */
typedef struct tkoLabelframe {
    tkoFrame frame;            /* A pointer to the generic frame structure.
                                * This must be the first element of the
                                * tkoLabelframe. */
    /*
     * tkoLabelframe specific configuration settings.
     */
    Tcl_Obj *textPtr;          /* Value of -text option: specifies text to
                                * display in button. */
    Tk_Font tkfont;            /* Value of -font option: specifies font to
                                * use for display text. */
    XColor *textColorPtr;      /* Value of -fg option: specifies foreground
                                * color in normal mode. */
    int labelAnchor;           /* Value of -labelanchor option: specifies
                                * where to place the label. */
    Tk_Window labelWin;        /* Value of -labelwidget option: Window to use
                                * as label for the frame. */
    /*
     * tkoLabelframe specific fields for use with configuration settings above.
     */
    GC  textGC;                /* GC for drawing text in normal mode. */
    Tk_TextLayout textLayout;  /* Stored text layout information. */
    XRectangle labelBox;       /* The label's actual size and position. */
    int labelReqWidth;         /* The label's requested width. */
    int labelReqHeight;        /* The label's requested height. */
    int labelTextX, labelTextY; /* Position of the text to be drawn. */
} tkoLabelframe;

/*
 * The following macros define how many extra pixels to leave around a label's
 * text.
 */
#define LABELSPACING 1
#define LABELMARGIN 4

 /*
  * Flag bits for frames:
  *
  * REDRAW_PENDING:             Non-zero means a DoWhenIdle handler has
  *                             already been queued to redraw this window.
  * GOT_FOCUS:                  Non-zero means this widget currently has the
  *                             input focus.
  */
#define REDRAW_PENDING		1
#define GOT_FOCUS		4

  /*
   * The following enum is used to define a type for the -labelanchor option of
   * the Labelframe widget. These values are used as indices into the string
   * table below.
   */
enum labelanchor {
    LABELANCHOR_E, LABELANCHOR_EN, LABELANCHOR_ES,
    LABELANCHOR_N, LABELANCHOR_NE, LABELANCHOR_NW,
    LABELANCHOR_S, LABELANCHOR_SE, LABELANCHOR_SW,
    LABELANCHOR_W, LABELANCHOR_WN, LABELANCHOR_WS
};

/*
* Methods
*/
static int FrameConstructorFrame(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int FrameConstructorLabelframe(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int FrameConstructorToplevel(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int FrameDestructor(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int FrameMethod_tko_configure(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int FrameMethod_tko_option(
	ClientData clientData,
	Tcl_Interp * interp,
	Tcl_ObjectContext context,
	int objc,
	Tcl_Obj * const objv[]);
static int FrameMethod_labelanchor(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int FrameMethod_labelwidget(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);

/*
 * Functions
 */
static int FrameConstructor(
    int type,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static void FrameMetaDestroy(
    tkoFrame * frame);
static void
FrameMetaDelete(
    ClientData clientData)
{
    Tcl_EventuallyFree(clientData, (Tcl_FreeProc *) FrameMetaDestroy);
}

static void FrameComputeGeometry(
    tkoFrame * frame);
static void FrameDisplay(
    ClientData clientData);
static void FrameEventProc(
    ClientData clientData,
    XEvent * eventPtr);
static void FrameLostSlaveProc(
    ClientData clientData,
    Tk_Window tkWin);
static void FrameRequestProc(
    ClientData clientData,
    Tk_Window tkWin);
static void FrameStructureProc(
    ClientData clientData,
    XEvent * eventPtr);
static void FrameWorldChanged(
    ClientData instanceData);
static void FrameLabelwinRemove(
    tkoLabelframe * labelframe);
static void FrameMap(
    ClientData clientData);

/*
 * Data
 */

/*
 * frameMeta --
 *
 * The structure is used to identify our own data inoo objects.
 */
static Tcl_ObjectMetadataType frameMeta = {
    TCL_OO_METADATA_VERSION_CURRENT,
    "FrameMeta",
    FrameMetaDelete,
    NULL
};

/*
 * frameClass --
 *
 * The structure below defines frame class behavior by means of functions that
 * can be invoked from generic window code.
 */
static const Tk_ClassProcs frameClass = {
    sizeof(Tk_ClassProcs),      /* size */
    FrameWorldChanged,  /* worldChangedProc */
    NULL,      /* createProc */
    NULL       /* modalProc */
};

/*
 * frameGeomType --
 *
 * The structure below defines the official type record for the labelframe's
 * geometry manager:
 */
static const Tk_GeomMgr frameGeomType = {
    "labelframe",       /* name */
    FrameRequestProc,   /* requestProc */
    FrameLostSlaveProc  /* lostSlaveProc */
};

/*
 * Definition of options created in object constructor.
 * Order of used options in definition is important:
 * -class -visual -colormap -container -use
 */

/* Common options for all defined widgets. */
#define FRAME_COMMONDEFINE \
	{ "-background" , "background", "Background", DEF_FRAME_BG_COLOR, 0, NULL, \
        NULL, NULL,	TKO_SET_3DBORDER, &frameMeta, offsetof(tkoFrame, border)}, \
	{ "-bg" , "-background", NULL, NULL, 0, NULL, NULL, NULL,0,NULL,0}, \
	{ "-bd" , "-borderwidth", NULL, NULL, 0, NULL, NULL, NULL,0,NULL,0}, \
	{ "-cursor" , "cursor", "Cursor", DEF_FRAME_CURSOR, 0, NULL, \
		NULL, NULL, TKO_SET_CURSOR, &frameMeta, offsetof(tkoFrame, cursor)}, \
	{ "-height" , "height", "Height", DEF_FRAME_HEIGHT, 0, NULL, \
		NULL, NULL, TKO_SET_PIXEL, &frameMeta, offsetof(tkoFrame, height)}, \
	{ "-highlightbackground", "highlightbackground", "highlightBackground", DEF_FRAME_HIGHLIGHT_BG, 0, NULL, \
		NULL, NULL, TKO_SET_XCOLOR, &frameMeta, offsetof(tkoFrame, highlightBgColorPtr)}, \
	{ "-highlightcolor", "highlightColor", "HighlightColor", DEF_FRAME_HIGHLIGHT, 0,NULL, \
		NULL, NULL, TKO_SET_XCOLOR, &frameMeta, offsetof(tkoFrame, highlightColorPtr)}, \
	{ "-highlightthickness" , "highlightThickness", "HighlightThickness", DEF_FRAME_HIGHLIGHT_WIDTH,  0,NULL, \
		NULL, NULL, TKO_SET_PIXEL, &frameMeta, offsetof(tkoFrame, highlightWidth)}, \
	{ "-padx" , "padX", "Pad", DEF_FRAME_PADX, 0,NULL, \
		NULL, NULL, TKO_SET_PIXEL, &frameMeta, offsetof(tkoFrame, padX)}, \
	{ "-pady" , "padY", "Pad", DEF_FRAME_PADY, 0,NULL, \
		NULL, NULL, TKO_SET_PIXEL, &frameMeta, offsetof(tkoFrame, padY)}, \
	{ "-takefocus" , "takeFocus", "TakeFocus", DEF_FRAME_TAKE_FOCUS,  0,NULL, \
		NULL, NULL, TKO_SET_STRING, NULL, 0}, \
	{ "-width" , "width", "Width", DEF_FRAME_WIDTH,  0,NULL, \
		NULL, NULL, TKO_SET_PIXEL, &frameMeta, offsetof(tkoFrame, width)}, \
	{ NULL,NULL,NULL,NULL,0,NULL, NULL,NULL,0,NULL,0}

/* tko::frame options */
static tkoWidgetOptionDefine frameOptions[] = {
    {"-class", "class", "Class", "TkoFrame", TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_CLASS, NULL, 0},
    {"-visual", "visual", "Visual", DEF_FRAME_VISUAL, TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_VISUAL, NULL, 0},
    {"-colormap", "colormap", "Colormap", DEF_FRAME_COLORMAP, TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_COLORMAP, NULL, 0},
    {"-container", "container", "Container", DEF_FRAME_CONTAINER, TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_CONTAINER, &frameMeta, offsetof(tkoFrame, isContainer)},
    {"-borderwidth", "borderWidth", "BorderWidth", DEF_FRAME_BORDER_WIDTH, 0,NULL,
	NULL, NULL, TKO_SET_PIXEL, &frameMeta, offsetof(tkoFrame, borderWidth)},
    {"-relief", "relief", "Relief", DEF_FRAME_RELIEF, 0,NULL,
	NULL, NULL, TKO_SET_RELIEF, &frameMeta, offsetof(tkoFrame, relief)},
    FRAME_COMMONDEFINE
};

/* tko::toplevel options */
static tkoWidgetOptionDefine toplevelOptions[] = {
    {"-screen", "screen", "Screen", "", TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_STRING, NULL, 0},
    {"-class", "class", "Class", "TkoToplevel", TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_CLASS, NULL, 0},
    {"-container", "container", "Container", DEF_FRAME_CONTAINER, TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_CONTAINER, &frameMeta, offsetof(tkoFrame, isContainer)},
    {"-use", "use", "Use", DEF_TOPLEVEL_USE, TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_USENULL, &frameMeta, offsetof(tkoFrame, useThis)},
    {"-visual", "visual", "Visual", DEF_FRAME_VISUAL, TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_VISUAL, NULL, 0},
    {"-colormap", "colormap", "Colormap", DEF_FRAME_COLORMAP, TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_COLORMAP, NULL, 0},
    {"-borderwidth", "borderWidth", "BorderWidth", DEF_FRAME_BORDER_WIDTH, 0,NULL,
	NULL, NULL, TKO_SET_PIXEL, &frameMeta, offsetof(tkoFrame, borderWidth)},
    {"-menu", "menu", "Menu", DEF_TOPLEVEL_MENU, 0,NULL,
	NULL, NULL, TKO_SET_STRINGNULL, &frameMeta, offsetof(tkoFrame, menuName)},
    {"-relief", "relief", "Relief", DEF_FRAME_RELIEF, 0,NULL,
	NULL, NULL, TKO_SET_RELIEF, &frameMeta, offsetof(tkoFrame, relief)},
    FRAME_COMMONDEFINE
};

/* tko::labelframe options */
static tkoWidgetOptionDefine labelframeOptions[] = {
    {"-class", "class", "Class", "TkoLabelframe", TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_CLASS, NULL, 0},
    {"-visual", "visual", "Visual", DEF_FRAME_VISUAL, TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_VISUAL, NULL, 0},
    {"-colormap", "colormap", "Colormap", DEF_FRAME_COLORMAP, TKO_OPTION_READONLY,NULL,
	NULL, NULL, TKO_SET_COLORMAP, NULL, 0},
    {"-borderwidth", "borderWidth", "BorderWidth", DEF_LABELFRAME_BORDER_WIDTH, 0,NULL,
	NULL, NULL, TKO_SET_PIXEL, &frameMeta, offsetof(tkoFrame, borderWidth)},
    {"-fg", "-foreground", NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, 0},
    {"-font", "font", "Font", DEF_LABELFRAME_FONT, 0,NULL,
	NULL, NULL, TKO_SET_FONT, &frameMeta, offsetof(tkoLabelframe, tkfont)},
	{"-foreground", "foreground", "Foreground", DEF_LABELFRAME_FG, 0, NULL,
	NULL, NULL, TKO_SET_XCOLOR, &frameMeta, offsetof(tkoLabelframe, textColorPtr)},
    {"-labelanchor", "labelAnchor", "LabelAnchor", DEF_LABELFRAME_LABELANCHOR, 0, NULL,
	NULL, FrameMethod_labelanchor, 0, NULL, 0},
    {"-labelwidget", "labelWidget", "LabelWidget", "",0, NULL,
	NULL, FrameMethod_labelwidget, 0, NULL, 0},
    {"-relief", "relief", "Relief", DEF_LABELFRAME_RELIEF, 0, NULL,
	NULL, NULL, TKO_SET_RELIEF, &frameMeta, offsetof(tkoFrame, relief)},
    {"-text", "text", "Text", DEF_LABELFRAME_TEXT, 0, NULL,
	NULL, NULL, TKO_SET_TCLOBJ, &frameMeta, offsetof(tkoLabelframe, textPtr)},
    FRAME_COMMONDEFINE
};

/*
 * Definition of object methods created in Tko_FrameInit() function.
 */

/* tko::frame methods. */
static Tcl_MethodType frameMethods[] = {
    {TCL_OO_METHOD_VERSION_CURRENT, NULL, FrameConstructorFrame, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, NULL, FrameDestructor, NULL, NULL},
    {-1, NULL, NULL, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "_tko_configure", FrameMethod_tko_configure,
            NULL, NULL},
    {-1, NULL, NULL, NULL, NULL}
};

/* tko::labelframe methods. */
static Tcl_MethodType labelframeMethods[] = {
    {TCL_OO_METHOD_VERSION_CURRENT, NULL, FrameConstructorLabelframe, NULL,
            NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, NULL, FrameDestructor, NULL, NULL},
    {-1, NULL, NULL, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "_tko_configure", FrameMethod_tko_configure,
            NULL, NULL},
    {-1, NULL, NULL, NULL, NULL}
};

/* tko::toplevel methods. */
static Tcl_MethodType toplevelMethods[] = {
    {TCL_OO_METHOD_VERSION_CURRENT, NULL, FrameConstructorToplevel, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, NULL, FrameDestructor, NULL, NULL},
    {-1, NULL, NULL, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "_tko_configure", FrameMethod_tko_configure,
            NULL, NULL},
    {-1, NULL, NULL, NULL, NULL}
};

/*
 * Tko_FrameInit --
 *
 * Create tko frame widget class objects.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
int
Tko_FrameInit(
    Tcl_Interp * interp)
{              /* Tcl interpreter. */
Tcl_Class clazz;
Tcl_Object object;

    /* Create class like tk command and remove oo functions from widget commands */
static const char *initScript =
    "::oo::class create ::tko::frame {superclass ::tko::widget; variable tko; {*}$::tko::unknown}\n"
    "::oo::class create ::tko::labelframe {superclass ::tko::widget; variable tko; {*}$::tko::unknown}\n"
    "::oo::class create ::tko::toplevel {superclass ::tko::widget; variable tko; {*}$::tko::unknown}\n";

    /* Create widget class. */
    if(Tcl_GlobalEval(interp, initScript) != TCL_OK) {
        return TCL_ERROR;
    }

    /*
     * ::tko::toplevel
     */
    /* Get class object */
    if((object = Tcl_GetObjectFromObj(interp, TkoObj.tko_toplevel)) == NULL
        || (clazz = Tcl_GetObjectAsClass(object)) == NULL) {
        return TCL_ERROR;
    }
    /* Add methods and options */
    if(TkoWidgetClassDefine(interp, clazz, Tcl_GetObjectName(interp, object),
            toplevelMethods, toplevelOptions) != TCL_OK) {
        return TCL_ERROR;
    }
    /*
     * ::tko::frame
     */
    /* Get class object */
    if((object = Tcl_GetObjectFromObj(interp, TkoObj.tko_frame)) == NULL
        || (clazz = Tcl_GetObjectAsClass(object)) == NULL) {
        return TCL_ERROR;
    }
    /* Add methods and options */
    if(TkoWidgetClassDefine(interp, clazz, Tcl_GetObjectName(interp, object),
            frameMethods, frameOptions) != TCL_OK) {
        return TCL_ERROR;
    }

    /*
     * ::tko::labelframe
     */
    /* Get class object */
    if((object = Tcl_GetObjectFromObj(interp, TkoObj.tko_labelframe)) == NULL
        || (clazz = Tcl_GetObjectAsClass(object)) == NULL) {
        return TCL_ERROR;
    }
    /* Add methods and options */
    if(TkoWidgetClassDefine(interp, clazz, Tcl_GetObjectName(interp, object),
            labelframeMethods, labelframeOptions) != TCL_OK) {
        return TCL_ERROR;
    }
    return TCL_OK;
}

/*
 * FrameConstructorFrame --
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
FrameConstructorFrame(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    return FrameConstructor(TYPE_FRAME, interp, context, objc, objv);
}

/*
 * FrameConstructorLabelframe --
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
FrameConstructorLabelframe(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    return FrameConstructor(TYPE_LABELFRAME, interp, context, objc, objv);
}

/*
 * FrameConstructorToplevel --
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
FrameConstructorToplevel(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    return FrameConstructor(TYPE_TOPLEVEL, interp, context, objc, objv);
}

/*
 * FrameDestructor --
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
FrameDestructor(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    int skip;
    Tcl_Object object;
    tkoFrame *frame;
    Tk_Window tkWin = NULL;
    tkoLabelframe *labelframe;
    if((object = Tcl_ObjectContextObject(context)) == NULL) {
        return TCL_ERROR;
    }
    skip = Tcl_ObjectContextSkippedArgs(context);
    if((frame = (tkoFrame *) Tcl_ObjectGetMetadata(object, &frameMeta)) != NULL) {
        Tcl_Preserve(frame);
        labelframe = (tkoLabelframe *) frame;

        if(frame->win) {
            tkWin = *(frame->win);
            frame->win = NULL;
        }
        if(tkWin) {
            Tk_DeleteEventHandler(tkWin, frame->mask, FrameEventProc, frame);
        }
        if(frame->cursor != None) {
            if(frame->display != None) {
                Tk_FreeCursor(frame->display, frame->cursor);
            }
            frame->cursor = None;
        }
        frame->flags = 0;
        Tcl_CancelIdleCall(FrameDisplay, frame);
        Tcl_CancelIdleCall(FrameMap, frame);

        if(frame->menuName != NULL && tkWin) {
            TkSetWindowMenuBar(frame->interp, tkWin, frame->menuName, NULL);
            frame->menuName = NULL;
        }
        if(frame->type == TYPE_LABELFRAME && labelframe->labelWin) {
            Tk_ManageGeometry(labelframe->labelWin, NULL, NULL);
            if(tkWin && (tkWin != Tk_Parent(labelframe->labelWin))) {
                Tk_UnmaintainGeometry(labelframe->labelWin, tkWin);
            }
            Tk_UnmapWindow(labelframe->labelWin);
            labelframe->labelWin = NULL;
        }
        Tcl_Release(frame);
        Tcl_ObjectSetMetadata(object, &frameMeta, NULL);
    }
    /* ignore errors */
    Tcl_ObjectContextInvokeNext(interp, context, objc, objv, skip);

    return TCL_OK;
}

/*
 * FrameMethod_tko_configure --
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
FrameMethod_tko_configure(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    char *oldMenuName;
    Tcl_Object object;
    tkoFrame *frame;
    tkoLabelframe *labelframe;
    Tk_Window oldWindow;
    Tk_Window tkwin;
    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (frame =
            (tkoFrame *) Tcl_ObjectGetMetadata(object, &frameMeta)) == NULL
        || frame->win == NULL || (tkwin = *(frame->win)) == NULL) {
        return TCL_ERROR;
    }
    labelframe = (tkoLabelframe *) frame;

    /*
     * Need the old menubar name for the menu code to delete it.
     */

    if(frame->menuName == NULL) {
        oldMenuName = NULL;
    } else {
        oldMenuName = ckalloc(strlen(frame->menuName) + 1);
        strcpy(oldMenuName, frame->menuName);
    }

    if(frame->type == TYPE_LABELFRAME) {
        oldWindow = labelframe->labelWin;
    }
    /*TODO ???      if (oldMenuName != NULL) {
     * ckfree(oldMenuName);
     * }
     */

    /*
     * A few of the options require additional processing.
     */

    if((((oldMenuName == NULL) && (frame->menuName != NULL))
            || ((oldMenuName != NULL) && (frame->menuName == NULL))
            || ((oldMenuName != NULL) && (frame->menuName != NULL)
                && strcmp(oldMenuName, frame->menuName) != 0))
        && frame->type == TYPE_TOPLEVEL) {
        TkSetWindowMenuBar(frame->interp, tkwin, oldMenuName, frame->menuName);
    }

    if(oldMenuName != NULL) {
        ckfree(oldMenuName);
    }

    if(frame->border != NULL) {
        Tk_SetBackgroundFromBorder(tkwin, frame->border);
    } else {
        Tk_SetWindowBackgroundPixmap(tkwin, None);
    }

    if(frame->highlightWidth < 0) {
        frame->highlightWidth = 0;
    }
    if(frame->padX < 0) {
        frame->padX = 0;
    }
    if(frame->padY < 0) {
        frame->padY = 0;
    }

    FrameWorldChanged(frame);
    if(Tcl_ObjectContextInvokeNext(interp, context, objc, objv,
            Tcl_ObjectContextSkippedArgs(context)) != TCL_OK) {
        return TCL_ERROR;
    }
    return TCL_OK;
}

/*
 * FrameMethod_labelanchor --
 *
 * Process -labelanchor option.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
FrameMethod_labelanchor(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    int index, code;
    Tcl_Object object;
    tkoLabelframe *labelframe;
    Tcl_Obj *value;
	static const char *const labelAnchorStrings[] = {
		"e", "en", "es", "n", "ne", "nw", "s", "se", "sw", "w", "wn", "ws",
		NULL
	};

	if((object = Tcl_ObjectContextObject(context)) == NULL
        || (labelframe =
            (tkoLabelframe *) Tcl_ObjectGetMetadata(object, &frameMeta)) == NULL
        || (value =
            TkoWidgetOptionGet(interp, object, objv[objc - 1])) == NULL) {
        return TCL_ERROR;
    }
    code =
        Tcl_GetIndexFromObj(interp, value, labelAnchorStrings, "labelanchor", 0,
        &index);
    if(code != TCL_OK) {
        return TCL_ERROR;
    }
    labelframe->labelAnchor = (Tk_Anchor) index;
    return TCL_OK;
}

/*
 * FrameMethod_labelwidget --
 *
 * Process -labelwidget option.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
FrameMethod_labelwidget(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    Tk_Window oldWindow = NULL;
    Tk_Window newWindow = NULL;
    Tk_Window tkwin = NULL;
    Tk_Window ancestor, parent, sibling = NULL;
    Tcl_Object object;
    tkoLabelframe *labelframe;
    Tcl_Obj *value;
    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (labelframe =
            (tkoLabelframe *) Tcl_ObjectGetMetadata(object, &frameMeta)) == NULL
        || (value =
            TkoWidgetOptionGet(interp, object, objv[objc - 1])) == NULL) {
        return TCL_ERROR;
    }

    if(labelframe->frame.win == NULL
        || (tkwin = *(labelframe->frame.win)) == NULL) {
        return TCL_ERROR;
    }

    if(value == NULL || Tcl_GetCharLength(value) == 0) {
        newWindow = NULL;
    } else if(TkGetWindowFromObj(interp, tkwin, value, &newWindow) != TCL_OK) {
        return TCL_ERROR;
    }
    /*
     * If a -labelwidget is specified, check that it is valid and set up
     * geometry management for it.
     */
    oldWindow = labelframe->labelWin;
    if(oldWindow != newWindow) {
        if(newWindow != NULL) {
            /*
             * Make sure that the frame is either the parent of the window
             * used as label or a descendant of that parent. Also, don't
             * allow a top-level window to be managed inside the frame.
             */
            parent = Tk_Parent(newWindow);
            for(ancestor = tkwin;; ancestor = Tk_Parent(ancestor)) {
                if(ancestor == parent) {
                    break;
                }
                sibling = ancestor;
                if(Tk_IsTopLevel(ancestor)) {
                    goto badLabelWindow;
                }
            }
            if(Tk_IsTopLevel(newWindow)) {
                goto badLabelWindow;
            }
            if(newWindow == tkwin) {
                goto badLabelWindow;
            }
        }
        if(oldWindow != NULL) {
            Tk_DeleteEventHandler(oldWindow, StructureNotifyMask,
                FrameStructureProc, labelframe);
            Tk_ManageGeometry(oldWindow, NULL, NULL);
            Tk_UnmaintainGeometry(oldWindow, tkwin);
            Tk_UnmapWindow(oldWindow);
        }
        if(newWindow != NULL) {
            Tk_CreateEventHandler(newWindow,
                StructureNotifyMask, FrameStructureProc, labelframe);
            Tk_ManageGeometry(newWindow, &frameGeomType, labelframe);
            /*
             * If the frame is not parent to the label, make sure the
             * label is above its sibling in the stacking order.
             */
            if(sibling != NULL) {
                Tk_RestackWindow(newWindow, Above, sibling);
            }
        }
        labelframe->labelWin = newWindow;
    }
    //      FrameWorldChanged(labelframe);
    return TCL_OK;

  badLabelWindow:
    Tcl_SetObjResult(interp,
        Tcl_ObjPrintf("can't use %s as label in this frame",
            Tk_PathName(labelframe->labelWin)));
    Tcl_SetErrorCode(interp, "TK", "GEOMETRY", "HIERARCHY", NULL);
    labelframe->labelWin = NULL;
    return TCL_ERROR;
}

/*
 * FrameConstructor --
 *
 * Common part of all widget contructors.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
FrameConstructor(
    int type,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    Tcl_Object object;
    tkoFrame *frame;
    int skip;
    Tcl_Obj *myObjv[2];

    /* Get current object. Should not fail? */
    if((object = Tcl_ObjectContextObject(context)) == NULL) {
        return TCL_ERROR;
    }
    skip = Tcl_ObjectContextSkippedArgs(context);
    /* Check objv[] arguments: ... optionlist arglist */
    if(objc - skip != 2) {
        Tcl_WrongNumArgs(interp, 1, objv, "optionlist arglist");
        return TCL_ERROR;
    }
    if(type == TYPE_FRAME) {
        frame = ckalloc(sizeof(tkoFrame));
        memset(frame, 0, sizeof(tkoFrame));
        myObjv[0] =
            Tcl_ObjGetVar2(interp, TkoObj.tko_options, TkoObj.tko_frame,
            TCL_GLOBAL_ONLY);
        myObjv[1] = objv[objc - 1];
    } else if(type == TYPE_LABELFRAME) {
    tkoLabelframe *labelframe;

        frame = ckalloc(sizeof(tkoLabelframe));
        memset(frame, 0, sizeof(tkoLabelframe));
        myObjv[0] =
            Tcl_ObjGetVar2(interp, TkoObj.tko_options, TkoObj.tko_labelframe,
            TCL_GLOBAL_ONLY);
        myObjv[1] = objv[objc - 1];
        labelframe = (tkoLabelframe *) frame;
        labelframe->textPtr = NULL;
        labelframe->tkfont = NULL;
        labelframe->textColorPtr = NULL;
        labelframe->labelAnchor = LABELANCHOR_NW;
        labelframe->labelWin = NULL;
        labelframe->textGC = None;
        labelframe->textLayout = NULL;
        /*labelframe->labelBox */
        labelframe->labelReqWidth = 0;
        labelframe->labelReqHeight = 0;
        labelframe->labelTextX = 0;
        labelframe->labelTextY = 0;
    } else if(type == TYPE_TOPLEVEL) {
        myObjv[1] = Tcl_NewStringObj("-screen {}", -1);
        Tcl_IncrRefCount(myObjv[1]);
        if(Tcl_ListObjAppendList(interp, myObjv[1], objv[objc - 1]) != TCL_OK) {
            Tcl_DecrRefCount(myObjv[1]);
            return TCL_ERROR;
        }
        frame = ckalloc(sizeof(tkoFrame));
        memset(frame, 0, sizeof(tkoFrame));
        myObjv[0] =
            Tcl_ObjGetVar2(interp, TkoObj.tko_options, TkoObj.tko_toplevel,
            TCL_GLOBAL_ONLY);
    } else {
        Tcl_WrongNumArgs(interp, 1, objv, "internal type error");
        return TCL_ERROR;
    }
    if(myObjv[0] == NULL) {
        return TCL_ERROR;
    }
    frame->win = NULL;
    frame->object = object;
    frame->interp = interp;
    frame->display = None;
    frame->type = type;
    frame->menuName = NULL;
    frame->colormap = None;
    frame->border = NULL;
    frame->borderWidth = 0;
    frame->relief = TK_RELIEF_FLAT;
    frame->highlightWidth = 0;
    frame->highlightBgColorPtr = NULL;
    frame->highlightColorPtr = NULL;
    frame->width = 0;
    frame->height = 0;
    frame->cursor = None;
    frame->isContainer = 0;
    frame->useThis = NULL;
    frame->flags = 0;
    frame->padX = 0;
    frame->padY = 0;
    frame->mask = ExposureMask | StructureNotifyMask | FocusChangeMask;
    if(type == TYPE_TOPLEVEL) {
        frame->mask |= ActivateMask;
    }

    Tcl_ObjectSetMetadata(object, &frameMeta, (ClientData) frame);

    myObjv[0] = Tcl_DuplicateObj(myObjv[0]);
    Tcl_IncrRefCount(myObjv[0]);
    Tcl_ListObjAppendList(interp, myObjv[0], objv[objc - 2]);
    if(Tcl_ObjectContextInvokeNext(interp, context, 2, myObjv, 0) != TCL_OK) {
        Tcl_DecrRefCount(myObjv[0]);
        if(type == TYPE_TOPLEVEL) {
            Tcl_DecrRefCount(myObjv[1]);
        }
        return TCL_ERROR;
    }
    Tcl_DecrRefCount(myObjv[0]);
    if(type == TYPE_TOPLEVEL) {
        Tcl_DecrRefCount(myObjv[1]);
    }
    frame->win = TkoWidgetWindow(object);
    if(frame->win == NULL || *(frame->win) == NULL) {
        return TCL_ERROR;
    }
    if((frame->display = Tk_Display(*(frame->win))) == None) {
        return TCL_ERROR;
    }
    if(frame->isContainer && frame->useThis != NULL) {
        Tcl_SetObjResult(interp,
            Tcl_NewStringObj
            ("windows cannot have both the -use and the -container"
                " option set", -1));
        Tcl_SetErrorCode(interp, "TK", "FRAME", "CONTAINMENT", NULL);
        return TCL_ERROR;
    }
    /*
     * For top-level windows, provide an initial geometry request of 200x200,
     * just so the window looks nicer on the screen if it doesn't request a
     * size for itself.
     */
    if(type == TYPE_TOPLEVEL) {
        Tk_GeometryRequest(*(frame->win), 200, 200);
    }

    /*
     * Store backreference to frame widget in window structure.
     */

    Tk_SetClassProcs(*(frame->win), &frameClass, frame);

    /*
     * Mark Tk frames as suitable candidates for [wm manage].
     */

    ((TkWindow *) * (frame->win))->flags |= TK_WM_MANAGEABLE;

    Tk_CreateEventHandler(*(frame->win), frame->mask, FrameEventProc, frame);

    if(type == TYPE_TOPLEVEL) {
        Tcl_DoWhenIdle(FrameMap, frame);
    }

    return TCL_OK;
}

/*
 * FrameMetaDestroy --
 *
 *	This function is invoked by Tcl_EventuallyFree or Tcl_Release to clean
 *	up the internal structure of a frame at a safe time (when no-one is
 *	using it anymore).
 *
 * Results:
 *	None.
 *
 * Side effects:
 *	Everything associated with the frame is freed up.
 */
static void
FrameMetaDestroy(
    tkoFrame * frame)
{              /* Info about frame widget. */
tkoLabelframe *labelframe = (tkoLabelframe *) frame;

    if(frame->menuName != NULL) {
        ckfree(frame->menuName);
    }
    if(frame->useThis) {
        Tcl_DecrRefCount(frame->useThis);
    }
    if(frame->type == TYPE_LABELFRAME) {
        if(labelframe->textLayout) {
            Tk_FreeTextLayout(labelframe->textLayout);
        }
        if(labelframe->textGC != None && frame->display != None) {
            Tk_FreeGC(frame->display, labelframe->textGC);
        }
    }
    if(frame->border) {
        Tk_Free3DBorder(frame->border);
    }
    if(frame->colormap != None && frame->display != None) {
        Tk_FreeColormap(frame->display, frame->colormap);
    }
    if(frame->highlightBgColorPtr != NULL) {
        Tk_FreeColor(frame->highlightBgColorPtr);
    }
    if(frame->highlightColorPtr != NULL) {
        Tk_FreeColor(frame->highlightColorPtr);
    }
    ckfree(frame);
}

/*
 * FrameWorldChanged --
 *
 *	This function is called when the world has changed in some way and the
 *	widget needs to recompute all its graphics contexts and determine its
 *	new geometry.
 *
 * Results:
 *	None.
 *
 * Side effects:
 *	Frame will be relayed out and redisplayed.
 */
static void
FrameWorldChanged(
    ClientData instanceData)
{              /* Information about widget. */
tkoFrame *frame = instanceData;
tkoLabelframe *labelframe = instanceData;
XGCValues gcValues;
GC  gc;
int anyTextLabel, anyWindowLabel;
int bWidthLeft, bWidthRight, bWidthTop, bWidthBottom;
const char *labelText;
    if(frame->win == NULL || *(frame->win) == NULL)
        return;

    anyTextLabel = (frame->type == TYPE_LABELFRAME) &&
        (labelframe->textPtr != NULL) && (labelframe->labelWin == NULL);
    anyWindowLabel = (frame->type == TYPE_LABELFRAME) &&
        (labelframe->labelWin != NULL);

    if(frame->type == TYPE_LABELFRAME) {
        /*
         * The textGC is needed even in the labelWin case, so it's always
         * created for a labelframe.
         */

        gcValues.font = Tk_FontId(labelframe->tkfont);
        gcValues.foreground = labelframe->textColorPtr->pixel;
        gcValues.graphics_exposures = False;
        gc = Tk_GetGC(*(frame->win),
            GCForeground | GCFont | GCGraphicsExposures, &gcValues);
        if(labelframe->textGC != None) {
            Tk_FreeGC(frame->display, labelframe->textGC);
        }
        labelframe->textGC = gc;

        /*
         * Calculate label size.
         */

        labelframe->labelReqWidth = labelframe->labelReqHeight = 0;

        if(anyTextLabel) {
            labelText = Tcl_GetString(labelframe->textPtr);
            if(labelframe->textLayout) {
                Tk_FreeTextLayout(labelframe->textLayout);
            }
            labelframe->textLayout =
                Tk_ComputeTextLayout(labelframe->tkfont,
                labelText, -1, 0, TK_JUSTIFY_CENTER, 0,
                &labelframe->labelReqWidth, &labelframe->labelReqHeight);
            labelframe->labelReqWidth += 2 * LABELSPACING;
            labelframe->labelReqHeight += 2 * LABELSPACING;
        } else if(anyWindowLabel) {
            labelframe->labelReqWidth = Tk_ReqWidth(labelframe->labelWin);
            labelframe->labelReqHeight = Tk_ReqHeight(labelframe->labelWin);
        }

        /*
         * Make sure label size is at least as big as the border. This
         * simplifies later calculations and gives a better appearance with
         * thick borders.
         */

        if((labelframe->labelAnchor >= LABELANCHOR_N) &&
            (labelframe->labelAnchor <= LABELANCHOR_SW)) {
            if(labelframe->labelReqHeight < frame->borderWidth) {
                labelframe->labelReqHeight = frame->borderWidth;
            }
        } else {
            if(labelframe->labelReqWidth < frame->borderWidth) {
                labelframe->labelReqWidth = frame->borderWidth;
            }
        }
    }

    /*
     * Calculate individual border widths.
     */

    bWidthBottom = bWidthTop = bWidthRight = bWidthLeft =
        frame->borderWidth + frame->highlightWidth;

    bWidthLeft += frame->padX;
    bWidthRight += frame->padX;
    bWidthTop += frame->padY;
    bWidthBottom += frame->padY;

    if(anyTextLabel || anyWindowLabel) {
        switch (labelframe->labelAnchor) {
        case LABELANCHOR_E:
        case LABELANCHOR_EN:
        case LABELANCHOR_ES:
            bWidthRight += labelframe->labelReqWidth - frame->borderWidth;
            break;
        case LABELANCHOR_N:
        case LABELANCHOR_NE:
        case LABELANCHOR_NW:
            bWidthTop += labelframe->labelReqHeight - frame->borderWidth;
            break;
        case LABELANCHOR_S:
        case LABELANCHOR_SE:
        case LABELANCHOR_SW:
            bWidthBottom += labelframe->labelReqHeight - frame->borderWidth;
            break;
        default:
            bWidthLeft += labelframe->labelReqWidth - frame->borderWidth;
            break;
        }
    }

    Tk_SetInternalBorderEx(*(frame->win), bWidthLeft, bWidthRight, bWidthTop,
        bWidthBottom);

    FrameComputeGeometry(frame);

    /*
     * A labelframe should request size for its label.
     */

    if(frame->type == TYPE_LABELFRAME) {
int minwidth = labelframe->labelReqWidth;
int minheight = labelframe->labelReqHeight;
int padding = frame->highlightWidth;

        if(frame->borderWidth > 0) {
            padding += frame->borderWidth + LABELMARGIN;
        }
        padding *= 2;
        if((labelframe->labelAnchor >= LABELANCHOR_N) &&
            (labelframe->labelAnchor <= LABELANCHOR_SW)) {
            minwidth += padding;
            minheight += frame->borderWidth + frame->highlightWidth;
        } else {
            minheight += padding;
            minwidth += frame->borderWidth + frame->highlightWidth;
        }
        Tk_SetMinimumRequestSize(*(frame->win), minwidth, minheight);
    }

    if((frame->width > 0) || (frame->height > 0)) {
        Tk_GeometryRequest(*(frame->win), frame->width, frame->height);
    }

    if(Tk_IsMapped(*(frame->win))) {
        if(!(frame->flags & REDRAW_PENDING)) {
            Tcl_DoWhenIdle(FrameDisplay, frame);
        }
        frame->flags |= REDRAW_PENDING;
    }
}

/*
 * FrameComputeGeometry --
 *
 *	This function is called to compute various geometrical information for
 *	a frame, such as where various things get displayed. It's called when
 *	the window is reconfigured.
 *
 * Results:
 *	None.
 *
 * Side effects:
 *	Display-related numbers get changed in *frame.
 */

static void
FrameComputeGeometry(
    register tkoFrame * frame)
{              /* Information about widget. */
    int otherWidth, otherHeight, otherWidthT, otherHeightT, padding;
    int maxWidth, maxHeight;
    tkoLabelframe *labelframe = (tkoLabelframe *) frame;
    if(frame->win == NULL || *(frame->win) == NULL)
        return;

    /*
     * We have nothing to do here unless there is a label.
     */

    if(frame->type != TYPE_LABELFRAME) {
        return;
    }
    if(labelframe->textPtr == NULL && labelframe->labelWin == NULL) {
        return;
    }

    /*
     * Calculate the available size for the label
     */

    labelframe->labelBox.width = labelframe->labelReqWidth;
    labelframe->labelBox.height = labelframe->labelReqHeight;

    padding = frame->highlightWidth;
    if(frame->borderWidth > 0) {
        padding += frame->borderWidth + LABELMARGIN;
    }
    padding *= 2;

    maxHeight = Tk_Height(*(frame->win));
    maxWidth = Tk_Width(*(frame->win));

    if((labelframe->labelAnchor >= LABELANCHOR_N) &&
        (labelframe->labelAnchor <= LABELANCHOR_SW)) {
        maxWidth -= padding;
        if(maxWidth < 1) {
            maxWidth = 1;
        }
    } else {
        maxHeight -= padding;
        if(maxHeight < 1) {
            maxHeight = 1;
        }
    }
    if(labelframe->labelBox.width > maxWidth) {
        labelframe->labelBox.width = maxWidth;
    }
    if(labelframe->labelBox.height > maxHeight) {
        labelframe->labelBox.height = maxHeight;
    }

    /*
     * Calculate label and text position. The text's position is based on the
     * requested size (= the text's real size) to get proper alignment if the
     * text does not fit.
     */

    otherWidth = Tk_Width(*(frame->win)) - labelframe->labelBox.width;
    otherHeight = Tk_Height(*(frame->win)) - labelframe->labelBox.height;
    otherWidthT = Tk_Width(*(frame->win)) - labelframe->labelReqWidth;
    otherHeightT = Tk_Height(*(frame->win)) - labelframe->labelReqHeight;
    padding = frame->highlightWidth;

    switch (labelframe->labelAnchor) {
    case LABELANCHOR_E:
    case LABELANCHOR_EN:
    case LABELANCHOR_ES:
        labelframe->labelTextX = otherWidthT - padding;
        labelframe->labelBox.x = otherWidth - padding;
        break;
    case LABELANCHOR_N:
    case LABELANCHOR_NE:
    case LABELANCHOR_NW:
        labelframe->labelTextY = padding;
        labelframe->labelBox.y = padding;
        break;
    case LABELANCHOR_S:
    case LABELANCHOR_SE:
    case LABELANCHOR_SW:
        labelframe->labelTextY = otherHeightT - padding;
        labelframe->labelBox.y = otherHeight - padding;
        break;
    default:
        labelframe->labelTextX = padding;
        labelframe->labelBox.x = padding;
        break;
    }

    if(frame->borderWidth > 0) {
        padding += frame->borderWidth + LABELMARGIN;
    }

    switch (labelframe->labelAnchor) {
    case LABELANCHOR_NW:
    case LABELANCHOR_SW:
        labelframe->labelTextX = padding;
        labelframe->labelBox.x = padding;
        break;
    case LABELANCHOR_N:
    case LABELANCHOR_S:
        labelframe->labelTextX = otherWidthT / 2;
        labelframe->labelBox.x = otherWidth / 2;
        break;
    case LABELANCHOR_NE:
    case LABELANCHOR_SE:
        labelframe->labelTextX = otherWidthT - padding;
        labelframe->labelBox.x = otherWidth - padding;
        break;
    case LABELANCHOR_EN:
    case LABELANCHOR_WN:
        labelframe->labelTextY = padding;
        labelframe->labelBox.y = padding;
        break;
    case LABELANCHOR_E:
    case LABELANCHOR_W:
        labelframe->labelTextY = otherHeightT / 2;
        labelframe->labelBox.y = otherHeight / 2;
        break;
    default:
        labelframe->labelTextY = otherHeightT - padding;
        labelframe->labelBox.y = otherHeight - padding;
        break;
    }
}

/*
 * FrameDisplay --
 *
 *	This function is invoked to display a frame widget.
 *
 * Results:
 *	None.
 *
 * Side effects:
 *	Commands are output to X to display the frame in its current mode.
 */
static void
FrameDisplay(
    ClientData clientData /* Information about widget. */)
{             
    tkoFrame *frame = clientData;
    int bdX1, bdY1, bdX2, bdY2, hlWidth;
    Pixmap pixmap;
    TkRegion clipRegion = NULL;

    if(frame->win == NULL || *(frame->win) == NULL)
        return;

    frame->flags &= ~REDRAW_PENDING;
    if(!Tk_IsMapped(*(frame->win))) {
        return;
    }

    /*
     * Highlight shall always be drawn if it exists, so do that first.
     */

    hlWidth = frame->highlightWidth;

    if(hlWidth != 0) {
GC  fgGC, bgGC;

        bgGC = Tk_GCForColor(frame->highlightBgColorPtr,
            Tk_WindowId(*(frame->win)));
        if(frame->flags & GOT_FOCUS) {
            fgGC = Tk_GCForColor(frame->highlightColorPtr,
                Tk_WindowId(*(frame->win)));
            TkpDrawHighlightBorder(*(frame->win), fgGC, bgGC, hlWidth,
                Tk_WindowId(*(frame->win)));
        } else {
            TkpDrawHighlightBorder(*(frame->win), bgGC, bgGC, hlWidth,
                Tk_WindowId(*(frame->win)));
        }
    }

    /*
     * If -background is set to "", no interior is drawn.
     */

    if(frame->border == NULL) {
        return;
    }

    if(frame->type != TYPE_LABELFRAME) {
        /*
         * Pass to platform specific draw function. In general, it just draws
         * a simple rectangle, but it may "theme" the background.
         */

      noLabel:
        TkpDrawFrame(*(frame->win), frame->border, hlWidth,
            frame->borderWidth, frame->relief);
    } else {
        tkoLabelframe *labelframe = (tkoLabelframe *) frame;

        if((labelframe->textPtr == NULL) && (labelframe->labelWin == NULL)) {
            goto noLabel;
        }
#ifndef TK_NO_DOUBLE_BUFFERING
        /*
         * In order to avoid screen flashes, this function redraws the frame
         * into off-screen memory, then copies it back on-screen in a single
         * operation. This means there's no point in time where the on-screen
         * image has been cleared.
         */

        pixmap = Tk_GetPixmap(frame->display, Tk_WindowId(*(frame->win)),
            Tk_Width(*(frame->win)), Tk_Height(*(frame->win)),
            Tk_Depth(*(frame->win)));
#else
        pixmap = Tk_WindowId(tkWin);
#endif /* TK_NO_DOUBLE_BUFFERING */

        /*
         * Clear the pixmap.
         */

        Tk_Fill3DRectangle(*(frame->win), pixmap, frame->border, 0, 0,
            Tk_Width(*(frame->win)), Tk_Height(*(frame->win)), 0,
            TK_RELIEF_FLAT);

        /*
         * Calculate how the label affects the border's position.
         */

        bdX1 = bdY1 = hlWidth;
        bdX2 = Tk_Width(*(frame->win)) - hlWidth;
        bdY2 = Tk_Height(*(frame->win)) - hlWidth;

        switch (labelframe->labelAnchor) {
        case LABELANCHOR_E:
        case LABELANCHOR_EN:
        case LABELANCHOR_ES:
            bdX2 -= (labelframe->labelBox.width - frame->borderWidth) / 2;
            break;
        case LABELANCHOR_N:
        case LABELANCHOR_NE:
        case LABELANCHOR_NW:
            /*
             * Since the glyphs of the text tend to be in the lower part we
             * favor a lower border position by rounding up.
             */

            bdY1 += (labelframe->labelBox.height - frame->borderWidth + 1) / 2;
            break;
        case LABELANCHOR_S:
        case LABELANCHOR_SE:
        case LABELANCHOR_SW:
            bdY2 -= (labelframe->labelBox.height - frame->borderWidth) / 2;
            break;
        default:
            bdX1 += (labelframe->labelBox.width - frame->borderWidth) / 2;
            break;
        }

        /*
         * Draw border
         */

        Tk_Draw3DRectangle(*(frame->win), pixmap, frame->border, bdX1, bdY1,
            bdX2 - bdX1, bdY2 - bdY1, frame->borderWidth, frame->relief);

        if(labelframe->labelWin == NULL) {
            /*
             * Clear behind the label
             */

            Tk_Fill3DRectangle(*(frame->win), pixmap,
                frame->border, labelframe->labelBox.x,
                labelframe->labelBox.y, labelframe->labelBox.width,
                labelframe->labelBox.height, 0, TK_RELIEF_FLAT);

            /*
             * Draw label. If there is not room for the entire label, use
             * clipping to get a nice appearance.
             */

            if((labelframe->labelBox.width < labelframe->labelReqWidth)
                || (labelframe->labelBox.height < labelframe->labelReqHeight)) {
                clipRegion = TkCreateRegion();
                TkUnionRectWithRegion(&labelframe->labelBox, clipRegion,
                    clipRegion);
                TkSetRegion(frame->display, labelframe->textGC, clipRegion);
            }

            Tk_DrawTextLayout(frame->display, pixmap,
                labelframe->textGC, labelframe->textLayout,
                labelframe->labelTextX + LABELSPACING,
                labelframe->labelTextY + LABELSPACING, 0, -1);

            if(clipRegion != NULL) {
                XSetClipMask(frame->display, labelframe->textGC, None);
                TkDestroyRegion(clipRegion);
            }
        } else {
            /*
             * Reposition and map the window (but in different ways depending
             * on whether the frame is the window's parent).
             */

            if(*(frame->win) == Tk_Parent(labelframe->labelWin)) {
                if((labelframe->labelBox.x != Tk_X(labelframe->labelWin))
                    || (labelframe->labelBox.y != Tk_Y(labelframe->labelWin))
                    || (labelframe->labelBox.width !=
                        Tk_Width(labelframe->labelWin))
                    || (labelframe->labelBox.height !=
                        Tk_Height(labelframe->labelWin))) {
                    Tk_MoveResizeWindow(labelframe->labelWin,
                        labelframe->labelBox.x,
                        labelframe->labelBox.y,
                        labelframe->labelBox.width,
                        labelframe->labelBox.height);
                }
                Tk_MapWindow(labelframe->labelWin);
            } else {
                Tk_MaintainGeometry(labelframe->labelWin, *(frame->win),
                    labelframe->labelBox.x, labelframe->labelBox.y,
                    labelframe->labelBox.width, labelframe->labelBox.height);
            }
        }

#ifndef TK_NO_DOUBLE_BUFFERING
        /*
         * Everything's been redisplayed; now copy the pixmap onto the screen
         * and free up the pixmap.
         */

        XCopyArea(frame->display, pixmap, Tk_WindowId(*(frame->win)),
            labelframe->textGC, hlWidth, hlWidth,
            (unsigned)(Tk_Width(*(frame->win)) - 2 * hlWidth),
            (unsigned)(Tk_Height(*(frame->win)) - 2 * hlWidth),
            hlWidth, hlWidth);
        Tk_FreePixmap(frame->display, pixmap);
#endif /* TK_NO_DOUBLE_BUFFERING */
    }

}

/*
 * FrameEventProc --
 *
 *	This function is invoked by the Tk dispatcher on structure changes to
 *	a frame. For frames with 3D borders, this function is also invoked for
 *	exposures.
 *
 * Results:
 *	None.
 *
 * Side effects:
 *	When the window gets deleted, internal structures get cleaned up.
 *	When it gets exposed, it is redisplayed.
 */
static void
FrameEventProc(
    ClientData clientData,     /* Information about window. */
    register XEvent * eventPtr)
{              /* Information about event. */
    tkoFrame *frame = clientData;
    if(eventPtr->type == DestroyNotify || frame->win == NULL
        || *(frame->win) == NULL)
        return;

    if((eventPtr->type == Expose) && (eventPtr->xexpose.count == 0)) {
        goto redraw;
    } else if(eventPtr->type == ConfigureNotify) {
        FrameComputeGeometry(frame);
        goto redraw;
    } else if(eventPtr->type == FocusIn) {
        if(eventPtr->xfocus.detail != NotifyInferior) {
            frame->flags |= GOT_FOCUS;
            if(frame->highlightWidth > 0) {
                goto redraw;
            }
        }
    } else if(eventPtr->type == FocusOut) {
        if(eventPtr->xfocus.detail != NotifyInferior) {
            frame->flags &= ~GOT_FOCUS;
            if(frame->highlightWidth > 0) {
                goto redraw;
            }
        }
    } else if(eventPtr->type == ActivateNotify) {
        TkpSetMainMenubar(frame->interp, *(frame->win), frame->menuName);
    }
    return;

  redraw:
    if(!(frame->flags & REDRAW_PENDING)) {
        Tcl_DoWhenIdle(FrameDisplay, frame);
        frame->flags |= REDRAW_PENDING;
    }
}

/*
 * FrameMap --
 *
 *	This function is invoked as a when-idle handler to map a newly-created
 *	top-level frame.
 *
 * Results:
 *	None.
 *
 * Side effects:
 *	The frame given by the clientData argument is mapped.
 */
static void
FrameMap(
    ClientData clientData)
{              /* Pointer to frame structure. */
tkoFrame *frame = clientData;
    if(frame->win == NULL || *(frame->win) == NULL)
        return;

    /*
     * Wait for all other background events to be processed before mapping
     * window. This ensures that the window's correct geometry will have been
     * determined before it is first mapped, so that the window manager
     * doesn't get a false idea of its desired geometry.
     */

    Tcl_Preserve(frame);
    while(1) {
        if(Tcl_DoOneEvent(TCL_IDLE_EVENTS) == 0) {
            break;
        }

        /*
         * After each event, make sure that the window still exists and quit
         * if the window has been destroyed.
         */
        if(frame->win == NULL || *(frame->win) == NULL) {
            Tcl_Release(frame);
            return;
        }
    }
    Tk_MapWindow(*(frame->win));
    Tcl_Release(frame);
}

/*
 * FrameStructureProc --
 *
 *	This function is invoked whenever StructureNotify events occur for a
 *	window that's managed as label for the frame. This procudure's only
 *	purpose is to clean up when windows are deleted.
 *
 * Results:
 *	None.
 *
 * Side effects:
 *	The window is disassociated from the frame when it is deleted.
 */
static void
FrameStructureProc(
    ClientData clientData,     /* Pointer to record describing frame. */
    XEvent * eventPtr)
{              /* Describes what just happened. */
tkoLabelframe *labelframe = clientData;

    /*
     * This should only happen in a labelframe but it doesn't hurt to be
     * careful.
     */
    if((eventPtr->type == DestroyNotify)
        && (labelframe->frame.type == TYPE_LABELFRAME)) {
        FrameLabelwinRemove(labelframe);
    }
}

/*
 * FrameLabelwinRemove --
 *
 * Results:
 *  None.
 *
 * Side effects:
 */
static void
FrameLabelwinRemove(
    tkoLabelframe * labelframe)
{
tkoFrame *frame = (tkoFrame *) labelframe;
Tcl_Obj *arrayName = TkoWidgetOptionVar(frame->object);
    labelframe->labelWin = NULL;
    if(arrayName == NULL)
        return;
    Tcl_ObjSetVar2(frame->interp, arrayName, TkoObj._labelwidget, TkoObj.empty,
        TCL_GLOBAL_ONLY);
    FrameWorldChanged(labelframe);
}

/*
 * FrameRequestProc --
 *
 *	This function is invoked whenever a window that's associated with a
 *	frame changes its requested dimensions.
 *
 * Results:
 *	None.
 *
 * Side effects:
 *	The size and location on the screen of the window may change depending
 *	on the options specified for the frame.
 */
static void
FrameRequestProc(
    ClientData clientData,     /* Pointer to record for frame. */
    Tk_Window tkWin)
{              /* Window that changed its desired size. */
tkoFrame *frame = clientData;

    FrameWorldChanged(frame);
}

/*
 * FrameLostSlaveProc --
 *
 *	This function is invoked by Tk whenever some other geometry claims
 *	control over a slave that used to be managed by us.
 *
 * Results:
 *	None.
 *
 * Side effects:
 *	Forgets all frame-related information about the slave.
 */
static void
FrameLostSlaveProc(
    ClientData clientData,     /* Frame structure for slave window that was
                                * stolen away. */
    Tk_Window tkWin            /* Tk's handle for the slave window. */)
{
    tkoLabelframe *labelframe = clientData;

    /*
     * This should only happen in a labelframe but it doesn't hurt to be
     * careful.
     */

    if(labelframe->frame.type == TYPE_LABELFRAME) {
        Tk_DeleteEventHandler(labelframe->labelWin, StructureNotifyMask,
            FrameStructureProc, labelframe);
        if(tkWin != Tk_Parent(labelframe->labelWin)) {
            Tk_UnmaintainGeometry(labelframe->labelWin, tkWin);
        }
        Tk_UnmapWindow(labelframe->labelWin);
        FrameLabelwinRemove(labelframe);
    }
}

/* vim: set ts=4 sw=4 sts=4 ff=unix et : */

/*
 * rbcGraph.c --
 *
 *      This module implements a graph widget for the rbc toolkit.
 *
 * Copyright (c) 2001 BLT was created by George Howlett.
 * Copyright (c) 2009 RBC was created by Samuel Green, Nicholas Hudson, Stanton Sievers, Jarrod Stormo
 * Copyright (c) 2018 Rene Zaumseil
 *
 * See the file "license.terms" for information on usage and redistribution of
 * this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

/*
 * To do:
 *
 * 5) Surface, contour, and flow graphs
 *
 * 7) Arrows for line markers
 *
 */

#include "tkoGraph.h"

Tk_Uid rbcXAxisUid;
Tk_Uid rbcYAxisUid;
Tk_Uid rbcBarElementUid;
Tk_Uid rbcLineElementUid;
Tk_Uid rbcStripElementUid;
Tk_Uid rbcContourElementUid;
Tk_Uid rbcLineMarkerUid;
Tk_Uid rbcBitmapMarkerUid;
Tk_Uid rbcImageMarkerUid;
Tk_Uid rbcTextMarkerUid;
Tk_Uid rbcPolygonMarkerUid;
Tk_Uid rbcWindowMarkerUid;

extern Tk_CustomOption rbcLinePenOption;
extern Tk_CustomOption rbcBarPenOption;
extern Tk_CustomOption rbcDistanceOption;
extern Tk_CustomOption rbcBarModeOption;
extern Tk_CustomOption rbcPadOption;
extern Tk_CustomOption rbcTileOption;
extern Tk_CustomOption rbcShadowOption;
extern Tk_CustomOption rbcStyleOption;

static Tk_ConfigSpec configSpecs[] = {
    {TK_CONFIG_END, NULL, NULL, NULL, NULL, 0, 0}
};

#define DEF_GRAPH_ASPECT_RATIO      "0.0"
#define DEF_GRAPH_BAR_BASELINE      "0.0"
#define DEF_GRAPH_BAR_MODE          "normal"
#define DEF_GRAPH_BAR_WIDTH         "0.8"
#define DEF_GRAPH_BACKGROUND        RBC_NORMAL_BACKGROUND
#define DEF_GRAPH_BG_MONO           RBC_NORMAL_BG_MONO
#define DEF_GRAPH_BORDERWIDTH       RBC_BORDERWIDTH
#define DEF_GRAPH_BUFFER_ELEMENTS   "1"
#define DEF_GRAPH_BUFFER_GRAPH	    "1"
#define DEF_GRAPH_CURSOR            "crosshair"
#define DEF_GRAPH_FONT              RBC_FONT_LARGE
#define DEF_GRAPH_HALO              "2m"
#define DEF_GRAPH_HALO_BAR          "0.1i"
#define DEF_GRAPH_HEIGHT            "4i"
#define DEF_GRAPH_HIGHLIGHT_BACKGROUND  RBC_NORMAL_BACKGROUND
#define DEF_GRAPH_HIGHLIGHT_BG_MONO RBC_NORMAL_BG_MONO
#define DEF_GRAPH_HIGHLIGHT_COLOR   "black"
#define DEF_GRAPH_HIGHLIGHT_WIDTH   "2"
#define DEF_GRAPH_INVERT_XY         "0"
#define DEF_GRAPH_JUSTIFY           "center"
#define DEF_GRAPH_MARGIN            "0"
#define DEF_GRAPH_MARGIN_VAR        (char *)NULL
#define DEF_GRAPH_PLOT_BACKGROUND   "white"
#define DEF_GRAPH_PLOT_BG_MONO      "white"
#define DEF_GRAPH_PLOT_BW_COLOR     RBC_BORDERWIDTH
#define DEF_GRAPH_PLOT_BW_MONO      "0"
#define DEF_GRAPH_PLOT_PADX         "8"
#define DEF_GRAPH_PLOT_PADY         "8"
#define DEF_GRAPH_PLOT_RELIEF       "sunken"
#define DEF_GRAPH_RELIEF            "flat"
#define DEF_GRAPH_SHADOW_COLOR      (char *)NULL
#define DEF_GRAPH_SHADOW_MONO       (char *)NULL
#define DEF_GRAPH_SHOW_VALUES       "no"
#define DEF_GRAPH_TAKE_FOCUS        ""
#define DEF_GRAPH_TITLE             (char *)NULL
#define DEF_GRAPH_TITLE_COLOR       RBC_NORMAL_FOREGROUND
#define DEF_GRAPH_TITLE_MONO        RBC_NORMAL_FG_MONO
#define DEF_GRAPH_WIDTH             "5i"
#define DEF_GRAPH_DATA              (char *)NULL
#define DEF_GRAPH_DATA_COMMAND      (char *)NULL

static RbcSwitchParseProc StringToFormat;
static RbcSwitchCustom formatSwitch = {
    StringToFormat, (RbcSwitchFreeProc *) NULL, (ClientData) 0,
};

/*
 * SnapData --
 */
typedef struct SnapData {
    char *name;
    int width, height;
    int format;
} SnapData;

enum SnapFormats { FORMAT_PHOTO, FORMAT_EMF, FORMAT_WMF };

/*
 * snapSwitches --
 */
static RbcSwitchSpec snapSwitches[] = {
    {RBC_SWITCH_INT_POSITIVE, "-width", Tk_Offset(SnapData, width), 0},
    {RBC_SWITCH_INT_POSITIVE, "-height", Tk_Offset(SnapData, height), 0},
    {RBC_SWITCH_CUSTOM, "-format", Tk_Offset(SnapData, format), 0,
        &formatSwitch},
    {RBC_SWITCH_END, NULL, 0, 0}
};

static Tcl_IdleProc DisplayGraph;
static Tk_EventProc GraphEventProc;

static RbcBindPickProc PickEntry;
static RbcTileChangedProc TileChangedProc;
/*
* Methods
*/
static int GraphConstructor(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphDestructor(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphMethod_tko_configure(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphMethod(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphMethod_style(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphMethod_barmode(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphMethod_barwidth(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphMethod_plotpadx(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphMethod_plotpady(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphMethod_shadow(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);
static int GraphMethod_tile(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[]);

/*
 * Functions
 */
static void AdjustAxisPointers(
    RbcGraph * graph);
static void DrawMargins(
    RbcGraph * graph,
    Drawable drawable);
static void DrawPlotRegion(
    RbcGraph * graph,
    Drawable drawable);
static void UpdateMarginTraces(
    RbcGraph * graph);
static int XAxisOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int X2AxisOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int YAxisOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int Y2AxisOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int BarOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int LineOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int ElementOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int ExtentsOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int InsideOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int InvtransformOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int TransformOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
static int SnapOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv);
#ifdef __WIN32
static int InitMetaFileHeader(
    Tk_Window tkwin,
    int width,
    int height,
    APMHEADER * mfhPtr);
static int CreateAPMetaFile(
    Tcl_Interp * interp,
    HANDLE hMetaFile,
    HDC hDC,
    APMHEADER * mfhPtr,
    char *fileName);
#endif
static void GraphMetaDestroy(
    RbcGraph * graph);
static void
GraphMetaDelete(
    ClientData clientData)
{
    Tcl_EventuallyFree(clientData, (Tcl_FreeProc *) GraphMetaDestroy);
}

/*
 * graphMeta --
 */
static Tcl_ObjectMetadataType graphMeta = {
    TCL_OO_METADATA_VERSION_CURRENT,
    "GraphMeta",
    GraphMetaDelete,
    NULL
};

/*
 * RbcGraphFromObject --
 *
 * Return:
 *  RbcGraph structure from object meta data.
 */
RbcGraph *
RbcGraphFromObject(
    Tcl_Object object)
{
    return (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta);
}

/*
 * graphOptionDefine --
 *
 * Options and option methods created in class constructor.
 */
static tkoWidgetOptionDefine graphOptionDefine[] = {
    {"-class", "class", "Class", "TkoGraph", TKO_OPTION_READONLY, NULL,
	NULL, NULL, TKO_SET_CLASS, NULL, 0},
    {"-style", "style", "Style", "line", TKO_OPTION_READONLY, NULL,
	NULL, GraphMethod_style, 0, NULL, 0},
    {"-aspect", "aspect", "Aspect", DEF_GRAPH_ASPECT_RATIO, 0, NULL,
	NULL, NULL, TKO_SET_DOUBLE, &graphMeta, offsetof(RbcGraph, aspect)},
    {"-background", "background", "Background", DEF_GRAPH_BACKGROUND, 0, NULL,
	NULL, NULL, TKO_SET_3DBORDER, &graphMeta, offsetof(RbcGraph, border)},
    {"-barmode", "barMode", "BarMode", DEF_GRAPH_BAR_MODE, 0, NULL,
	NULL, GraphMethod_barmode, 0, NULL, 0},
    {"-barwidth", "barWidth", "BarWidth", DEF_GRAPH_BAR_WIDTH, 0, NULL,
	NULL, GraphMethod_barwidth, 0, NULL, 0},
    {"-baseline", "baseline", "Baseline", DEF_GRAPH_BAR_BASELINE, 0, NULL,
	NULL, NULL, TKO_SET_DOUBLE, &graphMeta, offsetof(RbcGraph, baseline)},
    {"-bd", "-borderwidth", NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, 0},
    {"-bg", "-background", NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, 0},
    {"-bm", "-bottommargin", NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, 0},
    {"-borderwidth", "borderWidth", "BorderWidth", DEF_GRAPH_BORDERWIDTH, 0, NULL,
	NULL, NULL, TKO_SET_PIXELNONEGATIV, &graphMeta, offsetof(RbcGraph, borderWidth)},
    {"-bottommargin", "bottomMargin", "Margin", DEF_GRAPH_MARGIN, 0, NULL,
	NULL, NULL, TKO_SET_PIXELNONEGATIV, &graphMeta, offsetof(RbcGraph,margins[RBC_MARGIN_BOTTOM].reqSize)},
    {"-bottomvariable", "bottomVariable", "BottomVariable", DEF_GRAPH_MARGIN_VAR, 0, NULL,
	NULL, NULL, TKO_SET_STRINGNULL, &graphMeta, offsetof(RbcGraph,margins[RBC_MARGIN_BOTTOM].varName)},
    {"-bufferelements", "bufferElements", "BufferElements", DEF_GRAPH_BUFFER_ELEMENTS, 0, NULL,
	NULL, NULL, TKO_SET_BOOLEAN, &graphMeta, offsetof(RbcGraph, backingStore)},
    {"-buffergraph", "bufferGraph", "BufferGraph", DEF_GRAPH_BUFFER_GRAPH, 0, NULL,
	NULL, NULL, TKO_SET_BOOLEAN, &graphMeta, offsetof(RbcGraph, doubleBuffer)},
    {"-cursor", "cursor", "Cursor", DEF_GRAPH_CURSOR, 0, NULL,
	NULL, NULL, TKO_SET_CURSOR, &graphMeta, offsetof(RbcGraph, cursor)},
    {"-fg", "-foreground", NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, 0},
    {"-font", "font", "Font", DEF_GRAPH_FONT, 0, NULL,
	NULL, NULL, TKO_SET_FONT, &graphMeta, offsetof(RbcGraph, titleTextStyle.font)},
    {"-foreground", "foreground", "Foreground", DEF_GRAPH_TITLE_COLOR, 0, NULL,
	NULL, NULL, TKO_SET_XCOLOR, &graphMeta, offsetof(RbcGraph, titleTextStyle.color)},
    {"-halo", "halo", "Halo", DEF_GRAPH_HALO, 0, NULL,
	NULL, NULL, TKO_SET_PIXELNONEGATIV, &graphMeta, offsetof(RbcGraph, halo)},
    {"-height", "height", "Height", DEF_GRAPH_HEIGHT, 0, NULL,
	NULL, NULL, TKO_SET_PIXELNONEGATIV, &graphMeta, offsetof(RbcGraph, reqHeight)},
    {"-highlightbackground", "highlightBackground", "HighlightBackground", DEF_GRAPH_HIGHLIGHT_BACKGROUND, 0, NULL,
	NULL, NULL, TKO_SET_XCOLOR, &graphMeta, offsetof(RbcGraph, highlightBgColor)},
    {"-highlightcolor", "highlightColor", "HighlightColor", DEF_GRAPH_HIGHLIGHT_COLOR, 0, NULL,
	NULL, NULL, TKO_SET_XCOLOR, &graphMeta, offsetof(RbcGraph, highlightColor)},
    {"-highlightthickness", "highlightThickness", "HighlightThickness", DEF_GRAPH_HIGHLIGHT_WIDTH, 0, NULL,
	NULL, NULL, TKO_SET_PIXEL, &graphMeta, offsetof(RbcGraph, highlightWidth)},
    {"-invertxy", "invertXY", "InvertXY", DEF_GRAPH_INVERT_XY, 0, NULL,
	NULL, NULL, TKO_SET_BOOLEAN, &graphMeta, offsetof(RbcGraph, inverted)},
    {"-justify", "justify", "Justify", DEF_GRAPH_JUSTIFY, 0, NULL,
	NULL, NULL, TKO_SET_JUSTIFY, &graphMeta, offsetof(RbcGraph,titleTextStyle.justify)},
    {"-leftmargin", "leftMargin", "Margin", DEF_GRAPH_MARGIN, 0, NULL,
	NULL, NULL, TKO_SET_PIXELNONEGATIV, &graphMeta, offsetof(RbcGraph,margins[RBC_MARGIN_LEFT].reqSize)},
    {"-leftvariable", "leftVariable", "LeftVariable", DEF_GRAPH_MARGIN_VAR, 0, NULL,
	NULL, NULL, TKO_SET_STRINGNULL, &graphMeta, offsetof(RbcGraph,margins[RBC_MARGIN_LEFT].varName)},
    {"-lm", "-leftmargin", NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, 0},
    {"-plotbackground", "plotBackground", "Background", DEF_GRAPH_PLOT_BG_MONO, 0, NULL,
	NULL, NULL, TKO_SET_XCOLOR, &graphMeta, offsetof(RbcGraph, plotBg)},
    {"-plotborderwidth", "plotBorderWidth", "BorderWidth", DEF_GRAPH_PLOT_BW_COLOR, 0, NULL,
	NULL, NULL, TKO_SET_PIXELNONEGATIV, &graphMeta, offsetof(RbcGraph,plotBorderWidth)},
    {"-plotpadx", "plotPadX", "PlotPad", DEF_GRAPH_PLOT_PADX, 0, NULL,
	NULL, GraphMethod_plotpadx, 0, NULL, 0},
    {"-plotpady", "plotPadY", "PlotPad", DEF_GRAPH_PLOT_PADY, 0, NULL,
	NULL, GraphMethod_plotpady, 0, NULL, 0},
    {"-plotrelief", "plotRelief", "Relief", DEF_GRAPH_PLOT_RELIEF, 0, NULL,
	NULL, NULL, TKO_SET_RELIEF, &graphMeta, offsetof(RbcGraph, plotRelief)},
    {"-relief", "relief", "Relief", DEF_GRAPH_RELIEF, 0, NULL,
	NULL, NULL, TKO_SET_RELIEF, &graphMeta, offsetof(RbcGraph, relief)},
    {"-rightmargin", "rightMargin", "Margin", DEF_GRAPH_MARGIN, 0, NULL,
	NULL, NULL, TKO_SET_PIXELNONEGATIV, &graphMeta, offsetof(RbcGraph,margins[RBC_MARGIN_RIGHT].reqSize)},
    {"-rightvariable", "rightVariable", "RightVariable", DEF_GRAPH_MARGIN_VAR, 0, NULL,
	NULL, NULL, TKO_SET_STRINGNULL, &graphMeta, offsetof(RbcGraph,margins[RBC_MARGIN_RIGHT].varName)},
    {"-rm", "-rightmargin", NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, 0},
    {"-shadow", "shadow", "Shadow", DEF_GRAPH_SHADOW_COLOR, 0, NULL,
	NULL, GraphMethod_shadow, 0, NULL, 0},
    {"-takefocus", "takeFocus", "TakeFocus", DEF_GRAPH_TAKE_FOCUS, 0, NULL,
	NULL, NULL, TKO_SET_STRINGNULL, &graphMeta, offsetof(RbcGraph, takeFocus)},
    {"-tile", "tile", "Tile", NULL, 0, NULL,
	NULL, GraphMethod_tile, 0, NULL, 0},
    {"-title", "title", "Title", DEF_GRAPH_TITLE, 0, NULL,
	NULL, NULL, TKO_SET_STRINGNULL, &graphMeta, offsetof(RbcGraph, title)},
    {"-tm", "-topmargin", NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, 0},
    {"-topmargin", "-topmargin", "Margin", DEF_GRAPH_MARGIN, 0, NULL,
	NULL, NULL, TKO_SET_PIXELNONEGATIV, &graphMeta, offsetof(RbcGraph,margins[RBC_MARGIN_TOP].reqSize)},
    {"-topvariable", "topVariable", "TopVariable", DEF_GRAPH_MARGIN_VAR, 0, NULL,
	NULL, NULL, TKO_SET_STRINGNULL, &graphMeta, offsetof(RbcGraph,margins[RBC_MARGIN_TOP].varName)},
    {"-width", "width", "Width", DEF_GRAPH_WIDTH, 0, NULL,
	NULL, NULL, TKO_SET_PIXELNONEGATIV, &graphMeta, offsetof(RbcGraph, reqWidth)},
    {NULL, NULL, NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, 0}
};

/*
 * graphMethods --
 *
 * Methods created in class constructor.
 */
static Tcl_MethodType graphMethods[] = {
    {TCL_OO_METHOD_VERSION_CURRENT, NULL, GraphConstructor, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, NULL, GraphDestructor, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "axis", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "bar", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "crosshairs", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "element", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "extents", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "grid", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "inside", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "invtransform", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "legend", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "line", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "marker", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "pen", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "postscript", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "snap", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "transform", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "x2axis", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "xaxis", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "y2axis", GraphMethod, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "yaxis", GraphMethod, NULL, NULL},
    {-1, NULL, NULL, NULL, NULL},
    {TCL_OO_METHOD_VERSION_CURRENT, "_tko_configure", GraphMethod_tko_configure,
            NULL, NULL},
    {-1, NULL, NULL, NULL, NULL}
};

/*
 * Tko_GraphInit --
 *
 *  Initializer for the graph widget package.
 *
 * Results:
 *  A standard Tcl result.
 *
 * Side Effects:
 *  Tcl commands created
 */
int
Tko_GraphInit(
    Tcl_Interp * interp)
{
Tcl_Class clazz;
Tcl_Object object;
static const char *initScript =
    "::oo::class create ::graph {superclass ::tko::widget; variable tko; {*}$::tko::unknown}";

    rbcBarElementUid = Tk_GetUid("BarElement");
    rbcLineElementUid = Tk_GetUid("LineElement");
    rbcStripElementUid = Tk_GetUid("StripElement");
    rbcContourElementUid = Tk_GetUid("ContourElement");

    rbcLineMarkerUid = Tk_GetUid("LineMarker");
    rbcBitmapMarkerUid = Tk_GetUid("BitmapMarker");
    rbcImageMarkerUid = Tk_GetUid("ImageMarker");
    rbcTextMarkerUid = Tk_GetUid("TextMarker");
    rbcPolygonMarkerUid = Tk_GetUid("PolygonMarker");
    rbcWindowMarkerUid = Tk_GetUid("WindowMarker");

    rbcXAxisUid = Tk_GetUid("X");
    rbcYAxisUid = Tk_GetUid("Y");

    /* Create widget class. */
    if(Tcl_Eval(interp, initScript) != TCL_OK) {
        return TCL_ERROR;
    }
    /*
     * Get class object
     */
    if((object = Tcl_GetObjectFromObj(interp, TkoObj.graph)) == NULL
        || (clazz = Tcl_GetObjectAsClass(object)) == NULL) {
        return TCL_ERROR;
    }
    /*
     * Add methods and options
     */
    if(TkoWidgetClassDefine(interp, clazz, Tcl_GetObjectName(interp, object),
            graphMethods, graphOptionDefine) != TCL_OK) {
        return TCL_ERROR;
    }

    return TCL_OK;
}

/*
 * GraphConstructor --
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphConstructor(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    Tcl_Object object;
    RbcGraph *graph;
    int skip;
    Tcl_Obj *myObjv[5];

    /* Get current object. Should not fail? */
    if((object = Tcl_ObjectContextObject(context)) == NULL) {
        return TCL_ERROR;
    }
    skip = Tcl_ObjectContextSkippedArgs(context);
    /* Check calling args */
    if(skip != 3 || objc != 5 || strcmp("create", Tcl_GetString(objv[1])) != 0) {
        Tcl_WrongNumArgs(interp, 1, objv, "pathName ?options?");
        return TCL_ERROR;
    }
    if(objc < 3 || strcmp("create", Tcl_GetString(objv[1])) != 0) {
        Tcl_WrongNumArgs(interp, 1, objv, "pathName ?options?");
        return TCL_ERROR;
    }
    /* Get own options */
    myObjv[3] =
        Tcl_ObjGetVar2(interp, TkoObj.tko_options, TkoObj.graph,
        TCL_GLOBAL_ONLY);
    if(myObjv[3] == NULL) {
        return TCL_ERROR;
    }

    /*
     * Create and initialize the graph data structure.
     */
    graph = RbcCalloc(1, sizeof(RbcGraph));
    assert(graph);
    graph->interp = interp;
    graph->win = NULL;
    graph->classUid = rbcLineElementUid;
    graph->chartStyle = "line";
    graph->object = object;
    graph->display = None;
    graph->flags = (RBC_RESET_WORLD);
    graph->cursor = None;
    graph->inset = 0;
    graph->borderWidth = 0;
    graph->relief = TK_RELIEF_FLAT;
    graph->highlightWidth = 2;
    graph->cursor = None;
    graph->border = NULL;
    graph->highlightBgColor = NULL;
    graph->highlightColor = NULL;
    graph->title = NULL;
    graph->titleX = graph->titleY = 0;
    RbcInitTextStyle(&graph->titleTextStyle);
    graph->takeFocus = NULL;
    graph->reqWidth = graph->reqHeight = 0;
    graph->width = graph->height = 0;
    Tcl_InitHashTable(&graph->penTable, TCL_STRING_KEYS);
    Tcl_InitHashTable(&graph->axes.table, TCL_STRING_KEYS);
    Tcl_InitHashTable(&graph->axes.tagTable, TCL_STRING_KEYS);
    Tcl_InitHashTable(&graph->elements.table, TCL_STRING_KEYS);
    Tcl_InitHashTable(&graph->elements.tagTable, TCL_STRING_KEYS);
    Tcl_InitHashTable(&graph->markers.table, TCL_STRING_KEYS);
    Tcl_InitHashTable(&graph->markers.tagTable, TCL_STRING_KEYS);
    graph->elements.displayList = RbcChainCreate();
    graph->markers.displayList = RbcChainCreate();
    graph->axes.displayList = RbcChainCreate();
    graph->classUid = NULL;
    graph->chartStyle = NULL;
    graph->bindTable = NULL;
    graph->nextMarkerId = 1;
    graph->axisChain[0] = NULL; /* set in RbcDefaultAxes() */
    graph->axisChain[1] = NULL; /* set in RbcDefaultAxes() */
    graph->axisChain[2] = NULL; /* set in RbcDefaultAxes() */
    graph->axisChain[3] = NULL; /* set in RbcDefaultAxes() */
    graph->margins[RBC_MARGIN_BOTTOM].site = RBC_MARGIN_BOTTOM;
    graph->margins[RBC_MARGIN_LEFT].site = RBC_MARGIN_LEFT;
    graph->margins[RBC_MARGIN_TOP].site = RBC_MARGIN_TOP;
    graph->margins[RBC_MARGIN_RIGHT].site = RBC_MARGIN_RIGHT;
    graph->postscript = NULL;
    graph->legend = NULL;
    graph->crosshairs = NULL;
    graph->gridPtr = NULL;
    graph->halo = 0;
    graph->inverted = 0;
    graph->tile = NULL;
    graph->drawGC = NULL;
    graph->fillGC = NULL;
    graph->plotBorderWidth = 0;
    graph->plotRelief = TK_RELIEF_SUNKEN;
    graph->plotBg = NULL;
    graph->plotFillGC = NULL;
    graph->aspect = 0.0;
    graph->left = graph->right = 0;
    graph->top = graph->bottom = 0;
    graph->padX.side1 = graph->padX.side2 = 8;
    graph->vRange = graph->vOffset = 0;
    graph->padY.side1 = graph->padY.side2 = 8;
    graph->hRange = graph->hOffset = 0;
    graph->vScale = graph->hScale = 0.;
    graph->doubleBuffer = TRUE;
    graph->backingStore = TRUE;
    graph->backPixmap = None;
    graph->backWidth = graph->backHeight = 0;
    graph->baseline = 0.;
    graph->barWidth = 0.;
    graph->mode = MODE_INFRONT;
    graph->freqArr = NULL;
/*      Tcl_HashTable   freqTable; */
    graph->nStacks = 0;

    Tcl_ObjectSetMetadata(object, &graphMeta, (ClientData) graph);

    graph->win = TkoWidgetWindow(object);
    if(graph)
        /* call next constructor */
        myObjv[0] = objv[0];
    myObjv[1] = objv[1];
    myObjv[2] = objv[2];
    myObjv[3] = Tcl_DuplicateObj(myObjv[3]);
    Tcl_IncrRefCount(myObjv[3]);
    Tcl_ListObjAppendList(interp, myObjv[3], objv[objc - 2]);
    myObjv[4] = objv[4];
    if(Tcl_ObjectContextInvokeNext(interp, context, objc, myObjv,
            skip) != TCL_OK) {
        Tcl_DecrRefCount(myObjv[3]);
        return TCL_ERROR;
    }
    Tcl_DecrRefCount(myObjv[3]);
    graph->win = TkoWidgetWindow(object);
    if(graph->win == NULL || *(graph->win) == NULL) {
        return TCL_ERROR;
    }
    if((graph->display = Tk_Display(*(graph->win))) == None) {
        return TCL_ERROR;
    }

    RbcSetWindowInstanceData(*(graph->win), graph);

    /*
     * Init pens
     */
    if(RbcCreatePen(graph, "activeLine", rbcLineElementUid, 0,
            (const char **)NULL) == NULL) {
        return TCL_ERROR;
    }
    if(RbcCreatePen(graph, "activeBar", rbcBarElementUid, 0,
            (const char **)NULL) == NULL) {
        return TCL_ERROR;
    }
    /*
     * Create axis
     */
    if(RbcDefaultAxes(graph) != TCL_OK) {
        return TCL_ERROR;
    }
    AdjustAxisPointers(graph);

    if(RbcCreatePostScript(graph) != TCL_OK) {
        return TCL_ERROR;
    }
    if(RbcCreateCrosshairs(graph) != TCL_OK) {
        return TCL_ERROR;
    }
    if(RbcCreateLegend(graph) != TCL_OK) {
        return TCL_ERROR;
    }
    if(RbcCreateGrid(graph) != TCL_OK) {
        return TCL_ERROR;
    }
    Tk_CreateEventHandler(*(graph->win),
        ExposureMask | StructureNotifyMask | FocusChangeMask, GraphEventProc,
        graph);

    graph->bindTable =
        RbcCreateBindingTable(interp, *(graph->win), graph, PickEntry);

    /* No need to set return value. It will be ignored by "oo::class create" */
    return TCL_OK;
}

/*
 * GraphDestructor --
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphDestructor(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    Tcl_Object object;
    int skip;
    RbcGraph *graph;
    Tk_Window tkWin = NULL;

    /* Get current object. Should not fail? */
    if((object = Tcl_ObjectContextObject(context)) == NULL)
        return TCL_ERROR;
    skip = Tcl_ObjectContextSkippedArgs(context);

    if((graph = (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta)) != NULL) {
        Tcl_Preserve(graph);

        if(graph->win) {
            tkWin = *(graph->win);
            graph->win = NULL;
        }
        if(tkWin) {
            Tk_DeleteEventHandler(tkWin,
                ExposureMask | StructureNotifyMask | FocusChangeMask,
                GraphEventProc, graph);
        }

        Tcl_Release(graph);
        Tcl_ObjectSetMetadata(object, &graphMeta, NULL);
    }
    /* ignore errors */
    Tcl_ObjectContextInvokeNext(interp, context, objc, objv, skip);

    return TCL_OK;
}

/*
* GraphMetaDestroy --
*
*      This procedure is invoked by Tcl_EventuallyFree or Tcl_Release
*      to clean up the internal structure of a graph at a safe time
*      (when no-one is using it anymore).
*
* Results:
*      None.
*
* Side effects:
*      Everything associated with the widget is freed up.
*/
static void
GraphMetaDestroy(
    RbcGraph * graph)
{
    if(graph->flags & RBC_REDRAW_PENDING) {
        Tcl_CancelIdleCall(DisplayGraph, graph);
    }
    if(graph->border != NULL) {
        Tk_Free3DBorder(graph->border);
    }
    if(graph->highlightBgColor != NULL) {
        Tk_FreeColor(graph->highlightBgColor);
    }
    if(graph->highlightColor != NULL) {
        Tk_FreeColor(graph->highlightColor);
    }
    if(graph->plotBg != NULL) {
        Tk_FreeColor(graph->plotBg);
    }
    /*
     * Destroy the individual components of the graph: elements, markers,
     * X and Y axes, legend, display lists etc.
     */
    RbcDestroyMarkers(graph);
    RbcDestroyElements(graph);
    RbcDestroyAxes(graph);      /* take care of *axisChain */
    RbcDestroyPens(graph);

    if(graph->legend != NULL) {
        RbcDestroyLegend(graph);
    }
    if(graph->postscript != NULL) {
        RbcDestroyPostScript(graph);
    }
    if(graph->crosshairs != NULL) {
        RbcDestroyCrosshairs(graph);
    }
    if(graph->gridPtr != NULL) {
        RbcDestroyGrid(graph);
    }
    if(graph->bindTable != NULL) {
        RbcDestroyBindingTable(graph->bindTable);
    }

    /* Release allocated X resources and memory. */
    if(graph->display != None) {
        if(graph->cursor != None) {
            Tk_FreeCursor(graph->display, graph->cursor);
        }
        if(graph->drawGC != NULL) {
            Tk_FreeGC(graph->display, graph->drawGC);
        }
        if(graph->fillGC != NULL) {
            Tk_FreeGC(graph->display, graph->fillGC);
        }
        if(graph->plotFillGC != NULL) {
            Tk_FreeGC(graph->display, graph->plotFillGC);
        }
        RbcFreeTextStyle(graph->display, &graph->titleTextStyle);
        if(graph->backPixmap != None) {
            Tk_FreePixmap(graph->display, graph->backPixmap);
        }
    }
    if(graph->freqArr != NULL) {
        ckfree((char *)graph->freqArr);
    }
    if(graph->title != NULL) {
        ckfree(graph->title);
    }
    if(graph->takeFocus != NULL) {
        ckfree(graph->takeFocus);
    }
    if(graph->nStacks > 0) {
        Tcl_DeleteHashTable(&graph->freqTable);
    }
    if(graph->tile != NULL) {
        RbcFreeTile(graph->tile);
    }
    ckfree((char *)graph);
}

/*
* GraphMethod_tko_configure --
*
*      Allocates resources for the graph.
*
* Results:
*      None.
*
* Side effects:
*      Configuration information, such as text string, colors, font,
*      etc. get set for graph;  old resources get freed, if there
*      were any.  The graph is redisplayed.
*/
static int
GraphMethod_tko_configure(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    Tcl_Object object;
    RbcGraph *graph;
    XColor *colorPtr;
    GC  newGC;
    XGCValues gcValues;
    unsigned long gcMask;

    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (graph =
            (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta)) == NULL) {
        return TCL_ERROR;
    }
    if(graph->win == NULL || *(graph->win) == NULL)
        return TCL_ERROR;

    /* Don't allow negative bar widths. Reset to an arbitrary value (0.1) */
    if(graph->barWidth <= 0.0) {
        graph->barWidth = 0.1;
    }
    graph->inset = graph->borderWidth + graph->highlightWidth + 1;
    if((graph->reqHeight != Tk_ReqHeight(*(graph->win)))
        || (graph->reqWidth != Tk_ReqWidth(*(graph->win)))) {
        Tk_GeometryRequest(*(graph->win), graph->reqWidth, graph->reqHeight);
    }
    Tk_SetInternalBorder(*(graph->win), graph->borderWidth);
    colorPtr = Tk_3DBorderColor(graph->border);

    if(graph->title != NULL) {
    int w, h;

        RbcGetTextExtents(&graph->titleTextStyle, graph->title, &w, &h);
        graph->titleTextStyle.height = h + 10;
    } else {
        graph->titleTextStyle.width = graph->titleTextStyle.height = 0;
    }

    /*
     * Create GCs for interior and exterior regions, and a background
     * GC for clearing the margins with XFillRectangle
     */

    /* Margin GC */

    gcValues.foreground = graph->titleTextStyle.color->pixel;
    gcValues.background = colorPtr->pixel;
    gcMask = (GCForeground | GCBackground);
    newGC = Tk_GetGC(*(graph->win), gcMask, &gcValues);
    if(graph->drawGC != NULL) {
        Tk_FreeGC(graph->display, graph->drawGC);
    }
    graph->drawGC = newGC;

    /* Plot fill GC (Background = Foreground) */

    gcValues.foreground = graph->plotBg->pixel;
    newGC = Tk_GetGC(*(graph->win), gcMask, &gcValues);
    if(graph->plotFillGC != NULL) {
        Tk_FreeGC(graph->display, graph->plotFillGC);
    }
    graph->plotFillGC = newGC;

    /* Margin fill GC (Background = Foreground) */

    gcValues.foreground = colorPtr->pixel;
    gcValues.background = graph->titleTextStyle.color->pixel;
    newGC = Tk_GetGC(*(graph->win), gcMask, &gcValues);
    if(graph->fillGC != NULL) {
        Tk_FreeGC(graph->display, graph->fillGC);
    }
    graph->fillGC = newGC;
    if(graph->tile != NULL) {
        RbcSetTileChangedProc(graph->tile, TileChangedProc, graph);
    }

    RbcResetTextStyle(*(graph->win), &graph->titleTextStyle);

    if(RbcConfigModified(configSpecs, "-invertxy", (char *)NULL)) {

        /*
         * If the -inverted option changed, we need to readjust the pointers
         * to the axes and recompute the their scales.
         */

        AdjustAxisPointers(graph);
        graph->flags |= RBC_RESET_AXES;
    }
    if((!graph->backingStore) && (graph->backPixmap != None)) {

        /*
         * Free the pixmap if we're not buffering the display of elements
         * anymore.
         */

        Tk_FreePixmap(graph->display, graph->backPixmap);
        graph->backPixmap = None;
    }
    /*
     * Reconfigure the crosshairs, just in case the background color of
     * the plotarea has been changed.
     */
    RbcConfigureCrosshairs(graph);

    /*
     *  Update the layout of the graph (and redraw the elements) if
     *  any of the following graph options which affect the size of
     *  the plotting area has changed.
     *
     *      -aspect
     *      -borderwidth, -plotborderwidth
     *      -font, -title
     *      -width, -height
     *      -invertxy
     *      -bottommargin, -leftmargin, -rightmargin, -topmargin,
     *      -barmode, -barwidth
     */
    if(RbcConfigModified(configSpecs, "-invertxy", "-title", "-font",
            "-*margin", "-*width", "-height", "-barmode", "-*pad*", "-aspect",
            (char *)NULL)) {
        graph->flags |= RBC_RESET_WORLD;
    }
    if(RbcConfigModified(configSpecs, "-plotbackground", (char *)NULL)) {
        graph->flags |= RBC_REDRAW_BACKING_STORE;
    }
    graph->flags |= RBC_REDRAW_WORLD;
    RbcEventuallyRedrawGraph(graph);
    return TCL_OK;
}

/*
 * GraphMethod --
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphMethod(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    int cmdIndex, result;
    RbcOp proc;
    int i;
    const char **myArgv;
    static const char *const graphCmdNames[] = {
        "axis", "bar",
        "crosshairs", "element", "extents", "grid",
        "inside", "invtransform", "legend", "line",
        "marker", "pen", "postscript",
        "snap", "transform",
        "x2axis", "xaxis", "y2axis", "yaxis",
        NULL
    };

    enum graphCmd {
        COMMAND_AXIS, COMMAND_BAR,
        COMMAND_CROSSHAIRS, COMMAND_ELEMENT, COMMAND_EXTENTS, COMMAND_GRID,
        COMMAND_INSIDE, COMMAND_INVTRANSFORM, COMMAND_LEGEND, COMMAND_LINE,
        COMMAND_MARKER, COMMAND_PEN, COMMAND_POSTSCRIPT,
        COMMAND_SNAP, COMMAND_TRANSFORM,
        COMMAND_X2AXIS, COMMAND_XAXIS, COMMAND_Y2AXIS, COMMAND_YAXIS
    };

    RbcGraph *graph =
        (RbcGraph *) Tcl_ObjectGetMetadata(Tcl_ObjectContextObject(context),
        &graphMeta);

    /*
     * Parse the widget command by looking up the second token in the list of
     * valid command names.
     */

    result = Tcl_GetIndexFromObj(interp, objv[1], graphCmdNames, "option", 0,
        &cmdIndex);
    if(result != TCL_OK) {
        return result;
    }

    switch ((enum graphCmd)cmdIndex) {
    case COMMAND_AXIS:{
        proc = (RbcOp) RbcVirtualAxisOp;
        break;
    }
    case COMMAND_BAR:{
        proc = BarOp;
        break;
    }
    case COMMAND_CROSSHAIRS:{
        proc = RbcCrosshairsOp;
        break;
    }
    case COMMAND_ELEMENT:{
        proc = ElementOp;
        break;
    }
    case COMMAND_EXTENTS:{
        if(objc != 3) {
            Tcl_WrongNumArgs(interp, 2, objv, "item");
            return TCL_ERROR;
        }
        proc = ExtentsOp;
        break;
    }
    case COMMAND_GRID:{
        proc = RbcGridOp;
        break;
    }
    case COMMAND_INSIDE:{
        if(objc != 4) {
            Tcl_WrongNumArgs(interp, 2, objv, "winX winY");
            return TCL_ERROR;
        }
        proc = InsideOp;
        break;
    }
    case COMMAND_INVTRANSFORM:{
        if(objc != 4) {
            Tcl_WrongNumArgs(interp, 2, objv, "winX winY");
            return TCL_ERROR;
        }
        proc = InvtransformOp;
        break;
    }
    case COMMAND_LEGEND:{
        proc = RbcLegendOp;
        break;
    }
    case COMMAND_LINE:{
        proc = LineOp;
        break;
    }
    case COMMAND_MARKER:{
        proc = RbcMarkerOp;
        break;
    }
    case COMMAND_PEN:{
        proc = RbcPenOp;
        break;
    }
    case COMMAND_POSTSCRIPT:{
        proc = RbcPostScriptOp;
        break;
    }
    case COMMAND_SNAP:{
        if(objc < 3) {
            Tcl_WrongNumArgs(interp, 2, objv, "?switchse? name");
            return TCL_ERROR;
        }
        proc = SnapOp;
        break;
    }
    case COMMAND_TRANSFORM:{
        if(objc != 4) {
            Tcl_WrongNumArgs(interp, 2, objv, "x y");
            return TCL_ERROR;
        }
        proc = TransformOp;
        break;
    }
    case COMMAND_X2AXIS:{
        proc = X2AxisOp;
        break;
    }
    case COMMAND_XAXIS:{
        proc = XAxisOp;
        break;
    }
    case COMMAND_Y2AXIS:{
        proc = Y2AxisOp;
        break;
    }
    case COMMAND_YAXIS:{
        proc = YAxisOp;
        break;
    }
    default:{
        return TCL_ERROR;
    }
    }
    myArgv = ckalloc(objc * sizeof(char *));
    for(i = 0; i < objc; i++) {
        myArgv[i] = Tcl_GetString(objv[i]);
    }
    Tcl_Preserve(graph);
    result = (*proc) (graph, interp, objc, myArgv);
    Tcl_Release(graph);
    ckfree(myArgv);
    return result;
}

/*
 * GraphMethod_style --
 *
 *  Process -style option.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphMethod_style(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    const char *chPtr;
    Tcl_Object object;
    RbcGraph *graph;
    Tcl_Obj *value;
    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (graph =
            (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta)) == NULL
        || (value =
            TkoWidgetOptionGet(interp, object, objv[objc - 1])) == NULL) {
        return TCL_ERROR;
    }

    chPtr = Tcl_GetString(value);
    if(strcmp(chPtr, "line") == 0) {
        graph->classUid = rbcLineElementUid;
        graph->chartStyle = "line";
    } else if(strcmp(chPtr, "bar") == 0) {
        graph->classUid = rbcBarElementUid;
        graph->chartStyle = "bar";
    } else if(strcmp(chPtr, "chart") == 0) {
        graph->classUid = rbcStripElementUid;
        graph->chartStyle = "strip";
    } else {
        Tcl_SetObjResult(interp,
            Tcl_ObjPrintf("wrong -style option, should be line,bar or chart"));
        return TCL_ERROR;
    }
    return TCL_OK;
}

/*
 * GraphMethod_barmode --
 *
 *  Process -barmode option.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphMethod_barmode(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    const char *string;
    int length;
    Tcl_Object object;
    RbcGraph *graph;
    Tcl_Obj *value;
    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (graph =
            (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta)) == NULL
        || (value =
            TkoWidgetOptionGet(interp, object, objv[objc - 1])) == NULL) {
        return TCL_ERROR;
    }

    string = Tcl_GetStringFromObj(value, &length);
    if((string[0] == 'n') && (strncmp(string, "normal", length) == 0)) {
        graph->mode = MODE_INFRONT;
    } else if((string[0] == 'i') && (strncmp(string, "infront", length) == 0)) {
        graph->mode = MODE_INFRONT;
    } else if((string[0] == 's') && (strncmp(string, "stacked", length) == 0)) {
        graph->mode = MODE_STACKED;
    } else if((string[0] == 'a') && (strncmp(string, "aligned", length) == 0)) {
        graph->mode = MODE_ALIGNED;
    } else if((string[0] == 'o') && (strncmp(string, "overlap", length) == 0)) {
        graph->mode = MODE_OVERLAP;
    } else {
        Tcl_AppendResult(interp, "bad mode argument \"", string,
            "\": should be \"infront\", \"stacked\", \"overlap\", or \"aligned\"",
            (char *)NULL);
        return TCL_ERROR;
    }
    return TCL_OK;
}

/*
 * GraphMethod_barwidth --
 *
 *  Process -barwidth option.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphMethod_barwidth(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    double dblVal;
    Tcl_Obj *array;
    Tcl_Object object;
    RbcGraph *graph;
    Tcl_Obj *value;
    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (graph =
            (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta)) == NULL
        || (value =
            TkoWidgetOptionGet(interp, object, objv[objc - 1])) == NULL) {
        return TCL_ERROR;
    }

    if(Tcl_GetDoubleFromObj(interp, value, &dblVal) != TCL_OK) {
        return TCL_ERROR;
    }
    if((array = TkoWidgetOptionVar(object)) == NULL) {
        return TCL_ERROR;
    }
    if(dblVal < 0.1) {
        dblVal = 0.1;
    }
    Tcl_ObjSetVar2(interp, array, objv[objc - 1], Tcl_NewDoubleObj(dblVal),
        TCL_GLOBAL_ONLY);
    graph->barWidth = dblVal;
    return TCL_OK;
}

/*
 * GraphMethod_plotpadx --
 *
 *  Process -plotpadx option.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphMethod_plotpadx(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    Tcl_Obj *array;
    Tcl_Object object;
    RbcGraph *graph;
    Tcl_Obj *value;
    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (graph =
            (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta)) == NULL
        || (value =
            TkoWidgetOptionGet(interp, object, objv[objc - 1])) == NULL) {
        return TCL_ERROR;
    }

    if((array = TkoWidgetOptionVar(object)) == NULL) {
        return TCL_ERROR;
    }
    if(RbcGraphOptionSetPad(interp, object, value, &graph->padX) != TCL_OK) {
        return TCL_ERROR;
    }
    Tcl_ObjSetVar2(interp, array, objv[objc - 1],
        Tcl_ObjPrintf("%d %d", graph->padX.side1, graph->padX.side2),
        TCL_GLOBAL_ONLY);
    return TCL_OK;
}

/*
 * GraphMethod_plotpady --
 *
 *  Process -plotpady option.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphMethod_plotpady(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    Tcl_Obj *array;
    Tcl_Object object;
    RbcGraph *graph;
    Tcl_Obj *value;
    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (graph =
            (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta)) == NULL
        || (value =
            TkoWidgetOptionGet(interp, object, objv[objc - 1])) == NULL) {
        return TCL_ERROR;
    }

    if((array = TkoWidgetOptionVar(object)) == NULL) {
        return TCL_ERROR;
    }
    if(RbcGraphOptionSetPad(interp, object, value, &graph->padY) != TCL_OK) {
        return TCL_ERROR;
    }
    Tcl_ObjSetVar2(interp, array, objv[objc - 1],
        Tcl_ObjPrintf("%d %d", graph->padY.side1, graph->padY.side2),
        TCL_GLOBAL_ONLY);
    return TCL_OK;
}

/*
 * GraphMethod_shadow --
 *
 * Process -shadow option.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphMethod_shadow(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    Tcl_Obj *array;
    Tcl_Object object;
    RbcGraph *graph;
    Tcl_Obj *value;
    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (graph =
            (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta)) == NULL
        || (value =
            TkoWidgetOptionGet(interp, object, objv[objc - 1])) == NULL) {
        return TCL_ERROR;
    }

    if((array = TkoWidgetOptionVar(object)) == NULL) {
        return TCL_ERROR;
    }
    if(RbcGraphOptionSetShadow(interp, object, value,
            &graph->titleTextStyle.shadow) != TCL_OK) {
        return TCL_ERROR;
    }
    if(graph->titleTextStyle.shadow.color != NULL) {
        Tcl_ObjSetVar2(interp, array, objv[objc - 1],
            Tcl_ObjPrintf("%s %d",
                Tk_NameOfColor(graph->titleTextStyle.shadow.color),
                graph->titleTextStyle.shadow.offset), TCL_GLOBAL_ONLY);
    } else {
        Tcl_ObjSetVar2(interp, array, objv[objc - 1], TkoObj.empty,
            TCL_GLOBAL_ONLY);
    }
    return TCL_OK;
}

/*
 * GraphMethod_tile --
 *
 *  Process -tile option.
 *
 * Results:
 *  TODO
 *
 * Side effects:
 *  TODO
 */
static int
GraphMethod_tile(
    ClientData clientData,
    Tcl_Interp * interp,
    Tcl_ObjectContext context,
    int objc,
    Tcl_Obj * const objv[])
{
    Tcl_Object object;
    RbcGraph *graph;
    Tcl_Obj *value;
    if((object = Tcl_ObjectContextObject(context)) == NULL
        || (graph =
            (RbcGraph *) Tcl_ObjectGetMetadata(object, &graphMeta)) == NULL
        || (value =
            TkoWidgetOptionGet(interp, object, objv[objc - 1])) == NULL) {
        return TCL_ERROR;
    }

    return (RbcGraphOptionSetTile(interp, object, value, &graph->tile));
}

/*
 * RbcEventuallyRedrawGraph --
 *
 *      Tells the Tk dispatcher to call the graph display routine at
 *      the next idle point.  This request is made only if the window
 *      is displayed and no other redraw request is pending.
 *
 * Results:
 *      None.
 *
 * Side effects:
 *      The window is eventually redisplayed.
 */
void
RbcEventuallyRedrawGraph(
    RbcGraph * graph)
{              /* Graph widget record */
    if(graph->win == NULL || *(graph->win) == NULL)
        return;
    if(!(graph->flags & RBC_REDRAW_PENDING)) {
        Tcl_DoWhenIdle(DisplayGraph, graph);
        graph->flags |= RBC_REDRAW_PENDING;
    }
}

/*
 * GraphEventProc --
 *
 *      This procedure is invoked by the Tk dispatcher for various
 *      events on graphs.
 *
 * Results:
 *      None.
 *
 * Side effects:
 *      When the window gets deleted, internal structures get
 *      cleaned up.  When it gets exposed, the graph is eventually
 *      redisplayed.
 */
static void
GraphEventProc(
    ClientData clientData,     /* Graph widget record */
    register XEvent * eventPtr)
{              /* Event which triggered call to routine */
    RbcGraph *graph = clientData;
    if(eventPtr->type == DestroyNotify || graph->win == NULL
        || *(graph->win) == NULL)
        return;

    if(eventPtr->type == Expose) {
        if(eventPtr->xexpose.count == 0) {
            graph->flags |= RBC_REDRAW_WORLD;
            RbcEventuallyRedrawGraph(graph);
        }
    } else if((eventPtr->type == FocusIn) || (eventPtr->type == FocusOut)) {
        if(eventPtr->xfocus.detail != NotifyInferior) {
            if(eventPtr->type == FocusIn) {
                graph->flags |= RBC_GRAPH_FOCUS;
            } else {
                graph->flags &= ~RBC_GRAPH_FOCUS;
            }
            graph->flags |= RBC_REDRAW_WORLD;
            RbcEventuallyRedrawGraph(graph);
        }
    } else if(eventPtr->type == ConfigureNotify) {
        graph->flags |= (RBC_MAP_WORLD | RBC_REDRAW_WORLD);
        RbcEventuallyRedrawGraph(graph);
    }
}

/*
 * TileChangedProc --
 *
 *      Rebuilds the designated GC with the new tile pixmap.
 *
 * Results:
 *      None.
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static void
TileChangedProc(
    ClientData clientData,
    RbcTile tile)
{              /* Not used. */
RbcGraph *graph = clientData;
    if(graph->win == NULL || *(graph->win) == NULL)
        return;

    graph->flags |= RBC_REDRAW_WORLD;
    RbcEventuallyRedrawGraph(graph);
}

/*
 * AdjustAxisPointers --
 *
 *      Sets the axis pointers according to whether the axis is
 *      inverted on not.  The axis sites are also reset.
 *
 * Results:
 *      None.
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static void
AdjustAxisPointers(
    RbcGraph * graph)
{              /* Graph widget record */
    if(graph->inverted) {
        graph->margins[RBC_MARGIN_LEFT].axes = graph->axisChain[0];
        graph->margins[RBC_MARGIN_BOTTOM].axes = graph->axisChain[1];
        graph->margins[RBC_MARGIN_RIGHT].axes = graph->axisChain[2];
        graph->margins[RBC_MARGIN_TOP].axes = graph->axisChain[3];
    } else {
        graph->margins[RBC_MARGIN_LEFT].axes = graph->axisChain[1];
        graph->margins[RBC_MARGIN_BOTTOM].axes = graph->axisChain[0];
        graph->margins[RBC_MARGIN_RIGHT].axes = graph->axisChain[3];
        graph->margins[RBC_MARGIN_TOP].axes = graph->axisChain[2];
    }
}

/*
 * PickEntry --
 *
 *      Find the closest point from the set of displayed elements,
 *      searching the display list from back to front.  That way, if
 *      the points from two different elements overlay each other exactly,
 *      the one that's on top (visible) is picked.
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static ClientData
PickEntry(
    ClientData clientData,
    int x,
    int y,
    ClientData * contextPtr)
{              /* Not used. */
    RbcGraph *graph = clientData;
    RbcChainLink *linkPtr;
    RbcElement *elemPtr;
    RbcMarker *markerPtr;
    RbcExtents2D exts;

    if(graph->flags & RBC_MAP_ALL) {
        /* Can't pick anything until the next
         * redraw occurs. */
        return NULL;
    }
    RbcGraphExtents(graph, &exts);

    if((x > exts.right) || (x < exts.left) || (y > exts.bottom)
        || (y < exts.top)) {
        /*
         * Sample coordinate is in one of the graph margins.  Can only
         * pick an axis.
         */
        return RbcNearestAxis(graph, x, y);
    }

    /*
     * From top-to-bottom check:
     *  1. markers drawn on top (-under false).
     *  2. elements using its display list back to front.
     *  3. markers drawn under element (-under true).
     */
    markerPtr = (RbcMarker *) RbcNearestMarker(graph, x, y, FALSE);
    if(markerPtr != NULL) {
        /* Found a marker (-under false). */
        return markerPtr;
    }
    {
    RbcClosestSearch search;

        search.along = RBC_SEARCH_BOTH;
        search.halo = graph->halo + 1;
        search.index = -1;
        search.x = x;
        search.y = y;
        search.dist = (double)(search.halo + 1);
        search.mode = RBC_SEARCH_AUTO;

        for(linkPtr = RbcChainLastLink(graph->elements.displayList);
            linkPtr != NULL; linkPtr = RbcChainPrevLink(linkPtr)) {
            elemPtr = RbcChainGetValue(linkPtr);
            if((elemPtr->flags & RBC_MAP_ITEM)
                || (RbcVectorNotifyPending(elemPtr->x.clientId))
                || (RbcVectorNotifyPending(elemPtr->y.clientId))) {
                continue;
            }
            if((!elemPtr->hidden) && (elemPtr->state == RBC_STATE_NORMAL)) {
                (*elemPtr->procsPtr->closestProc) (graph, elemPtr, &search);
            }
        }
        if(search.dist <= (double)search.halo) {
            /* Found an element within the
             * minimum halo distance. */
            return search.elemPtr;
        }
    }
    markerPtr = (RbcMarker *) RbcNearestMarker(graph, x, y, TRUE);
    if(markerPtr != NULL) {
        /* Found a marker (-under true) */
        return markerPtr;
    }
    /* Nothing found. */
    return NULL;
}

/* Widget sub-commands */

/*
 * XAxisOp --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
XAxisOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv)
{
    int margin;

    margin = (graph->inverted) ? RBC_MARGIN_LEFT : RBC_MARGIN_BOTTOM;
    return RbcAxisOp(graph, margin, argc, argv);
}

/*
 * X2AxisOp --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
X2AxisOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv)
{
    int margin;

    margin = (graph->inverted) ? RBC_MARGIN_RIGHT : RBC_MARGIN_TOP;
    return RbcAxisOp(graph, margin, argc, argv);
}

/*
 * YAxisOp --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
YAxisOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv)
{
    int margin;

    margin = (graph->inverted) ? RBC_MARGIN_BOTTOM : RBC_MARGIN_LEFT;
    return RbcAxisOp(graph, margin, argc, argv);
}

/*
 * Y2AxisOp --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
Y2AxisOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv)
{
    int margin;

    margin = (graph->inverted) ? RBC_MARGIN_TOP : RBC_MARGIN_RIGHT;
    return RbcAxisOp(graph, margin, argc, argv);
}

/*
 * BarOp --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
BarOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv)
{
    return RbcElementOp(graph, interp, argc, argv, rbcBarElementUid);
}

/*
 * LineOp --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
LineOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv)
{
    return RbcElementOp(graph, interp, argc, argv, rbcLineElementUid);
}

/*
 * ElementOp --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
ElementOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,
    const char **argv)
{
    return RbcElementOp(graph, interp, argc, argv, graph->classUid);
}

/*
 * ExtentsOp --
 *
 *      Reports the size of one of several items within the graph.
 *      The following are valid items:
 *
 *        "bottommargin"    Height of the bottom margin
 *        "leftmargin"      Width of the left margin
 *        "legend"          x y w h of the legend
 *        "plotarea"        x y w h of the plotarea
 *        "plotheight"      Height of the plot area
 *        "rightmargin"     Width of the right margin
 *        "topmargin"       Height of the top margin
 *        "plotwidth"       Width of the plot area
 *
 * Results:
 *      Always returns TCL_OK.
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
ExtentsOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,                  /* Not used. */
    const char **argv)
{
    char c;
    unsigned int length;
    char string[200];

    c = argv[2][0];
    length = strlen(argv[2]);
    if((c == 'p') && (length > 4)
        && (strncmp("plotheight", argv[2], length) == 0)) {
        Tcl_SetObjResult(interp, Tcl_NewIntObj(graph->bottom - graph->top + 1));
    } else if((c == 'p') && (length > 4)
        && (strncmp("plotwidth", argv[2], length) == 0)) {
        Tcl_SetObjResult(interp, Tcl_NewIntObj(graph->right - graph->left + 1));
    } else if((c == 'p') && (length > 4)
        && (strncmp("plotarea", argv[2], length) == 0)) {
        sprintf(string, "%d %d %d %d", graph->left, graph->top,
            graph->right - graph->left + 1, graph->bottom - graph->top + 1);
        Tcl_SetObjResult(interp, Tcl_NewStringObj(string, -1));
    } else if((c == 'l') && (length > 2)
        && (strncmp("legend", argv[2], length) == 0)) {
        sprintf(string, "%d %d %d %d", RbcLegendX(graph->legend),
            RbcLegendY(graph->legend), RbcLegendWidth(graph->legend),
            RbcLegendHeight(graph->legend));
        Tcl_SetObjResult(interp, Tcl_NewStringObj(string, -1));
    } else if((c == 'l') && (length > 2)
        && (strncmp("leftmargin", argv[2], length) == 0)) {
        Tcl_SetObjResult(interp,
            Tcl_NewIntObj(graph->margins[RBC_MARGIN_LEFT].width));
    } else if((c == 'r') && (length > 1)
        && (strncmp("rightmargin", argv[2], length) == 0)) {
        Tcl_SetObjResult(interp,
            Tcl_NewIntObj(graph->margins[RBC_MARGIN_RIGHT].width));
    } else if((c == 't') && (length > 1)
        && (strncmp("topmargin", argv[2], length) == 0)) {
        Tcl_SetObjResult(interp,
            Tcl_NewIntObj(graph->margins[RBC_MARGIN_TOP].height));
    } else if((c == 'b') && (length > 1)
        && (strncmp("bottommargin", argv[2], length) == 0)) {
        Tcl_SetObjResult(interp,
            Tcl_NewIntObj(graph->margins[RBC_MARGIN_BOTTOM].height));
    } else {
        Tcl_AppendResult(interp, "bad extent item \"", argv[2],
            "\": should be plotheight, plotwidth, leftmargin, rightmargin, \
topmargin, bottommargin, plotarea, or legend", (char *)NULL);
        return TCL_ERROR;
    }
    return TCL_OK;
}

/*
 * InsideOp --
 *
 *      Returns true of false whether the given point is inside
 *      the plotting area (defined by left,bottom right, top).
 *
 * Results:
 *      Always returns TCL_OK.  interp->result will contain
 *      the boolean string representation.
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
InsideOp(
    RbcGraph * graph,
    Tcl_Interp * interp,
    int argc,                  /* Not used. */
    const char **argv)
{
    int x, y;
    RbcExtents2D exts;
    int result;
    if(graph->win == NULL || *(graph->win) == NULL)
        return TCL_ERROR;

    if(Tk_GetPixels(interp, *(graph->win), argv[2], &x) != TCL_OK) {
        return TCL_ERROR;
    }
    if(Tk_GetPixels(interp, *(graph->win), argv[3], &y) != TCL_OK) {
        return TCL_ERROR;
    }
    RbcGraphExtents(graph, &exts);
    result = RbcPointInRegion(&exts, x, y);
    Tcl_SetObjResult(interp, Tcl_NewBooleanObj(result));
    return TCL_OK;
}

/*
 * InvtransformOp --
 *
 *      This procedure returns a list of the graph coordinate
 *      values corresponding with the given window X and Y
 *      coordinate positions.
 *
 * Results:
 *      Returns a standard Tcl result.  If an error occurred while
 *      parsing the window positions, TCL_ERROR is returned, and
 *      interp->result will contain the error message.  Otherwise
 *      interp->result will contain a Tcl list of the x and y
 *      coordinates.
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
InvtransformOp(
    RbcGraph * graph,          /* Graph widget record */
    Tcl_Interp * interp,
    int argc,                  /* Not used. */
    const char **argv)
{
    double x, y;
    RbcPoint2D point;
    RbcAxis2D axes;
    char stringDouble[TCL_DOUBLE_SPACE];

    if(Tcl_ExprDouble(interp, argv[2], &x) != TCL_OK ||
        Tcl_ExprDouble(interp, argv[3], &y) != TCL_OK) {
        return TCL_ERROR;
    }
    if(graph->flags & RBC_RESET_AXES) {
        RbcResetAxes(graph);
    }
    /* Perform the reverse transformation, converting from window
     * coordinates to graph data coordinates.  Note that the point is
     * always mapped to the bottom and left axes (which may not be
     * what the user wants).  */

    /*  Pick the first pair of axes */
    axes.x = RbcGetFirstAxis(graph->axisChain[0]);
    axes.y = RbcGetFirstAxis(graph->axisChain[1]);
    point = RbcInvMap2D(graph, x, y, &axes);

    Tcl_PrintDouble(NULL, point.x, stringDouble);
    Tcl_AppendElement(interp, stringDouble);
    Tcl_PrintDouble(NULL, point.y, stringDouble);
    Tcl_AppendElement(interp, stringDouble);
    return TCL_OK;
}

/*
 * TransformOp --
 *
 *      This procedure returns a list of the window coordinates
 *      corresponding with the given graph x and y coordinates.
 *
 * Results:
 *      Returns a standard Tcl result.  interp->result contains
 *      the list of the graph coordinates. If an error occurred
 *      while parsing the window positions, TCL_ERROR is returned,
 *      then interp->result will contain an error message.
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
TransformOp(
    RbcGraph * graph,          /* Graph widget record */
    Tcl_Interp * interp,
    int argc,                  /* Not used. */
    const char **argv)
{
    double x, y;
    RbcPoint2D point;
    RbcAxis2D axes;

    if((Tcl_ExprDouble(interp, argv[2], &x) != TCL_OK) ||
        (Tcl_ExprDouble(interp, argv[3], &y) != TCL_OK)) {
        return TCL_ERROR;
    }
    if(graph->flags & RBC_RESET_AXES) {
        RbcResetAxes(graph);
    }
    /*
     * Perform the transformation from window to graph coordinates.
     * Note that the points are always mapped onto the bottom and left
     * axes (which may not be the what the user wants).
     */
    axes.x = RbcGetFirstAxis(graph->axisChain[0]);
    axes.y = RbcGetFirstAxis(graph->axisChain[1]);

    point = RbcMap2D(graph, x, y, &axes);
    Tcl_AppendPrintfToObj(Tcl_GetObjResult(interp),
        "%d %d", ROUND(point.x), ROUND(point.y));
    return TCL_OK;
}

/*
 * StringToFormat --
 *
 *      Convert a string represent a node number into its integer
 *      value.
 *
 * Results:
 *      The return value is a standard Tcl result.
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
StringToFormat(
    ClientData clientData,     /* Contains a pointer to the tabset containing
                                * this image. */
    Tcl_Interp * interp,       /* Interpreter to send results back to */
    char *switchName,          /* Not used. */
    char *string,              /* String representation */
    char *record,              /* Structure record */
    int offset)
{              /* Offset to field in structure */
    int *formatPtr = (int *)(record + offset);
    char c;

    c = string[0];
    if((c == 'p') && (strcmp(string, "photo") == 0)) {
        *formatPtr = FORMAT_PHOTO;
#ifdef _WIN32
    } else if((c == 'e') && (strcmp(string, "emf") == 0)) {
        *formatPtr = FORMAT_EMF;
    } else if((c == 'w') && (strcmp(string, "wmf") == 0)) {
        *formatPtr = FORMAT_WMF;
#endif /* _WIN32 */
    } else {
#ifdef _WIN32
        Tcl_AppendResult(interp, "bad format \"", string,
            "\": should be photo, emf, or wmf.", (char *)NULL);
#else
        Tcl_AppendResult(interp, "bad format \"", string,
            "\": should be photo.", (char *)NULL);
#endif /* _WIN32 */
        return TCL_ERROR;
    }
    return TCL_OK;
}

#ifdef _WIN32

/*
 * InitMetaFileHeader --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
InitMetaFileHeader(
    Tk_Window tkwin,
    int width,
    int height,
    APMHEADER * mfhPtr)
{
    unsigned int *p;
    unsigned int sum;
    Screen *screen;
#define MM_INCH		25.4
    double dpiX, dpiY;

    mfhPtr->key = 0x9ac6cdd7L;
    mfhPtr->hmf = 0;
    mfhPtr->inch = 1440;

    screen = Tk_Screen(tkwin);
    dpiX = (WidthOfScreen(screen) * MM_INCH) / WidthMMOfScreen(screen);
    dpiY = (HeightOfScreen(screen) * MM_INCH) / HeightMMOfScreen(screen);

    mfhPtr->bbox.Left = mfhPtr->bbox.Top = 0;
    mfhPtr->bbox.Bottom = (SHORT) ((width * 1440) / dpiX);
    mfhPtr->bbox.Right = (SHORT) ((height * 1440) / dpiY);
    mfhPtr->reserved = 0;
    sum = 0;
    for(p = (unsigned int *)mfhPtr;
        p < (unsigned int *)&(mfhPtr->checksum); p++) {
        sum ^= *p;
    }
    mfhPtr->checksum = sum;
    return TCL_OK;
}

/*
 * CreateAPMetaFile --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
CreateAPMetaFile(
    Tcl_Interp * interp,
    HANDLE hMetaFile,
    HDC hDC,
    APMHEADER * mfhPtr,
    char *fileName)
{
    HANDLE hFile;
    HANDLE hMem;
    LPVOID buffer;
    int result;
    DWORD count, nBytes;

    result = TCL_ERROR;
    hMem = NULL;
    hFile = CreateFile((LPCWSTR) fileName,      /* File path */
        GENERIC_WRITE,  /* Access mode */
        0,     /* No sharing. */
        NULL,  /* Security attributes */
        CREATE_ALWAYS,  /* Overwrite any existing file */
        FILE_ATTRIBUTE_NORMAL, NULL);   /* No template file */
    if(hFile == INVALID_HANDLE_VALUE) {
        Tcl_AppendResult(interp, "can't create metafile \"", fileName,
            "\":", RbcLastError(), (char *)NULL);
        return TCL_ERROR;
    }
    if((!WriteFile(hFile, (LPVOID) mfhPtr, sizeof(APMHEADER), &count,
                NULL)) || (count != sizeof(APMHEADER))) {
        Tcl_AppendResult(interp, "can't create metafile header to \"",
            fileName, "\":", RbcLastError(), (char *)NULL);
        goto error;
    }
    nBytes = GetWinMetaFileBits(hMetaFile, 0, NULL, MM_ANISOTROPIC, hDC);
    hMem = GlobalAlloc(GHND, nBytes);
    if(hMem == NULL) {
        Tcl_AppendResult(interp, "can't create allocate global memory:",
            RbcLastError(), (char *)NULL);
        goto error;
    }
    buffer = (LPVOID) GlobalLock(hMem);
    if(!GetWinMetaFileBits(hMetaFile, nBytes, buffer, MM_ANISOTROPIC, hDC)) {
        Tcl_AppendResult(interp, "can't get metafile bits:",
            RbcLastError(), (char *)NULL);
        goto error;
    }
    if((!WriteFile(hFile, buffer, nBytes, &count, NULL)) || (count != nBytes)) {
        Tcl_AppendResult(interp, "can't write metafile bits:",
            RbcLastError(), (char *)NULL);
        goto error;
    }
    result = TCL_OK;
  error:
    CloseHandle(hFile);
    if(hMem != NULL) {
        GlobalUnlock(hMem);
        GlobalFree(hMem);
    }
    return result;
}

#endif /*_WIN32*/

/*
 * SnapOp --
 *
 *      Snaps a picture of the graph and stores it in the specified image
 *
 * Results:
 *      Returns a standard Tcl result.  interp->result contains
 *      the list of the graph coordinates. If an error occurred
 *      while parsing the window positions, TCL_ERROR is returned,
 *      then interp->result will contain an error message.
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static int
SnapOp(
    RbcGraph * graph,          /* Graph widget record */
    Tcl_Interp * interp,
    int argc,                  /* Not used. */
    const char **argv)
{
    int result;
    Pixmap drawable;
    int noBackingStore = 0;
    register int i;
    SnapData data;
    if(graph->win == NULL || *(graph->win) == NULL)
        return TCL_ERROR;

    /* .g snap ?switches? name */
    data.height = Tk_Height(*(graph->win));
    data.width = Tk_Width(*(graph->win));
    data.format = FORMAT_PHOTO;
    /* Process switches  */
    i = RbcProcessSwitches(interp, snapSwitches, argc - 2, argv + 2,
        (char *)&data, RBC_SWITCH_OBJV_PARTIAL);
    if(i < 0) {
        return TCL_ERROR;
    }
    i += 2;
    if(i >= argc) {
        Tcl_AppendResult(interp, "missing name argument: should be \"",
            argv[0], "snap ?switches? name\"", (char *)NULL);
        return TCL_ERROR;
    }
    data.name = (char *)argv[i];
    if(data.width < 2) {
        data.width = 400;
    }
    if(data.height < 2) {
        data.height = 400;
    }
    /* Always re-compute the layout of the graph before snapping the photo. */
    graph->width = data.width;
    graph->height = data.height;
    RbcLayoutGraph(graph);

    drawable = Tk_WindowId(*(graph->win));
    if(data.format == FORMAT_PHOTO) {
        drawable = Tk_GetPixmap(graph->display, drawable, graph->width,
            graph->height, Tk_Depth(*(graph->win)));
#ifdef _WIN32
        assert(drawable != None);
#endif
        graph->flags |= RBC_RESET_WORLD;
        RbcDrawGraph(graph, drawable, noBackingStore);
        result = RbcSnapPhoto(interp, *(graph->win), drawable, 0, 0,
            data.width, data.height, data.width, data.height, data.name, 1.0);
        Tk_FreePixmap(graph->display, drawable);
#ifdef _WIN32
    } else if((data.format == FORMAT_WMF) || (data.format == FORMAT_EMF)) {
    TkWinDC drawableDC;
    TkWinDCState state;
    HDC hRefDC, hDC;
    HENHMETAFILE hMetaFile;
    Tcl_DString dString;
    char *title;

        hRefDC = TkWinGetDrawableDC(graph->display, drawable, &state);

        Tcl_DStringInit(&dString);
        Tcl_DStringAppend(&dString, "::graph ", -1);
        Tcl_DStringAppend(&dString, "\0", -1);
        Tcl_DStringAppend(&dString, Tk_PathName(*(graph->win)), -1);
        Tcl_DStringAppend(&dString, "\0", -1);
        title = Tcl_DStringValue(&dString);
        hDC = CreateEnhMetaFile(hRefDC, NULL, NULL, (LPCWSTR) title);
        Tcl_DStringFree(&dString);

        if(hDC == NULL) {
            Tcl_AppendResult(interp, "can't create metafile: ",
                RbcLastError(), (char *)NULL);
            return TCL_ERROR;
        }

        drawableDC.hdc = hDC;
        drawableDC.type = TWD_WINDC;

        RbcLayoutGraph(graph);
        graph->flags |= RBC_RESET_WORLD;
        RbcDrawGraph(graph, (Drawable) & drawableDC, FALSE);

        hMetaFile = CloseEnhMetaFile(hDC);
        if(strcmp(data.name, "CLIPBOARD") == 0) {
    HWND hWnd;

            hWnd = Tk_GetHWND(drawable);
            OpenClipboard(hWnd);
            EmptyClipboard();
            SetClipboardData(CF_ENHMETAFILE, hMetaFile);
            CloseClipboard();
            result = TCL_OK;
        } else {
            result = TCL_ERROR;
            if(data.format == FORMAT_WMF) {
    APMHEADER mfh;

                assert(sizeof(mfh) == 22);
                InitMetaFileHeader(*(graph->win), data.width, data.height,
                    &mfh);
                result = CreateAPMetaFile(interp, hMetaFile, hRefDC, &mfh,
                    data.name);
            } else {
    HENHMETAFILE hMetaFile2;

                hMetaFile2 = CopyEnhMetaFile(hMetaFile, (LPCWSTR) data.name);
                if(hMetaFile2 != NULL) {
                    result = TCL_OK;
                    DeleteEnhMetaFile(hMetaFile2);
                }
            }
            DeleteEnhMetaFile(hMetaFile);
        }
        TkWinReleaseDrawableDC(drawable, hRefDC, &state);

#endif /*_WIN32*/
    } else {
        Tcl_AppendResult(interp, "bad snapshot format", (char *)NULL);
        return TCL_ERROR;
    }
    graph->flags = RBC_MAP_WORLD;
    RbcEventuallyRedrawGraph(graph);
    return result;
}

static RbcOpSpec graphOps[] = {
    {"axis", 1, (RbcOp) RbcVirtualAxisOp, 2, 0, "oper ?args?",},
    {"bar", 2, (RbcOp) BarOp, 2, 0, "oper ?args?",},
    {"crosshairs", 2, (RbcOp) RbcCrosshairsOp, 2, 0, "oper ?args?",},
    {"element", 2, (RbcOp) ElementOp, 2, 0, "oper ?args?",},
    {"extents", 2, (RbcOp) ExtentsOp, 3, 3, "item",},
    {"grid", 1, (RbcOp) RbcGridOp, 2, 0, "oper ?args?",},
    {"inside", 3, (RbcOp) InsideOp, 4, 4, "winX winY",},
    {"invtransform", 3, (RbcOp) InvtransformOp, 4, 4, "winX winY",},
    {"legend", 2, (RbcOp) RbcLegendOp, 2, 0, "oper ?args?",},
    {"line", 2, (RbcOp) LineOp, 2, 0, "oper ?args?",},
    {"marker", 2, (RbcOp) RbcMarkerOp, 2, 0, "oper ?args?",},
    {"pen", 2, (RbcOp) RbcPenOp, 2, 0, "oper ?args?",},
    {"postscript", 2, (RbcOp) RbcPostScriptOp, 2, 0, "oper ?args?",},
    {"snap", 1, (RbcOp) SnapOp, 3, 0, "?switches? name",},
    {"transform", 1, (RbcOp) TransformOp, 4, 4, "x y",},
    {"x2axis", 2, (RbcOp) X2AxisOp, 2, 0, "oper ?args?",},
    {"xaxis", 2, (RbcOp) XAxisOp, 2, 0, "oper ?args?",},
    {"y2axis", 2, (RbcOp) Y2AxisOp, 2, 0, "oper ?args?",},
    {"yaxis", 2, (RbcOp) YAxisOp, 2, 0, "oper ?args?",},
};

static int nGraphOps = sizeof(graphOps) / sizeof(RbcOpSpec);

/*
 * RbcGraphInstCmdProc --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
int
RbcGraphInstCmdProc(
    ClientData clientData,
    Tcl_Interp * interp,
    int argc,
    const char *argv[])
{
    RbcOp proc;
    int result;
    RbcGraph *graph = clientData;

    proc = RbcGetOp(interp, nGraphOps, graphOps, RBC_OP_ARG1, argc, argv, 0);
    if(proc == NULL) {
        return TCL_ERROR;
    }
    Tcl_Preserve(graph);
    result = (*proc) (graph, interp, argc, argv);
    Tcl_Release(graph);
    return result;
}

/*
 * DrawMargins --
 *
 *      Draws the exterior region of the graph (axes, ticks, titles, etc)
 *      onto a pixmap. The interior region is defined by the given
 *      rectangle structure.
 *
 *      ---------------------------------
 *          |                               |
 *          |           rectArr[0]          |
 *          |                               |
 *      ---------------------------------
 *          |     |top           right|     |
 *          |     |                   |     |
 *          |     |                   |     |
 *          | [1] |                   | [2] |
 *          |     |                   |     |
 *          |     |                   |     |
 *          |     |                   |     |
 *          |     |                   |     |
 *          |     |                   |     |
 *          |     |left         bottom|     |
 *      ---------------------------------
 *          |                               |
 *          |          rectArr[3]           |
 *          |                               |
 *      ---------------------------------
 *
 *          X coordinate axis
 *          Y coordinate axis
 *          legend
 *          interior border
 *          exterior border
 *          titles (X and Y axis, graph)
 *
 * Returns:
 *      None.
 *
 * Side Effects:
 *      Exterior of graph is displayed in its window.
 */
static void
DrawMargins(
    RbcGraph * graph,
    Drawable drawable /* Pixmap or window to draw into */)
{             
    XRectangle rects[4];

    if(graph->win == NULL || *(graph->win) == NULL)
        return;
    /*
     * Draw the four outer rectangles which encompass the plotting
     * surface. This clears the surrounding area and clips the plot.
     */
    rects[0].x = rects[0].y = rects[3].x = rects[1].x = 0;
    rects[0].width = rects[3].width = (short int)graph->width;
    rects[0].height = (short int)graph->top;
    rects[3].y = graph->bottom;
    rects[3].height = graph->height - graph->bottom;
    rects[2].y = rects[1].y = graph->top;
    rects[1].width = graph->left;
    rects[2].height = rects[1].height = graph->bottom - graph->top;
    rects[2].x = graph->right;
    rects[2].width = graph->width - graph->right;

    if(graph->tile != NULL) {
        RbcSetTileOrigin(*(graph->win), graph->tile, 0, 0);
        RbcTileRectangles(*(graph->win), drawable, graph->tile, rects, 4);
    } else {
        XFillRectangles(graph->display, drawable, graph->fillGC, rects, 4);
    }

    /* Draw 3D border around the plotting area */

    if(graph->plotBorderWidth > 0) {
        int x, y, width, height;

        x = graph->left - graph->plotBorderWidth;
        y = graph->top - graph->plotBorderWidth;
        width = (graph->right - graph->left) + (2 * graph->plotBorderWidth);
        height = (graph->bottom - graph->top) + (2 * graph->plotBorderWidth);
        Tk_Draw3DRectangle(*(graph->win), drawable, graph->border, x, y,
            width, height, graph->plotBorderWidth, graph->plotRelief);
    }
    if(RbcLegendSite(graph->legend) & RBC_LEGEND_IN_MARGIN) {
        /* Legend is drawn on one of the graph margins */
        RbcDrawLegend(graph->legend, drawable);
    }
    if(graph->title != NULL) {
        RbcDrawText(*(graph->win), drawable, graph->title,
            &graph->titleTextStyle, graph->titleX, graph->titleY);
    }
    RbcDrawAxes(graph, drawable);

}

/*
 * DrawPlotRegion --
 *
 *      Draws the contents of the plotting area.  This consists of
 *      the elements, markers (draw under elements), axis limits,
 *      grid lines, and possibly the legend.  Typically, the output
 *      will be cached into a backing store pixmap, so that redraws
 *      can occur quickly.
 *
 * Results:
 *      None.
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static void
DrawPlotRegion(
    RbcGraph * graph,
    Drawable drawable)
{              /* Pixmap or window to draw into */
    /* Clear the background of the plotting area. */
    XFillRectangle(graph->display, drawable, graph->plotFillGC,
        graph->left, graph->top, graph->right - graph->left + 1,
        graph->bottom - graph->top + 1);

    /* Draw the elements, markers, legend, and axis limits. */

    if(!graph->gridPtr->hidden) {
        RbcDrawGrid(graph, drawable);
    }
    RbcDrawMarkers(graph, drawable, RBC_MARKER_UNDER);
    if((RbcLegendSite(graph->legend) & RBC_LEGEND_IN_PLOT) &&
        (!RbcLegendIsRaised(graph->legend))) {
        RbcDrawLegend(graph->legend, drawable);
    }
    RbcDrawAxisLimits(graph, drawable);
    RbcDrawElements(graph, drawable);
}

/*
 * RbcLayoutGraph --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
void
RbcLayoutGraph(
    RbcGraph * graph)
{
    if(graph->flags & RBC_RESET_AXES) {
        RbcResetAxes(graph);
    }
    if(graph->flags & RBC_LAYOUT_NEEDED) {
        RbcLayoutMargins(graph);
        graph->flags &= ~RBC_LAYOUT_NEEDED;
    }
    /* Compute coordinate transformations for graph components */
    if((graph->vRange > 1) && (graph->hRange > 1)) {
        if(graph->flags & RBC_MAP_WORLD) {
            RbcMapAxes(graph);
        }
        RbcMapElements(graph);
        RbcMapMarkers(graph);
        RbcMapGrid(graph);
        graph->flags &= ~(RBC_MAP_ALL);
    }
}

/*
 * RbcDrawGraph --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
void
RbcDrawGraph(
    RbcGraph * graph,
    Drawable drawable,         /* Pixmap or window to draw into */
    int backingStore)
{              /* If non-zero, use backing store for
                * plotting area. */
    if(graph->win == NULL || *(graph->win) == NULL)
        return;
    if(backingStore) {
        /*
         * Create another pixmap to save elements if one doesn't
         * already exist or the size of the window has changed.
         */
        if((graph->backPixmap == None) ||
            (graph->backWidth != graph->width) ||
            (graph->backHeight != graph->height)) {

            if(graph->backPixmap != None) {
                Tk_FreePixmap(graph->display, graph->backPixmap);
            }
            graph->backPixmap = Tk_GetPixmap(graph->display,
                Tk_WindowId(*(graph->win)), graph->width,
                graph->height, Tk_Depth(*(graph->win)));
            graph->backWidth = graph->width;
            graph->backHeight = graph->height;
            graph->flags |= RBC_REDRAW_BACKING_STORE;
        }
        if(graph->flags & RBC_REDRAW_BACKING_STORE) {
            /* The backing store is new or out-of-date. */
            DrawPlotRegion(graph, graph->backPixmap);
            graph->flags &= ~RBC_REDRAW_BACKING_STORE;
        }

        /* Copy the pixmap to the one used for drawing the entire graph. */

        XCopyArea(graph->display, graph->backPixmap, drawable,
            graph->drawGC, graph->left, graph->top,
            (graph->right - graph->left + 1),
            (graph->bottom - graph->top + 1), graph->left, graph->top);
    } else {
        DrawPlotRegion(graph, drawable);
    }

    /* Draw markers above elements */
    RbcDrawMarkers(graph, drawable, RBC_MARKER_ABOVE);
    RbcDrawActiveElements(graph, drawable);

    if(graph->flags & RBC_DRAW_MARGINS) {
        DrawMargins(graph, drawable);
    }
    if((RbcLegendSite(graph->legend) & RBC_LEGEND_IN_PLOT) &&
        (RbcLegendIsRaised(graph->legend))) {
        RbcDrawLegend(graph->legend, drawable);
    }
    /* Draw 3D border just inside of the focus highlight ring. */
    if((graph->borderWidth > 0) && (graph->relief != TK_RELIEF_FLAT)) {
        Tk_Draw3DRectangle(*(graph->win), drawable, graph->border,
            graph->highlightWidth, graph->highlightWidth,
            graph->width - 2 * graph->highlightWidth,
            graph->height - 2 * graph->highlightWidth,
            graph->borderWidth, graph->relief);
    }
    /* Draw focus highlight ring. */
    if((graph->highlightWidth > 0) && (graph->flags & RBC_GRAPH_FOCUS)) {
    GC  gc;

        gc = Tk_GCForColor(graph->highlightColor, drawable);
        Tk_DrawFocusHighlight(*(graph->win), gc, graph->highlightWidth,
            drawable);
    }
}

/*
 * UpdateMarginTraces --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
static void
UpdateMarginTraces(
    RbcGraph * graph)
{
    RbcMargin *marginPtr;
    int size;
    register int i;

    for(i = 0; i < 4; i++) {
        marginPtr = graph->margins + i;
        if(marginPtr->varName != NULL) {        /* Trigger variable traces */
            if((marginPtr->site == RBC_MARGIN_LEFT) ||
                (marginPtr->site == RBC_MARGIN_RIGHT)) {
                size = marginPtr->width;
            } else {
                size = marginPtr->height;
            }
            Tcl_SetVar2Ex(graph->interp, marginPtr->varName, NULL,
                Tcl_NewIntObj(size), TCL_GLOBAL_ONLY);
        }
    }
}

/*
 * DisplayGraph --
 *
 *      This procedure is invoked to display a graph widget.
 *
 * Results:
 *      None.
 *
 * Side effects:
 *      Commands are output to X to display the graph in its
 *      current mode.
 */
static void
DisplayGraph(
    ClientData clientData)
{
    RbcGraph *graph = clientData;
    Pixmap drawable;
    graph->flags &= ~RBC_REDRAW_PENDING;
    if(graph->win == NULL || *(graph->win) == NULL)
        return;

    if(RbcGraphUpdateNeeded(graph)) {
        /*
         * One of the elements of the graph has a vector notification
         * pending.  This means that the vector will eventually notify
         * the graph that its data has changed.  Since the graph uses
         * the actual vector (not a copy) we need to keep in-sync.
         * Therefore don't draw right now but wait until we've been
         * notified before redrawing.
         */
        return;
    }
    graph->width = Tk_Width(*(graph->win));
    graph->height = Tk_Height(*(graph->win));
    RbcLayoutGraph(graph);
    RbcUpdateCrosshairs(graph);
    if(!Tk_IsMapped(*(graph->win))) {
        /* The graph's window isn't displayed, so don't bother
         * drawing anything.  By getting this far, we've at least
         * computed the coordinates of the graph's new layout.  */
        return;
    }

    /* Disable crosshairs before redisplaying to the screen */
    RbcDisableCrosshairs(graph);
    /*
     * Create a pixmap the size of the window for double buffering.
     */
    if(graph->doubleBuffer) {
        drawable = Tk_GetPixmap(graph->display, Tk_WindowId(*(graph->win)),
            graph->width, graph->height, Tk_Depth(*(graph->win)));
    } else {
        drawable = Tk_WindowId(*(graph->win));
    }
#ifdef _WIN32
    assert(drawable != None);
#endif
    RbcDrawGraph(graph, drawable, graph->backingStore && graph->doubleBuffer);
    if(graph->flags & RBC_DRAW_MARGINS) {
        XCopyArea(graph->display, drawable, Tk_WindowId(*(graph->win)),
            graph->drawGC, 0, 0, graph->width, graph->height, 0, 0);
    } else {
        XCopyArea(graph->display, drawable, Tk_WindowId(*(graph->win)),
            graph->drawGC, graph->left, graph->top,
            (graph->right - graph->left + 1),
            (graph->bottom - graph->top + 1), graph->left, graph->top);
    }
    if(graph->doubleBuffer) {
        Tk_FreePixmap(graph->display, drawable);
    }
    RbcEnableCrosshairs(graph);
    graph->flags &= ~RBC_RESET_WORLD;
    UpdateMarginTraces(graph);
}

/*
 * RbcGetGraphFromWindowData --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
RbcGraph *
RbcGetGraphFromWindowData(
    Tk_Window tkwin)
{
RbcGraph *graph;

    while(tkwin != NULL) {
        graph = (RbcGraph *) RbcGetWindowInstanceData(tkwin);
        if(graph != NULL) {
            return graph;
        }
        tkwin = Tk_Parent(tkwin);
    }
    return NULL;
}

/*
 * RbcGraphType --
 *
 *      TODO: Description
 *
 * Results:
 *      TODO: Results
 *
 * Side Effects:
 *      TODO: Side Effects
 */
int
RbcGraphType(
    RbcGraph * graph)
{
    if(graph->classUid == rbcLineElementUid) {
        return RBC_GRAPH;
    } else if(graph->classUid == rbcBarElementUid) {
        return RBC_BARCHART;
    } else if(graph->classUid == rbcStripElementUid) {
        return RBC_STRIPCHART;
    }
    return 0;
}

/* vim: set ts=4 sw=4 sts=4 ff=unix et : */