home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / lisp / stk-3.0 / stk-3 / blt-for-STk-3.0 / blt-1.9 / man / graph.man < prev    next >
Encoding:
Text File  |  1995-07-01  |  54.1 KB  |  1,346 lines
  1. '\"
  2. '\" Copyright 1991-1994 by AT&T Bell Laboratories.
  3. '\"
  4. '\" Permission to use, copy, modify, and distribute this software
  5. '\" and its documentation for any purpose and without fee is hereby
  6. '\" granted, provided that the above copyright notice appear in all
  7. '\" copies and that both that the copyright notice and warranty
  8. '\" disclaimer appear in supporting documentation, and that the
  9. '\" names of AT&T Bell Laboratories any of their entities not be used
  10. '\" in advertising or publicity pertaining to distribution of the
  11. '\" software without specific, written prior permission.
  12. '\"
  13. '\" AT&T disclaims all warranties with regard to this software, including
  14. '\" all implied warranties of merchantability and fitness.  In no event
  15. '\" shall AT&T be liable for any special, indirect or consequential
  16. '\" damages or any damages whatsoever resulting from loss of use, data
  17. '\" or profits, whether in an action of contract, negligence or other
  18. '\" tortuous action, arising out of or in connection with the use or
  19. '\" performance of this software.
  20. '\"
  21. '\" Graph widget created by Sani Nassif and George Howlett.
  22. '\"
  23. .so man.macros
  24. .HS blt_graph cmds
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. blt_graph \- Create and manipulate graph widgets
  29. .SH SYNOPSIS
  30. \fBblt_graph\fI \fIpathName \fR?\fIoptions\fR?
  31. .SH "STANDARD OPTIONS"
  32. .LP
  33. .nf
  34. .ta 4c 8c 12c
  35. \fBbackground\fR    \fBcursor\fR    \fBforeground\fR        
  36. \fBborderWidth\fR    \fBfont\fR    \fBrelief\fR            
  37. .fi
  38. .LP
  39. See the ``options'' manual entry for details on the standard options.
  40. .ta 4c
  41. .SH "WIDGET-SPECIFIC OPTIONS"
  42. .LP
  43. .nf
  44. .ta 4c 8c 12c
  45. \fBbottomMargin\fR    \fBleftMargin\fR    \fBtitle\fR     
  46. \fBbufferElements\fR    \fBplotBackground\fR    \fBtopMargin\fR 
  47. \fBhalo\fR    \fBplotBorderWidth\fR    \fBwidth\fR     
  48. \fBheight\fR    \fBplotRelief\fR        
  49. \fBinvertxy\fR    \fBrightMargin\fR       
  50. .fi
  51. .BE
  52. .SH DESCRIPTION
  53. .PP
  54. The \fBblt_graph\fR command creates a new window (given by the 
  55. \fIpathName\fR argument) and makes it into an graph widget.
  56. Additional
  57. options, described above, may be specified on the command line
  58. or in the option database
  59. to configure aspects of the graph such as its colors and font.
  60. The \fBblt_graph\fR command returns its
  61. \fIpathName\fR argument.  At the time this command is invoked,
  62. there must not exist a window named \fIpathName\fR, but
  63. \fIpathName\fR's parent must exist.
  64. .PP
  65. The \fBblt_graph\fR widget plots two-variable data in a window.  
  66. It has of several components; coordinate axes, 
  67. crosshairs, a legend, and a collection of elements and tags.
  68. .SS "COORDINATE AXES"
  69. The graph widget has four axes, two standard (x and y) and two alternate
  70. (x2 and y2).  Graph elements and tags are mapped onto one x-axis and 
  71. y-axis (by default, they are mapped onto the standard axes).
  72. .PP
  73. Each axis consists of the axis line and major and minor 
  74. ticks placed at set intervals. At major ticks, labels (text strings) 
  75. representing the coordinate value of the tick are drawn.  
  76. By default, the tick labels are simply numeric strings.  However, 
  77. a Tcl procedure can be supplied to individually format each 
  78. tick label.
  79. .PP
  80. The scale of the axis is determined its minimum and maximum limits.
  81. By default, each axis is auto-scaled using the data limits.
  82. However either limit can be set to manually scale the graph.
  83. .SS "CROSSHAIRS"
  84. Crosshairs are a set of two lines (vertical and horizontal) which
  85. intersect on the graph.  They are implemented using XOR drawing
  86. primitives, so they do not require the graph to be redrawn when 
  87. they are moved or redisplayed.
  88. .SS "ELEMENTS"
  89. A graph element is a set of data points and configuration options 
  90. which determine how the data is displayed.  Elements are created 
  91. by the \fBelement create\fP widget command.  The configuration options may 
  92. be specified as the element is created or later by the \fBelement configure\fR 
  93. widget command.  There is an internal display list of element names which 
  94. controls the drawing order of the elements. By default, elements are 
  95. appended to the display list as they are created.  The element display list
  96. can be managed by the \fBelement show\fR command.  
  97. .SS "LEGEND"
  98. The legend consists of a list of entries, where each entry is an element
  99. symbol and label.  By default, the legend is located in the right
  100. margin of the graph.  However, the legend may appear anywhere in the
  101. plotting area of the graph by specifying its window coordinates.
  102. .SS "TAGS"
  103. Tags are simple drawing procedures used to annotate or highlight
  104. areas of the graph. A tag may be either a text string, bitmap,
  105. line, window, or polygon.  A tag may be associated with a particular 
  106. element, so that the tag is displayed only if the element is 
  107. displayed.  Tags are the first items drawn when the graph is displayed, 
  108. so that elements, symbols, legend, and axes always appear in front of them.  
  109. .PP
  110. Tags differ from elements in that they do not affect the auto-scaling of 
  111. coordinate axes.  Furthermore, tags can have \fIelastic\fR coordinates
  112. (specified by \fC-Inf\fR and \fCInf\fR respectively) which translate into
  113. the axis minimum or maximum limit.  For example, to place a tag so it
  114. always remains in the lower left corner of the plot, use the coordinates
  115. \fC-Inf\fR,\fC-Inf\fR.
  116. .SH "WIDGET COMMANDS"
  117. .PP
  118. The \fBblt_graph\fR command creates a new Tcl command whose
  119. name is \fIpathName\fR.  This
  120. command may be used to invoke various
  121. operations on the widget.  It has the general form:
  122. .DS C
  123. \fIpathName option \fR?\fIarg arg ...\fR?
  124. .DE
  125. \fIOption\fR and the \fIarg\fRs
  126. determine the exact behavior of the command.  The following
  127. commands are valid for \fBblt_graph\fR widgets:
  128. .TP
  129. \fIpathName \fBconfigure \fR?\fIoptions...\fR?
  130. Queries or modifies the configuration options of the widget. 
  131. Valids options are described in
  132. .SB WIDGET OPTIONS.
  133. .TP
  134. \fIpathName \fBcrosshairs configure\fR ?\fIoptions...\fR?
  135. Queries or modifies the configuration options of the crosshairs.
  136. This command is similar to the \fBconfigure\fR command, except that it
  137. applies to the options of the crosshairs, whereas \fBconfigure\fR applies 
  138. to the options for the graph as a whole.  See
  139. .SB CROSSHAIRS OPTIONS
  140. for a description of valid options.
  141. .TP
  142. \fIpathName \fBcrosshairs toggle\fR
  143. Toggles the current state of the crosshairs, turning them on or off.
  144. This command returns an empty string.
  145. .TP
  146. \fIpathName \fBelement activate \fIname \fR?\fIindex...?\fR
  147. Specifies which data points of element \fIname\fR are to be drawn 
  148. using active foreground and background colors.  \fIName\fR is the name
  149. of the element and \fIindex\fR is a number representing the index of 
  150. the data point. If no indices are present then all data points become 
  151. active.  This command returns the empty string.
  152. .TP
  153. \fIpathName \fBelement append \fIname coords\fR
  154. Appends pairs of x,y data points to element \fIname\fR.  
  155. \fIcoords\fR is a list of numeric expressions (x,y graph coordinates) 
  156. representing data points.  It returns the empty string.
  157. .TP
  158. \fIpathName \fBelement closest \fIwinX winY ?name...?\fR
  159. Finds the data point closest to the window coordinates \fIwinX\fR and 
  160. \fIwinY\fR in the element \fIname\fR.  It returns a list containing the 
  161. name of the closest element, the index of its closest point, 
  162. and the graph x,y coordinates of the point.  If no data point
  163. within a threshold distance can be found (see the \fB-halo\fR option), 
  164. then the empty list is returned.  \fIName\fR is the name of an 
  165. element, which must be mapped.  If no elements are specified, then
  166. all mapped elements are searched.  
  167. .TP
  168. \fIpathName \fBelement configure \fIname \fR?\fIoptions...\fR?
  169. This command is similar to the \fBconfigure\fR command, except that it
  170. applies to the options of an individual element, whereas
  171. \fBconfigure\fR applies to the options for the graph as a whole.
  172. \fIOptions\fR may have any of the values accepted by the
  173. \fBelement create\fR widget command. See
  174. .SB ELEMENT OPTIONS
  175. for a description of valid options.
  176. .TP
  177. \fIpathName \fBelement create \fIname \fR?\fIoptions...\fR? 
  178. Creates a new element \fIname\fP in the graph.  Element names must be
  179. unique, so \fIname\fR can not already exist in the graph.  
  180. If additional arguments are present, they specify any of the 
  181. element options (see 
  182. .SB ELEMENT OPTIONS
  183. ).
  184. .TP
  185. \fIpathName \fBelement deactivate \fIname ?name...?\fR
  186. .VS
  187. Deactivate the named elements.  The elements will be redrawn using
  188. their normal foreground and background colors.  \fIName\fR is the name
  189. of the element. This command returns the empty string.
  190. .VE
  191. .TP
  192. \fIpathName \fBelement delete ?\fIname ...\fR?
  193. Deletes the element \fIname\fR from the graph.  
  194. Returns the empty string.
  195. .TP
  196. \fIpathName \fBelement names\fR
  197. Returns a list of all elements. This differs from
  198. \fBelement show\fR in that it returns the names of all elements, not
  199. just those in the element display list.
  200. .TP
  201. \fIpathName \fBelement show \fR?\fInames\fR?
  202. Queries or resets the element display list.  
  203. The element display
  204. list defines which elements are drawn and in what order.  
  205. \fINames\fR is a list of the elements to
  206. be displayed.  If there is no \fInames\fR argument, the list of elements 
  207. currently being displayed is returned.
  208. .TP
  209. \fIpathName \fBinvtransform \fIwinX winY\fP 
  210. Performs an inverse coordinate transformation, mapping x,y window 
  211. coordinates to graph coordinates (using the standard x and y axes).  
  212. Returns a list of containing the x and y graph coordinates.
  213. .TP
  214. \fIpathName \fBlegend activate \fIname...\fR
  215. .VS
  216. Specifies that the legend entries of the named elements should be drawn 
  217. with the active legend background and foreground colors.  The entries may 
  218. also be drawn with a different relief (using the \fB-activerelief\fR and 
  219. \fB-activeborderwidth\fR options).
  220. \fIName\fR is the name of an element in the graph.
  221. .VE
  222. .TP
  223. \fIpathName \fBlegend configure \fR?\fIoptions...\fR?
  224. This command is similar to the \fBconfigure\fR command, except that it
  225. applies to the options for the legend, whereas \fBconfigure\fR applies
  226. to the options for the graph as a whole.  See 
  227. .SB LEGEND OPTIONS
  228. for a description of valid options.  
  229. .TP
  230. \fIpathName \fBlegend deactivate \fIname...\fR
  231. .VS
  232. Specifies that the legend enties of the named elements should be drawn 
  233. with the legend background and foreground colors.  \fIName\fR is the 
  234. name of an element in the graph.
  235. .VE
  236. .TP
  237. \fIpathName \fBlegend get \fIstring\fR
  238. .VS
  239. Returns the name of the graph element at the current screen position
  240. in the legend.  \fIString\fR must be in the form "\fI@x,y\fR", where 
  241. \fIx\fR and \fIy\fR are the window coordinates.  If the given screen 
  242. coordinates do not lie over a legend entry, the empty string is returned.
  243. .VE
  244. .TP
  245. \fIpathName \fBpostscript \fR?\fIfileName\fR? ?\fIoptions...\fR?
  246. Generates PostScript commands to print the graph. If no \fIfileName\fR
  247. argument is present, the PostScript output is returned. Otherwise,
  248. \fIfileName\fR is created and will contain the PostScript output.  In
  249. this case the empty string is returned.  If any \fIoption-value\fR
  250. pairs are present, they set configuration options controlling how the
  251. PostScript is generated. See 
  252. .SB POSTSCRIPT OPTIONS
  253. for a description of valid options.
  254. .TP
  255. \fIpathName \fBpsconfigure \fR?\fIoptions...\fR?
  256. Queries or modifies the options of the \fBpostscript\fR command.  
  257. See 
  258. .SB POSTSCRIPT OPTIONS
  259. for a description of valid options.  
  260. .TP
  261. \fIpathName \fBtag after \fItagId\fR ?\fItagId\fR?
  262. Reorders the tag display list placing the first tag specified after
  263. the second.  If no second \fItagId\fR argument is specified, the tag
  264. is placed at the end of the list.  This command can be used to control
  265. how tags are displayed since tags are drawn in the order of this
  266. display list.  The empty string is returned.
  267. .TP
  268. \fIpathName \fBtag before \fItagId\fR ?\fItagId\fR?
  269. Reorders the tag display list placing the first tag specified before
  270. the second.  If no second \fItagId\fR argument is specified, the tag
  271. is placed at the beginning of the list.  This command can be used to
  272. control how tags are displayed since tags are drawn in the order of
  273. this display list.  The empty string is returned.
  274. .TP
  275. \fIpathName \fBtag configure \fItagId\fR ?\fIoptions...\fR? 
  276. Queries or modifies the configuration options of the particular tag.
  277. See 
  278. .SB TAG OPTIONS
  279. for a description of valid options.
  280. .TP
  281. \fIpathName \fBtag coords \fItagId\fR ?\fIcoords\fR? 
  282. Queries or resets the coordinates of the tag designated by
  283. \fItagId\fR.  If \fIcoords\fR is present, it is a list of coordinate pairs
  284. representing the points of the tag.  This list is used to re-position the tag.
  285. If the \fIcoords\fR argument is not present, the current list of
  286. coordinates for \fItagId\fR is returned.
  287. .TP
  288. \fIpathName \fBtag create \fItype\fR ?\fIcoords\fR? ?\fIoptions...\fR?
  289. Creates a tag of the selected type. \fIType\fR may be either
  290. \fCtext\fR, \fCline\fR, \fCbitmap\fR, \fCpolygon\fR, or \fCwindow\fR.
  291. \fIcoords\fR is a list of coordinate pairs of points used
  292. to position the tag.  See
  293. .SB TAG OPTIONS
  294. for a description of valid options.  This command returns a
  295. unique tag identifier, which is used as the \fItagId\fR argument in
  296. other tag-related commands.
  297. .TP
  298. \fIpathName \fBtag delete \fItagId\fR ?\fItagId..\fR?
  299. Deletes each of the specified tags.  This command returns the empty string.
  300. .TP
  301. \fIpathName \fBtag ids\fR ?\fIpattern\fR? 
  302. Returns a list of IDs of tags created.  If \fIpattern\fR is supplied,
  303. only those tags whose IDs matching it will be returned.
  304. .TP
  305. \fIpathName \fBtag type \fItagId\fR 
  306. Returns the type of the tag given by \fItagId\fR, such as
  307. \fCLine\fR or \fCText\fR. 
  308. If \fItagId\fR is not a valid a tag identifier, the empty string is returned.
  309. .TP
  310. \fIpathName \fBtransform \fIx y\fP 
  311. Transforms the graph coordinates into window coordinates, by mapping
  312. the \fIx\fR and \fIy\fR values onto the standard axes (x and y).
  313. Returns a list containing the x and y window coordinates.
  314. Please note that graph coordinates far outside of the axis range are 
  315. not guarenteed to be accurate.
  316. .TP
  317. \fIpathName \fBxaxis configure\fR ?\fIoptions...\fR? 
  318. .TP
  319. \fIpathName \fByaxis configure\fR ?\fIoptions...\fR? 
  320. .TP
  321. \fIpathName \fBx2axis configure\fR ?\fIoptions...\fR? 
  322. .TP
  323. \fIpathName \fBy2axis configure\fR ?\fIoptions...\fR? 
  324. Queries or modifies the configuration options of the coordinate axis.  
  325. See 
  326. .SB AXIS OPTIONS
  327. for a description of valid options.
  328. .TP
  329. \fIpathName \fBxaxis limits\fR
  330. .TP
  331. \fIpathName \fByaxis limits\fR
  332. .TP
  333. \fIpathName \fBx2axis limits\fR
  334. .TP
  335. \fIpathName \fBy2axis limits\fR
  336. Returns a list of two graph coordinates representing the minimum and maximum 
  337. limits of the x-axis.  The format of the list returned is \fCmin max\fR.
  338. .sp 1
  339. .SH "CONFIGURATION OPTIONS"
  340. .SS "WIDGET OPTIONS"
  341. The following widget options are valid for the \fBconfigure\fR command.  
  342. .DS
  343. \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
  344. .DE
  345. The \fBconfigure\fR command queries or modifies the configuration options 
  346. of the widget.  If no \fIoption\fR is specified, returns a list 
  347. describing all of the
  348. available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
  349. information on the format of this list).  
  350. If \fIoption\fR is specified with no \fIvalue\fR, then the command 
  351. returns a list describing the one named option (this list will be 
  352. identical to the corresponding sublist of the value returned if 
  353. no \fIoption\fR is specified).  If one or more \fIoption\-value\fR 
  354. pairs are specified, then the command
  355. modifies the given widget option(s) to have the given value(s); in
  356. this case the command returns the empty string.  
  357. .TP
  358. \fB\-bottommargin \fIpixels\fR
  359. Specifies the size of the margin from the x-coordinate axis to the 
  360. bottom of the window.  The x-axis title is displayed in this margin.  
  361. \fIPixels\fR may be specified in any of the forms described in 
  362. \fBTk_GetPixels\fR.  If \fIpixels\fR is less than one pixel, the 
  363. the margin size is selected automatically.
  364. .TP
  365. \fB\-bufferelements \fIboolean\fR
  366. .VS
  367. Specifies whether to use a pixmap to cache the display of elements.
  368. This is especially useful when there are many data points or the
  369. graph is redrawn frequently.  \fIBoolean\fR is \fCtrue\fR by default.
  370. .VE
  371. .TP
  372. \fB\-halo \fIpixels\fR
  373. Specifies a threshold distance when searching for the closest data 
  374. point (see the \fBelement closest\fR command).  Only data points
  375. within this distance are considered in the search.
  376. If this option isn't specified, it defaults to \fC0.5i\fR.
  377. .TP
  378. \fB\-height \fIpixels\fR
  379. Specifies a desired window height that the graph widget should 
  380. request from its geometry manager. The default height is \fC400\fR.
  381. .TP
  382. \fB\-invertxy \fIboolean\fR
  383. .VS
  384. Specifies that placement of the x and y axes should be inverted.
  385. If \fIboolean\fR is \fCtrue\fR, the x-axis is exchanged with the
  386. y-axis.  By default \fIboolean\fR is \fCfalse\fR.
  387. .VE
  388. .TP
  389. \fB\-leftmargin \fIpixels\fR
  390. Sets the size of the margin from the left edge of the window to the
  391. the y-coordinate axis.  The y-axis title is displayed in this
  392. margin.  If \fIpixels\fR is less than one pixel, 
  393. the margin size is selected automatically.
  394. .TP
  395. \fB\-plotbackground \fIcolor\fR
  396. Sets the background color of the plotting area.  
  397. .TP
  398. \fB\-plotborderwidth \fIpixels\fR
  399. Sets the width of the 3-D border to draw around the outside of
  400. the plotting area (if such border is being drawn; the \fBplotrelief\fR option
  401. determines this).  By default is the plot border width is \fC2\fR.
  402. .TP
  403. \fB\-plotrelief \fIstring\fR
  404. Specifies the 3-D effect desired for the plotting area.  
  405. \fIString\fR must be in a form accepted by \fBTk_GetRelief\fR. 
  406. It indicates how the interior of the plotting area should appear 
  407. relative to rest of the graph; for example, \fCraised\fR means the 
  408. plot should appear to protrude from the graph, relative to the surface 
  409. of the graph.  By default, the plot relief is \fCsunken\fR.
  410. .TP
  411. \fB\-rightmargin \fIpixels\fR
  412. Sets the size of marging from the plotting area to the right edge 
  413. of the window.  By default, the legend is displayed in this margin.  
  414. If \Ipixels\fR is than 1, the margin size
  415. is selected automatically.
  416. .TP
  417. \fB\-title \fIstring\fR
  418. Specifies the title of the graph.  If \fIstring\fR is the empty string 
  419. (the default), no title is displayed.
  420. .TP
  421. \fB\-topmargin \fIpixels\fR
  422. Sets the size of the marging the top edge of the window to the plotting area.
  423. The graph title is displayed in this margin.  
  424. If \fIpixels\fR is less than 1, the margin size
  425. is selected automatically.
  426. .TP
  427. \fB\-width \fIpixels\fR
  428. Specifies a desired window width that the graph widget should
  429. request from its geometry manager.  The default width is \fC400\fR.
  430. .sp 1
  431. .SS "AXIS OPTIONS"
  432. The following options are valid for the \fBxaxis configure\fR, 
  433. \fByaxis configure\fR, \fBx2axis configure\fR, and the \fBy2axis configure\fR commands.  
  434. .DS
  435. \fIpathName \fBxaxis configure \fR?\fIoptions...\fR?
  436.  
  437. \fIpathName \fByaxis configure \fR?\fIoptions...\fR?
  438.  
  439. \fIpathName \fBx2axis configure \fR?\fIoptions...\fR?
  440.  
  441. \fIpathName \fBy2axis configure \fR?\fIoptions...\fR?
  442. .DE
  443. In addition, axis configuration options may be initialized by the
  444. \fBoption\fR command.  The name fields in the \fBblt_graph\fR 
  445. option database are
  446. prefixed by \fCx\fR, \fCy\fR, \fCx2\fR, or \fCy2\fR while 
  447. the class fields are prefixed by \fCAxis\fR. The following example sets 
  448. the color of all axes to blue and the x-axis scale to logarithmic.
  449. .DS
  450. \fCoption add *Blt_graph.AxisColor blue\fR
  451. \fCoption add *Blt_graph.xLogscale true\fR
  452. .DE
  453. .TP
  454. \fB\-color \fIcolor\fR
  455. Sets the color of the axis and its labels.
  456. This option defaults to \fCblack\fR.
  457. .TP
  458. \fB\-command \fIprefix\fR
  459. Specifies a Tcl command to be invoked when formatting the axis labels.
  460. \fIPrefix\fR is typically just the name of a Tcl procedure, but the string
  461. may also contain extra arguments for the procedure.  When invoked, two
  462. arguments (the path name of the graph widget and the numeric value of
  463. the axis label) are appended to the end of the command.  The procedure
  464. value should be a string representing the formatted label. If the value is
  465. the empty string or if \fIprefix\fR is the empty string, the default axis
  466. label is displayed.  Please note that this procedure is invoked during
  467. the display of the graph.  Resetting graph configurations within this 
  468. procedure can cause unexpected results.
  469. .TP
  470. \fB\-descending \fIboolean\fR
  471. .VS
  472. Specifies whether the values along the axis are increasing or decreasing.  
  473. If \fIboolean\fR is true, the axis values will decrease.
  474. By default, the axis values increase.
  475. .VE
  476. .TP
  477. \fB\-font \fIfontName\fR 
  478. Specifies the font for axis labels. If
  479. \fIfontName\fR isn't specified then it defaults to
  480. \fC*-Courier-Bold-R-Normal-*-100-*\fR.
  481. .TP
  482. \fB\-linewidth \fIpixels\fR
  483. Sets the line width of the axis and its ticks.  The default line
  484. width is \fC0\fR.
  485. .TP
  486. \fB\-logscale \fIboolean\fR
  487. Sets the scale of the coordinate axis (either logarithmically or
  488. linearly).  If \fIboolean\fR is \fCtrue\fR, the axis will be displayed
  489. in logarithmic scale.  \fIBoolean\fR must be a value accepted by
  490. \fBTcl_GetBoolean\fR.  By default, the scale is linear.
  491. .TP
  492. \fB\-loose \fIboolean\fR
  493. Indicates that when auto-scaling the axis, the axis range 
  494. should fit loosely around the data points at the outer tick intervals.  
  495. Otherwise the axis range fits tightly at the limits of the data displayed. 
  496. By default, the range is tight.
  497. .TP
  498. \fB\-mapped \fIboolean\fR
  499. Specifies if the axis should be displayed. By default, the standard
  500. axes are displayed (x and y), but not the alternate (x2 and y2).
  501. .TP
  502. \fB\-max \fIvalue\fR
  503. Sets the maximum limit of the axis.  Data points exceeding this
  504. limit are clipped at this value. If \fIvalue\fR is the empty string
  505. (the default), the axis is auto-scaled whereby the maximum limit is
  506. determined from the data points of the displayed elements.
  507. .TP
  508. \fB\-min \fIvalue\fR
  509. Sets the minimum limit of the axis. Data points less than this
  510. limit are clipped at this value.  If \fIvalue\fR is the empty string
  511. (the default), the axis is auto-scaled whereby the minimum limit is
  512. determined from the data points of the displayed elements.
  513. .TP
  514. \fB\-rotate \fItheta\fR
  515. Specifies the rotation of the axis labels.  \fITheta\fR is a
  516. real number representing the angle of rotation in degrees.
  517. The default rotation is \fC0.0\fR degrees.
  518. .TP
  519. \fB\-showticks \fIboolean\fR
  520. Indicates if axis ticks should be displayed. If \fIboolean\fR is
  521. \fCtrue\fR (the default), ticks are displayed.
  522. .TP
  523. \fB\-stepsize \fIvalue\fR
  524. Sets the step size between major axis ticks.  \fIValue\fR must be
  525. greater than zero and less than the axis range, or the requested step size 
  526. is ignored and the step size is automatically calculated based
  527. upon the element data points.
  528. .TP
  529. \fB\-subticks \fInumber\fR
  530. Sets the number of minor axis ticks to be displayed.  By default, the
  531. number of minor ticks is \fC5\fR.  If \fInumber\fR is zero, no subticks
  532. will be displayed.
  533. .TP
  534. \fB\-ticklength \fIpixels\fR
  535. .VS
  536. Sets the length of the ticks and subticks (subticks are one-half \fIpixels\fR).
  537. If \fIpixels\fR is negative, ticks will point towards the plot, instead
  538. of away from it.  The tick length is \fC0.1i\fR.  
  539. .VE
  540. .TP
  541. \fB\-title \fIstring\fR
  542. Sets the title of the axis. If \fIstring\fR is the
  543. empty string, no axis title will be displayed.  
  544. .sp 1
  545. .SS "CROSSHAIRS OPTIONS"
  546. .PP
  547. The following options are valid for the \fBcrosshair configure\fR command.
  548. .DS
  549. \fIpathName \fBcrosshairs configure\fR ?\fIoptions...\fR?
  550. .DE
  551. In addition, crosshairs configuration options may be initialized by the 
  552. \fBoption\fR command.  The name fields in the \fBblt_graph\fR option database
  553. are prefixed by
  554. by \fCxhairs\fR and classfields are prefixed by \fCXhairs\fR. 
  555. The following example sets the line width of the crosshairs to \fC2\fR.
  556. .DS
  557. \fCoption add *Blt_graph.xhairsLinewidth 2\fR
  558. .DE
  559. .TP
  560. \fB\-color \fIcolor\fR 
  561. Sets the color of the crosshairs.  
  562. If this option isn't specified, then it defaults to \fCblack\fR.
  563. .TP
  564. \fB\-dashes \fIdashes\fR
  565. Sets the dash style of the crosshairs. \fIdashes\fR
  566. is the number of alternatingly displayed pixels. If \fIdashes\fR is
  567. \fC0\fR (the default), the crosshairs will be drawn as a solid line. 
  568. .TP
  569. \fB\-linewidth \fIpixels\fR
  570. Set the line width of crosshairs.  The default line width is \fC0\fR.
  571. .TP
  572. \fB\-mapped \fIboolean\fR
  573. Specifies if the crosshairs should be displayed. By default, 
  574. the crosshairs are not displayed.  
  575. .TP
  576. \fB\-position \fIstring\fR
  577. Specifies the position of the crosshairs. \fIString\fR must be in the
  578. format "\fI@x,y\fR", where \fIx\fR and \fIy\fR 
  579. are window coordinates.  
  580. .sp 1
  581. .SS "ELEMENT OPTIONS"
  582. .PP
  583. The following options are valid for the \fBelement create\fR and 
  584. \fBelement configure\fR commands.
  585. \fIName\fR is the name of the element to be configured.
  586. .DS
  587. \fIpathName \fBelement create \fIname\fR ?\fIoptions...\fR?
  588.  
  589. \fIpathName \fBelement configure \fIname\fR ?\fIoptions...\fR?
  590. .DE
  591. In addition, element configuration options may be initialized by the 
  592. \fBoption\fR command.  The name fields in the \fBblt_graph\fR option database 
  593. are prefixed by \fCelem\fR. 
  594. The following example sets the symbol type of all elements to \fBline\fR 
  595. and the line width of all elements to \fC2\fR.
  596. .DS
  597. \fCoption add *Blt_graph.elemSymbol line\fR
  598. \fCoption add *Blt_graph.LineWidth 2\fR
  599. .DE
  600. .TP
  601. \fB\-activebackground \fIcolor\fR
  602. Like the \fB-background\fR option, but specifies the background
  603. color to use when drawing data points which are active
  604. (see the \fBelement activate\fR command).
  605. .TP
  606. \fB\-activeforeground \fIcolor\fR 
  607. Like the \fB-foreground\fR option, but specifies the foreground
  608. color to use when drawing data points which are active
  609. (see the \fBelement activate\fR command).
  610. .TP
  611. \fB\-activelinewidth \fIpixels\fR
  612. .VS
  613. Sets the width of the lines drawn when the element is active.  
  614. If \fIpixels\fR is zero and the symbol is not \fCline\fR,  no line 
  615. will be drawn when the element is active.
  616. The default line width is \fC1\fR.
  617. .VE
  618. .TP
  619. \fB\-background \fIcolor\fR
  620. If the symbol type is \fCline\fR, then \fIcolor\fR specifies the
  621. background color for dashed lines.  For non-line symbols, \fIcolor\fR
  622. specifies the fill color for the symbol (the foreground color is the
  623. outline).  If this option isn't specified then it defaults to
  624. \fCwhite\fR.
  625. .TP
  626. \fB\-dashes \fIdashes\fR
  627. Sets the dash style for lines. \fIdashes\fR is the number of
  628. alternatingly colored (foreground/background) pixels. If \fIdashes\fR 
  629. is \fC0\fR (the default), the line is drawn in a solid fashion.  This 
  630. option only has effect only if the symbol type is \fCline\fR or if the 
  631. line width is greater than zero.
  632. .TP
  633. \fB\-data \fIvalues\fR
  634. Specifies the graph coordinates of the the data points to be plotted.  
  635. \fIValues\fR is a list of valid numeric expressions.  
  636. It this option isn't specified, it defaults to the empty string.
  637. .TP
  638. \fB\-foreground \fIcolor\fR 
  639. Sets the foreground color of the element.
  640. If this option isn't specified then it defaults to \fCblack\fR.
  641. .TP
  642. \fB\-label \fIstring\fR
  643. Sets the element label.  Labels are displayed in the 
  644. legend next to the element symbol.  If \fIstring\fR is the empty 
  645. string, no legend entry will be displayed for the element.  By 
  646. default, the label is the name of the element.
  647. .TP
  648. \fB\-linewidth \fIpixels\fR
  649. Sets the width of the lines drawn.  For non-\fCline\fR symbols, 
  650. if \fIpixels\fR is greater than zero, a line is drawn between 
  651. the symbols.  The default line width is \fC0\fR.
  652. .TP
  653. \fB\-mapx \fItype\fR
  654. Specifies which x-axis to map the element's x-coordinates onto.
  655. \fIType\fR must be either \fCx\fR, \fCx2\fR, or \fCboth\fR.  The default
  656. axis is \fCx\fR.
  657. .TP
  658. \fB\-mapy \fItype\fR
  659. Specifies which y-axis to map the element's y-coordinates onto.
  660. \fIType\fR must be either \fCy\fR, \fCy2\fR, or \fCboth\fR.  The default
  661. axis is \fCy\fR.
  662. .TP
  663. \fB\-noretrace \fIboolean\fR
  664. If \fIboolean\fR is \fCtrue\fR, data points where x-coordinate values
  665. are not monotonically increasing (where the current x-coordinate value
  666. is less than the previous) indicate the start of a new line.  In this
  667. case, no connecting line segment will be drawn from the last to the
  668. current point.  If \fIboolean\fR is \fCfalse\fR, all points will be
  669. connected by line segments, regardless of their order. 
  670. The default value is \fCfalse\fR.
  671. .TP
  672. \fB\-scale \fIvalue\fR
  673. Specifies a scale factor for the size of the element's symbol. The default
  674. scale factor is \fC1.0\fR.
  675. .TP
  676. \fB\-symbol \fItype\fR
  677. \fIType\fR specifies the type of symbol to use for plotting data
  678. points.  Valid symbol types are \fCline\fR, \fCsquare\fR, \fCcircle\fR,
  679. \fCdiamond\fR, \fCplus\fR, \fCcross\fR, \fCsplus\fR, 
  680. and \fCscross\fR.  The default
  681. symbol type is \fCline\fR.
  682. .TP
  683. \fB\-trace \fIstring\fR 
  684. .VS
  685. Indicates if to trace (draw lines) between data points where values
  686. are increasing or decreasing.  
  687. \fIString\fR must be either
  688. \fCincreasing\fR, \fCdecreasing\fC, or \fCboth\fR.  
  689. For example, if
  690. \fIstring\fR is \fCincreasing\fR, data points where x-coordinate
  691. values are not monotonically increasing (where the current
  692. x-coordinate value is less than the previous) indicate the start of a
  693. new line.  In this case, no connecting line segment will be drawn from
  694. the last to the current point.  If \fIstring\fR is \fCboth\fR, all
  695. points will be connected by line segments, regardless of their order.
  696. The default value is \fCboth\fR.
  697. .VE
  698. .TP
  699. \fB\-xdata \fIvalues\fR
  700. Specifies the x-coordinates of the data points to be plotted.  
  701. \fIValues\fR is a list of valid numeric expressions.  It this 
  702. option isn't specified, it defaults to the empty string.
  703. .TP
  704. \fB\-ydata \fIvalues\fR
  705. Specifies the y-coordinates of the data points to be plotted.  
  706. \fIValues\fR is a valid list of numeric expressions.  It this 
  707. option isn't specified, it defaults to the empty string.
  708. .sp 1
  709. .SS "LEGEND OPTIONS"
  710. The following options are valid for the \fBlegend configure\fR command.
  711. .DS
  712. \fIpathName \fBlegend configure \fR?\fIoptions...\fR?
  713. .DE
  714. In addition, legend configuration options may be initialized by the
  715. \fBoption\fR command.  The name fields in the \fBblt_graph\fR 
  716. option database are
  717. prefixed by \fClegend\fR.  The following example initializes the
  718. legend foreground color to blue in the option database.
  719. .DS
  720. \fCoption add *Blt_graph.legendForeground blue\fR
  721. .DE
  722. .TP
  723. \fB\-activebackground \fIcolor\fR
  724. .VS
  725. Sets the active background color of the legend.  All legend entries
  726. marked as active (see \fBlegend activate\fR command) are drawn with
  727. this background color.
  728. .VE
  729. .TP
  730. \fB\-activeborderwidth \fIpixels\fR
  731. .VS
  732. Sets the width of the 3-D border to draw around the outside of
  733. the each active legend entry (if such border is being drawn; 
  734. the \fB-activerelief\fR option determines this).  By default is the 
  735. active border width is \fC2\fR.
  736. .VE
  737. .TP
  738. \fB\-activeforeground \fIcolor\fR
  739. .VS
  740. Sets the active foreground color of the legend.  All legend entries
  741. marked as active (see \fBlegend activate\fR command) are drawn with
  742. this foreground color.
  743. .VE
  744. .TP
  745. \fB\-activerelief \fIstring\fR
  746. .VS
  747. Specifies the 3-D effect desired for active legend entries.  \fIString\fR 
  748. must be in a form accepted by \fBTk_GetRelief\fR. 
  749. It indicates how  the interior of the entry should appear relative to 
  750. the legend; for
  751. example, \fCraised\fR means the entry should appear to protrude from
  752. the legend, relative to the surface of the legend.  By default, the
  753. active legend relief is \fCflat\fR.
  754. .VE
  755. .TP
  756. \fB\-anchor \fIanchorPos\fR
  757. Tells how to position the legend relative to the positioning point for
  758. the legend; \fIanchorPos\fR may have any of the forms accepted by
  759. \fBTk_GetAnchor\fR.  For example, if \fIanchorPos\fR is \fCcenter\fR
  760. then the legend is centered on the point; if \fIanchorPos\fR is
  761. \fCn\fR then the legend will be drawn such that the top center point
  762. of the rectangular region occupied by the legend will be at the
  763. positioning point.  This option defaults to \fCcenter\fR.
  764. .TP
  765. \fB\-background \fIcolor\fR
  766. .VS
  767. Sets the background color of the legend. \fIcolor\fR must be a valid
  768. color, it can not be the empty string.
  769. .VE
  770. .TP
  771. \fB\-borderwidth \fIpixels\fR
  772. Sets the width of the 3-D border to draw around the outside of
  773. the legend (if such border is being drawn; the \fBrelief\fR option
  774. determines this).  By default is the legend border width is \fC2\fR.
  775. .TP
  776. \fB\-font \fIfontName\fR 
  777. \fIFontName\fR specifies a font to use when drawing the labels of each
  778. element into the legend.  If this option isn't specified then it
  779. defaults to \fC*-Helvetica-Bold-R-Normal-*-120-*\fR.
  780. .TP
  781. \fB\-foreground \fIcolor\fR 
  782. Sets the foreground color of the element labels in the legend.  
  783. If this option isn't specified, then it defaults to \fCblack\fR.
  784. .TP
  785. \fB\-ipadx \fIpixels\fR
  786. Sets the internal padding to the width of the legend. 
  787. Padding will be added to both the left and right and
  788. between the elements symbol and label.
  789. By default is the legend border width is \fC2\fR.
  790. .TP
  791. \fB\-ipady \fIpixels\fR
  792. Sets the internal padding to the height of the legend. 
  793. Padding will be added to both the top and bottom and
  794. between the elements labels.
  795. By default is the legend border width is \fC2\fR.
  796. .TP
  797. \fB\-mapped \fIboolean\fR
  798. Indicates if the legend should be displayed. If \fIboolean\fR is
  799. \fCtrue\fR (the default), the legend will be mapped.  
  800. .TP
  801. \fB\-padx \fIpixels\fR
  802. Specifies extra padding on the left and right of the legend.
  803. The default is \fC4\fR.
  804. .TP
  805. \fB\-pady \fIpixels\fR
  806. Specifies extra padding on the top and bottom of the legend.
  807. The default is \fC0\fR.
  808. .TP
  809. \fB\-position \fIstring\fR
  810. Sets the positioning point of the legend in window coordinates.
  811. This option in conjunction with the \fB-anchor\fR option, determines
  812. where the legend is positioned. The format of \fIstring\fR is
  813. "\fI@x,y\fR", where \fIx\fR and \fIy\fR are the window coordinate
  814. values.  If \fIstring\fR is the empty string (the default), the legend
  815. will be displayed in the right margin (which is automatically extended
  816. to accommodate the legend).
  817. .TP
  818. \fB\-relief \fIstring\fR
  819. Specifies the 3-D effect desired for the legend.  \fIString\fR must be
  820. in a form accepted by \fBTk_GetRelief\fR. 
  821. It indicates how  the interior of the legend should appear relative to 
  822. the graph; for
  823. example, \fCraised\fR means the legend should appear to protrude from
  824. the graph, relative to the surface of the graph.  By default, the
  825. legend relief is \fCsunken\fR.
  826. .sp 1
  827. .SS "TAG OPTIONS"
  828. .PP
  829. The following options are valid for the \fBtag create\fR and \fBtag configure\fR commands.  
  830. \fITagid\fR is the identifier returned by the \fBtag create\fR command.
  831. .DS
  832. \fIpathName \fBtag create \fItype\fR ?\fIcoords\fR? ?\fIoptions...\fR?
  833.  
  834. \fIpathName \fBtag configure \fItagId\fR ?\fIoptions...\fR?
  835. .DE
  836. Tag configuration options may be initialized by the
  837. \fBoption\fR command.  The name fields in the \fBblt_graph\fR
  838. option database are
  839. prefixed by \fCbmTag\fR, \fCtextTag\fR, \fClineTag\fR,
  840. \fCpolyTag\fR, or \fCwinTag\fR with respect to the tag type.
  841. Class fields are prefixed by \fCTag\fR. The following example sets
  842. the background color of all tags to blue and the foreground color of
  843. all text tags to white.
  844. .DS
  845. \fCoption add *Blt_graph.TagBackground blue\fR
  846. \fCoption add *Blt_graph.textTagForeground white\fR
  847. .DE
  848. The description of tag options is broken into subsections for each tag type.
  849. .sp 1
  850. .SS "TEXT TAGS"
  851. A text tag displays a string of characters on a single line.  They may
  852. be used to annotate regions of the graph.  Text tags are
  853. created with the following widget command:
  854. .DS
  855. \fIpathName \fBtag create text \fR?\fIcoords\fR? ?\fIoptions...\fR?
  856. .DE
  857. The argument \fIcoords\fR specifies a list of two numeric
  858. expressions representing the graph coordinates of a point 
  859. used to position the text on the graph. 
  860. .P
  861. After the coordinate list there may be any number of
  862. \fIoption\fR-\fIvalue\fR pairs, each of which sets one of the
  863. configuration options for the tag.  These same
  864. \fIoption\fR\-\fIvalue\fR pairs may be used in the \fBtag configure\fR
  865. command to change the tag's configuration.  The following
  866. options are supported for text tags:
  867. .TP
  868. \fB\-anchor \fIanchorPos\fR
  869. \fIAnchorPos\fR tells how to position the text relative to the
  870. positioning point for the text; it may have any of the forms accepted
  871. by \fBTk_GetAnchor\fR.  For example, if \fIanchorPos\fR is
  872. \fCcenter\fR then the text is centered on the point; if
  873. \fIanchorPos\fR is \fCn\fR then the text will be drawn such that the
  874. top center point of the rectangular region occupied by the text will
  875. be at the positioning point.  This option defaults to \fCcenter\fR.
  876. .TP
  877. \fB\-background \fIcolor\fR
  878. Sets the background color of the text string.  
  879. If \fIcolor\fR is the empty string, the background will be transparent.
  880. If this option isn't specified then it defaults to \fCwhite\fR.
  881. .TP
  882. \fB\-font \fIfontName\fR
  883. Specifies the text font.
  884. If this option isn't specified, it defaults 
  885. \fC*-Helvetica-Bold-R-Normal-*-120-*\fR.
  886. .TP
  887. \fB\-foreground \fIcolor\fR
  888. Sets the foreground color of the text.  
  889. If this option isn't specified then it defaults to \fCblack\fR.
  890. .TP
  891. \fB\-element \fIname\fR
  892. Associates the tag with the element \fIname\fR.  If \fIname\fR is not
  893. the empty string (the default), the tag is displayed only if
  894. \fIname\fR exists and is currently being displayed (see \fBelement show\fR).
  895. .TP
  896. \fB\-mapx \fItype\fR
  897. Specifies which x-axis to map the tag's x-coordinates onto.
  898. \fIType\fR must be either \fCx\fR, \fCx2\fR, or \fCboth\fR.  The default
  899. axis is \fCx\fR.
  900. .TP
  901. \fB\-mapy \fItype\fR
  902. Specifies which y-axis to map the tag's y-coordinates onto.
  903. \fIType\fR must be either \fCy\fR, \fCy2\fR, or \fCboth\fR.  The default
  904. axis is \fCy\fR.
  905. .TP
  906. \fB\-rotate \fItheta\fR
  907. Specifies how the tag is rotated.
  908. \fITheta\fR is a real number representing the angle of rotation in degrees.
  909. The tag is first rotated along its center and is then displayed according 
  910. to its
  911. anchor position. The default rotation is \fC0.0\fR degrees.
  912. .TP
  913. \fB\-text \fIstring\fR
  914. Sets the text string.  The exact way
  915. in which the text string is displayed may be affected by other options
  916. such as \fB-anchor\fR or \fB-rotate\fR.  This option defaults to the
  917. empty string.
  918. .TP
  919. \fB\-xoffset \fIpixels\fR
  920. Specifies a x-coordinate offset (in window coordinates) from the
  921. specified position.  
  922. .TP
  923. \fB\-yoffset \fIpixels\fR
  924. Specifies a y-coordinate offset (in window coordinates) from the
  925. specified position.  
  926. .sp 1
  927. .SS "LINE TAGS"
  928. A line tag displays one or more connected line segments on the graph.
  929. Line tags are created with widget commands in the form:
  930. .DS
  931. \fIpathName \fBtag create line \fR?\fIcoords\fR? ?\fIoptions...\fR?
  932. .DE
  933. The argument \fIcoords\fR specifies a list of numeric
  934. expressions representing the graph coordinate pairs of the points 
  935. connecting the line.
  936. .P
  937. After the \fIcoords\fR there may be any number of \fIoption\fR-\fIvalue\fR
  938. pairs, each of which sets one of the configuration options
  939. for the tag.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  940. used in the \fBtag configure\fR command to change the tag's
  941. configuration.
  942. The following options are supported for line tags:
  943. .TP
  944. \fB\-background \fIcolor\fR
  945. Sets the background color of the line.
  946. The option is affects the line color only when the \fB-stipple\fR option 
  947. is set.  
  948. If this option isn't specified then it defaults to \fCwhite\fR.
  949. .TP
  950. \fB\-dashes \fIdashes\fR
  951. Sets the dash style of the line. \fIDashes\fR
  952. is the number of alternatingly displayed pixels. If \fIdashes\fR is
  953. \fC0\fR (the default), the tag will be drawn as a solid line. 
  954. .TP
  955. \fB\-element \fIname\fR
  956. Associates the tag with the element \fIname\fR.  The tag is displayed
  957. only if an element \fIname\fR exists and is currently displayed (see
  958. \fBelement show\fR).  If \fIname\fR is the empty
  959. string (the default), the tag is displayed.
  960. .TP
  961. \fB\-foreground \fIcolor\fR
  962. Sets the foreground color.  The default foreground color is \fCblack\fR.
  963. .TP
  964. \fB\-linewidth \fIpixels\fR
  965. Sets the width of the lines.
  966. The default width is \fC0\fR.
  967. .TP
  968. \fB\-mapx \fItype\fR
  969. Specifies which x-axis to map the tag's x-coordinates onto.
  970. \fIType\fR must be either \fCx\fR, \fCx2\fR, or \fCboth\fR.  The default
  971. axis is \fCx\fR.
  972. .TP
  973. \fB\-mapy \fItype\fR
  974. Specifies which y-axis to map the tag's y-coordinates onto.
  975. \fIType\fR must be either \fCy\fR, \fCy2\fR, or \fCboth\fR.  The default
  976. axis is \fCy\fR.
  977. .TP
  978. \fB\-stipple \fIbitmap\fR
  979. Indicates that the line should be drawn with a stippled pattern rather
  980. than solid; \fIbitmap\fR specifies the stipple pattern to use, may be
  981. in any of the forms accepted by \fBTk_GetBitmap\fR.  If \fIbitmap\fR is 
  982. the empty string (the default) then the line is drawn in a solid fashion.
  983. .TP
  984. \fB\-xoffset \fIpixels\fR
  985. Specifies an offset in the x-coordinate direction
  986. (in window coordinates) from the specified position.
  987. The default offset is \fC0\fR.
  988. .TP
  989. \fB\-yoffset \fIpixels\fR
  990. Specifies an offset in the y-coordinate direction
  991. (in window coordinates) from the specified position.
  992. The default offset ifs \fC0\fR.
  993. .sp 1
  994. .SS "BITMAP TAGS"
  995. A bitmap tag displays a bitmap on the graph.  Bitmap tags are
  996. created with widget commands in the form:
  997. .DS
  998. \fIpathName \fBtag create bitmap \fR?\fIcoords\fR? ?\fIoptions...\fR?
  999. .DE
  1000. The argument \fIcoords\fR specifies a list containing the graph
  1001. coordinates of a point used to position the bitmap on the display.
  1002. After the coordinate list there may be any number of \fIoption\fR-\fIvalue\fR
  1003. pairs, each of which sets one of the configuration options
  1004. for the tag.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1005. used in the \fBtag configure\fR command to change the tag's
  1006. configuration.
  1007. The following options are supported for bitmap tags:
  1008. .TP
  1009. \fB\-anchor \fIanchorPos\fR
  1010. \fIAnchorPos\fR tells how to position the bitmap relative to the
  1011. positioning point for the bitmap;  it may have any of the forms
  1012. accepted by \fBTk_GetAnchor\fR.  For example, if \fIanchorPos\fR
  1013. is \fCcenter\fR then the bitmap is centered on the point;  if
  1014. \fIanchorPos\fR is \fCn\fR then the bitmap will be drawn such that
  1015. the top center point of the rectangular region occupied by the
  1016. bitmap will be at the positioning point.
  1017. This option defaults to \fCcenter\fR.
  1018. .TP
  1019. \fB\-background \fIcolor\fR
  1020. Sets the background color of the bitmap.
  1021. If \fIcolor\fR is the empty string,
  1022. the background color will be transparent.
  1023. The default background color is \fCwhite\fR.
  1024. .TP
  1025. \fB\-foreground \fIcolor\fR
  1026. Sets the foreground color of the bitmap.  
  1027. The default foreground color is \fCblack\fR.
  1028. .TP
  1029. \fB\-bitmap \fIbitmap\fR
  1030. Specifies the bitmap to be displayed.
  1031. \fIBitmap\fR may have any of the forms accepted by \fBTk_GetBitmap\fR.
  1032. If \fIbitmap\fR is the empty string (the default), the tag will not be
  1033. displayed.
  1034. .TP
  1035. \fB\-element \fIname\fR
  1036. Associates the tag with the element \fIname\fR.  
  1037. If \fIname\fR is not the empty string (the default), the tag is displayed 
  1038. only if \fIname\fR exists and is being plotted
  1039. (see \fBelement show\fR).  
  1040. .TP
  1041. \fB\-mapx \fItype\fR
  1042. Specifies which x-axis to map the tag's x-coordinates onto.
  1043. \fIType\fR must be either \fCx\fR, \fCx2\fR, or \fCboth\fR.  The default
  1044. axis is \fCx\fR.
  1045. .TP
  1046. \fB\-mapy \fItype\fR
  1047. Specifies which y-axis to map the tag's y-coordinates onto.
  1048. \fIType\fR must be either \fCy\fR, \fCy2\fR, or \fCboth\fR.  The default
  1049. axis is \fCy\fR.
  1050. .TP
  1051. \fB\-rotate \fItheta\fR
  1052. Sets the rotation of the bitmap.
  1053. \fITheta\fR is a
  1054. real number representing the angle of rotation in degrees.
  1055. The tag is first rotated and then placed according to its anchor position.
  1056. The default rotation is \fC0.0\fR.
  1057. .TP
  1058. \fB\-xoffset \fIpixels\fR
  1059. Specifies an offset in the x-coordinate direction
  1060. (in window coordinates) from the specified position.
  1061. The default offset is \fC0\fR.
  1062. .TP
  1063. \fB\-yoffset \fIpixels\fR
  1064. Specifies an offset in the y-coordinate direction
  1065. (in window coordinates) from the specified position.
  1066. The default offset is \fC0\fR.
  1067. .sp 1
  1068. .SS "POLYGON TAGS"
  1069. A polygon tag displays a closed region described as two or more 
  1070. connected line segments on the graph. 
  1071. Polygon tags are created with the widget command:
  1072. .DS
  1073. \fIpathName \fBtag create polygon \fR?\fIcoords\fR? ?\fIoptions...\fR?
  1074. .DE
  1075. The argument \fIcoords\fR specifies a list of numeric
  1076. expressions representing graph coordinates which
  1077. describe the closed polygon.
  1078. It is assumed the first and last points are connected.
  1079. .P
  1080. After the coordinate list there may be any number of \fIoption\fR-\fIvalue\fR
  1081. pairs, each of which sets one of the configuration options
  1082. for the tag.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1083. used in the \fBtag configure\fR command to change the tag's
  1084. configuration.
  1085. The following options are supported for polygon tags:
  1086. .TP
  1087. \fB\-background \fIcolor\fR
  1088. Sets the background color of the polygon.  
  1089. The default background color is \fCwhite\fR.
  1090. .TP
  1091. \fB\-dashes \fIdashes\fR
  1092. .VS
  1093. Sets the dash style of the outline around the polygon. \fIDashes\fR
  1094. is the number of alternatingly displayed pixels. If \fIdashes\fR is
  1095. \fC0\fR (the default), the outline will be drawn as a solid line. 
  1096. .VE
  1097. .TP
  1098. \fB\-element \fIname\fR
  1099. Associates the tag with the element \fIname\fR.  
  1100. If \fIname\fR is not the empty string (the default), the tag is displayed 
  1101. only if \fIname\fR exists and is currently being displayed
  1102. (see \fBelement show\fR).
  1103. .TP
  1104. \fB\-foreground \fIcolor\fR
  1105. Sets the foreground color of the polygon.  
  1106. The default foreground color is \fCblack\fR.
  1107. .TP
  1108. \fB\-linewidth \fIpixels\fR
  1109. .VS
  1110. Sets the width of the outline of the polygon. If \fIpixels\fR is zero, 
  1111. no outline
  1112. is drawn. The default width is \fC0\fR.
  1113. .VE
  1114. .TP
  1115. \fB\-mapx \fItype\fR
  1116. Specifies which x-axis to map the tag's x-coordinates onto.
  1117. \fIType\fR must be either \fCx\fR, \fCx2\fR, or \fCboth\fR.  The default
  1118. axis is \fCx\fR.
  1119. .TP
  1120. \fB\-mapy \fItype\fR
  1121. Specifies which y-axis to map the tag's y-coordinates onto.
  1122. \fIType\fR must be either \fCy\fR, \fCy2\fR, or \fCboth\fR.  The default
  1123. axis is \fCy\fR.
  1124. .TP
  1125. \fB\-stipple \fIbitmap\fR
  1126. Indicates that the polygon should be drawn with a stippled pattern
  1127. rather than a solid color;
  1128. \fIbitmap\fR specifies the stipple pattern to use, in any of the
  1129. forms accepted by \fBTk_GetBitmap\fR.
  1130. If \fIbitmap\fR is the empty string (the default), then the polygon
  1131. is filled with a solid (foreground) color.
  1132. .TP
  1133. \fB\-xoffset \fIpixels\fR
  1134. Specifies an x-coordinate offset (in window coordinates)
  1135. from the specified position.  
  1136. The default offset is \fC0\fR.
  1137. .TP
  1138. \fB\-yoffset \fIpixels\fR
  1139. Specifies a y-coordinate offset (in window coordinates)
  1140. from the specified position. 
  1141. The default is offset \fC0\fR.
  1142. .sp 1
  1143. .SS "WINDOW TAGS"
  1144. A window tag displays a particular window at a given position on the graph.
  1145. Window tags are created with the widget command:
  1146. .DS
  1147. \fIpathName \fBtag create window \fR?\fIcoords\fR? ?\fIoptions...\fR?
  1148. .DE
  1149. The argument \fIcoords\fR specifies a list containing the graph
  1150. coordinates of a point used to position the window on the display 
  1151. After \fIcoords\fR, there may be any number of \fIoption\fR-\fIvalue\fR
  1152. pairs, each of which sets one of the configuration options
  1153. for the tag.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1154. used in the \fBtag configure\fR command to change the tag's
  1155. configuration.
  1156. The following options are supported for window tags:
  1157. .TP
  1158. \fB\-anchor \fIanchorPos\fR
  1159. \fIAnchorPos\fR tells how to position the window relative to the
  1160. positioning point for the window;  it may have any of the forms
  1161. accepted by \fBTk_GetAnchor\fR.  For example, if \fIanchorPos\fR
  1162. is \fCcenter\fR then the window is centered on the point;  if
  1163. \fIanchorPos\fR is \fCn\fR then the window will be displayed such that
  1164. the top center point of the rectangular region occupied by the
  1165. window will be at the positioning point.
  1166. This option defaults to \fCcenter\fR.
  1167. .TP
  1168. \fB\-element \fIname\fR
  1169. Associates the tag with the element \fIname\fR.  
  1170. If \fIname\fR is not the empty string, the tag is displayed 
  1171. only if \fIname\fR exists and is currently being displayed 
  1172. (see \fBelement show\fR).  
  1173. This option defaults to the empty string.
  1174. .TP
  1175. \fB\-height \fIpixels\fR
  1176. Specifies the height to assign to the tag's window.
  1177. If this option isn't specified, or if it is specified as the empty
  1178. string, then the window is given whatever height it requests internally.
  1179. .TP
  1180. \fB\-mapx \fItype\fR
  1181. Specifies which x-axis to map the tag's x-coordinates onto.
  1182. \fIType\fR must be either \fCx\fR, \fCx2\fR, or \fCboth\fR.  The default
  1183. axis is \fCx\fR.
  1184. .TP
  1185. \fB\-mapy \fItype\fR
  1186. Specifies which y-axis to map the tag's y-coordinates onto.
  1187. \fIType\fR must be either \fCy\fR, \fCy2\fR, or \fCboth\fR.  The default
  1188. axis is \fCy\fR.
  1189. .TP
  1190. \fB\-width \fIpixels\fR
  1191. Specifies the width to assign to the tag's window.
  1192. If this option isn't specified, or if it is specified as the empty
  1193. string, then the window is given whatever width it requests internally.
  1194. .TP
  1195. \fB\-window \fIpathName\fR
  1196. Specifies the window to be managed by the graph.
  1197. The window specified by \fIpathName\fR must be a child of
  1198. the \fBblt_graph\fR widget.
  1199. .TP
  1200. \fB\-xoffset \fIpixels\fR
  1201. Specifies an x-coordinate offset (in window coordinates)
  1202. from the specified position. 
  1203. The default offset is \fC0\fR.
  1204. .TP
  1205. \fB\-yoffset \fIpixels\fR
  1206. Specifies a y-coordinate offset (in window coordinates)
  1207. from the specified position.  
  1208. The default offset is \fC0\fR.
  1209. .sp 1
  1210. .SS "POSTSCRIPT OPTIONS"
  1211. The following options are valid for configuring PostScript output using either 
  1212. the \fBpostscript\fR or the \fBpsconfigure\fR command. 
  1213. .DS
  1214. \fIpathName \fBpostscript \fR?\fIfileName\fR? \fIoptions...\fR?
  1215.  
  1216. \fIpathName \fBpsconfigure ?\fIoptions...\fR?
  1217. .DE
  1218. .TP
  1219. \fB\-colormap \fIvarName\fR
  1220. \fIVarName\fR must be the name of a global array variable
  1221. that specifies a color mapping from the X color name to PostScript.
  1222. Each element of \fIvarName\fR must consist of PostScript
  1223. code to set a particular color value (e.g. ``\fC1.0 1.0 0.0 setrgbcolor\fR'').
  1224. When outputting color information in PostScript, it checks
  1225. to see if there is an element of \fIvarName\fR with the same
  1226. name as the color. If so, it uses the value of the element as the 
  1227. PostScript command to set the color.
  1228. If this option hasn't been specified, or if there isn't an entry
  1229. in \fIvarName\fR for a given color, then it uses the red, green,
  1230. and blue intensities from the X color.
  1231. .TP
  1232. \fB\-colormode \fImode\fR
  1233. Specifies how to output color information.  \fIMode\fR must be either
  1234. \fBcolor\fR (for full color output), \fCgray\fR (convert all colors
  1235. to their gray-scale equivalents) or \fCmono\fR (convert foreground colors
  1236. to black and background colors to white).  The default mode is \fCcolor\fR.
  1237. .TP
  1238. \fB\-fontmap \fIvarName\fR
  1239. \fIVarName\fR must be the name of a global array variable
  1240. that specifies a font mapping from the X font name to PostScript.
  1241. Each element of \fIvarName\fR must consist of a Tcl list with
  1242. one or two elements, which are the name and point size of a PostScript font.
  1243. When outputting PostScript commands for a particular font, Tk
  1244. checks to see if \fIvarName\fR contains an element with the same
  1245. name as the specified font. 
  1246. If there is such an element, then the font information contained in
  1247. that element is used in the PostScript output.  (If the point size 
  1248. is omitted from the list, the point size of the X font is used).
  1249. Otherwise the X font is examined in an attempt to guess what PostScript 
  1250. font to use.  This works only for fonts whose foundry property is
  1251. \fIAdobe\fR (such as Times, Helvetica, Courier, etc.).  If all of 
  1252. this fails then the font defaults to \fCHelvetica-Bold\fR.
  1253. .TP
  1254. \fB\-landscape \fIboolean\fR
  1255. If \fIboolean\fR is \fCtrue\fR, this specifies the printed area is to 
  1256. be rotated 90 degrees.
  1257. In non-rotated output the \f(BIx\fR axis of the printed area runs along
  1258. the short dimension of the page (``portrait'' orientation);
  1259. in rotated output the \f(BIx\fR axis runs along the long dimension of the
  1260. page (``landscape'' orientation).
  1261. Defaults to \fCfalse\fR.
  1262. .TP
  1263. \fB\-pageanchor \fIanchor\fR
  1264. Specifies which point of the printed area should be appear over
  1265. the positioning point on the page (which is given by the \fB\-pagex\fR
  1266. and \fB\-pagey\fR options).
  1267. For example, \fB\-pageanchor n\fR means that the top center of the
  1268. printed area should be over the positioning point.
  1269. Defaults to \fCnw\fR.
  1270. .TP
  1271. \fB\-pageheight \fIsize\fR
  1272. Specifies that the height of the graph drawn in PostScript.
  1273. The graph is \fInot\fR uniformly scaled since this also scales
  1274. the fonts.  \fISize\fR may be any value accepted by \fBTk_GetPixels\fR.
  1275. The resulting pixel value is then converted to postscript printer
  1276. points.  This means that a height \fI8i\fR will be properly
  1277. converted to 8 inches. This options defaults to the height of the graph window.
  1278. .TP
  1279. \fB\-pagewidth \fIsize\fR
  1280. Specifies that the width of the graph drawn in PostScript.
  1281. The graph is \fInot\fR uniformly scaled since this also scales
  1282. the fonts.  \fISize\fR may be any value accepted by \fBTk_GetPixels\fR.
  1283. The resulting pixel value is then converted to postscript printer
  1284. points.  This means that a width \fI6.5i\fR will be properly
  1285. converted to 6.5 inches. This options defaults to the width of the graph window.
  1286. .TP
  1287. \fB\-pagex \fIposition\fR
  1288. Specifies the x-coordinate of the page positioning point.
  1289. This (with the \fB-pageanchor\fR option) indicates 
  1290. where the graph is placed on the PostScript page.
  1291. \fIPosition\fR may be any value accepted by 
  1292. \fBTk_GetPixels\fR. The resulting pixel value is then converted to 
  1293. postscript printer points.  The default is \fC1i\fR.
  1294. .TP
  1295. \fB\-pagey \fIposition\fR
  1296. Specifies the y-coordinate of the page positioning point.
  1297. This (with the \fB-pageanchor\fR option) indicates 
  1298. where the graph is placed on the PostScript page.
  1299. \fIPosition\fR may be any value accepted by 
  1300. \fBTk_GetPixels\fR. The resulting pixel value is then converted to 
  1301. postscript printer points.  The default is \fC1i\fR.
  1302. .SH "SETTING DATA FROM C"
  1303. The data points of any element can be reset from a C routine using
  1304. the convenience function \fBBlt_GraphElement\fR.  This can be useful
  1305. in situations where it is too expensive to translate the data values
  1306. from string representations.  Another possible use could be to read in
  1307. special data file formats.
  1308. .sp 1
  1309. .nf
  1310. \fCint Blt_GraphElement(interp, pathName, elemName, numValues, valueArr)
  1311.     Tcl_Interp *interp;         /* Interpreter of the graph widget */
  1312.     char *pathName;             /* Path name of the graph widget */
  1313.     char *elemName;             /* Name of the element to reset */
  1314.     int numValues;              /* Number of values in array */
  1315.     double *valueArr;           /* Array of x,y coordinate pairs */
  1316. \fR
  1317. .fi
  1318. The interpreter must be the same as the one containing the graph
  1319. widget and both the graph and the element specified must 
  1320. already exist.
  1321. The data array must contain pairs of x,y coordinates.  The number
  1322. specified is the total number values in this array.  The data values 
  1323. in the array are copied into the graph widget for that element.
  1324. You don't need to worry about allocating space for them.
  1325. .PP
  1326. \fBBlt_GraphElement\fR will return TCL_OK if successful.
  1327. The graph will be redrawn with the new data points at the next idle point.
  1328. Otherwise it returns TCL_ERROR and "\fCinterp->result\fR"
  1329. will contain an error message.  
  1330. .SH BINDINGS
  1331. There are no default bindings. 
  1332. .SH BUGS
  1333. Auto-scale routines do not use requested min/max limits
  1334. as boundaries when the axis is logarithmically scaled.  
  1335. .PP
  1336. The needs to be a special mapping for undefined log scale values (>= 0.0). 
  1337. Possibly set up a "red zone" of undefined values which divides the 
  1338. positive and negative values.
  1339. .PP
  1340. The PostScript output generated for polygons with more than 1500 points 
  1341. may exceed the limits of some printers (See PostScript Language Reference 
  1342. Manual, page 568).  The work-around is to break the polygon into
  1343. separate pieces.
  1344. .SH KEYWORDS
  1345. graph, widget
  1346.