.ds f. AtBarchart.man .\" $Header: /afs/athena.mit.edu/astaff/project/atdev/spec/man/RCS/AtBarchart.man,v 3.1 91/01/03 18:22:06 crcraig Exp Locker: crcraig $ .\" Copyright (C) 1990 by the Massachusetts Institute of Technology .\" .TH AtBarchart 3X .SH NAME .B AtBarchart, AtFBarchart -- the Barchart object class .SH SYNOPSIS .B #include .SH DESCRIPTION The AtBarchart object displays 2-D barcharts in an AtPlotter widget. An arbitrary number of AtBarchart plots can be created with a single plotter widget as the parent. Each set of barcharts can have a distinct color and/or background pixmap. In addition, it is possible to incrementally update the barcharts when displaying dynamic data (i.e. without clearing the entire plotter widget and redrawing the axes and plots). Incremental updating, therefore, allows for smooth and flicker-free display of dynamically changing data in an efficient way. Incremental updating is enabled when the AtPlotter widget's XtNautoScale resource is False. .SH CLASSES The AtBarchart object is a subclass of AtPlotObject. The class pointer is atBarchartWidgetClass, and the class name is AtBarchart. The AtBarchart object is intended to be used as a child of the AtPlotter widget. .SH RESOURCES The AtBarchart widget inherits all the resources of the Object and AtPlot objects. In addition, it has the following new resources. .TS .if \n+(b.=1 .nr d. \n(.c-\n(c.-1 .de 35 .ps \n(.s .vs \n(.vu .in \n(.iu .if \n(.u .fi .if \n(.j .ad .if \n(.j=0 .na .. .nf .nr #~ 0 .if \n(.T .if n .nr #~ 0.6n .ds #d .d .if \(ts\n(.z\(ts\(ts .ds #d nl .fc .nr 33 \n(.s .rm 48 49 50 .nr 48 0 .nr 38 \w\f2Name\fP .if \n(48<\n(38 .nr 48 \n(38 .nr 38 \wXtNxMin .if \n(48<\n(38 .nr 48 \n(38 .nr 38 \wXtNxMax .if \n(48<\n(38 .nr 48 \n(38 .nr 38 \wXtNyPoints .if \n(48<\n(38 .nr 48 \n(38 .nr 38 \wXtNnumPoints .if \n(48<\n(38 .nr 48 \n(38 .nr 38 \wXtNdensity .if \n(48<\n(38 .nr 48 \n(38 .nr 38 \wXtNshading .if \n(48<\n(38 .nr 48 \n(38 .nr 38 \wXtNpattern .if \n(48<\n(38 .nr 48 \n(38 .nr 38 \wXtNposition .if \n(48<\n(38 .nr 48 \n(38 .48 .rm 48 .nr 49 0 .nr 38 \w\f2Type\fP .if \n(49<\n(38 .nr 49 \n(38 .nr 38 \wdouble .if \n(49<\n(38 .nr 49 \n(38 .nr 38 \wdouble .if \n(49<\n(38 .nr 49 \n(38 .nr 38 \wdouble * .if \n(49<\n(38 .nr 49 \n(38 .nr 38 \wint .if \n(49<\n(38 .nr 49 \n(38 .nr 38 \wdouble .if \n(49<\n(38 .nr 49 \n(38 .nr 38 \wBoolean .if \n(49<\n(38 .nr 49 \n(38 .nr 38 \wAtPattern .if \n(49<\n(38 .nr 49 \n(38 .nr 38 \wint .if \n(49<\n(38 .nr 49 \n(38 .49 .rm 49 .nr 50 0 .nr 38 \w\f2Default\fP .if \n(50<\n(38 .nr 50 \n(38 .nr 38 \w0.0 .if \n(50<\n(38 .nr 50 \n(38 .nr 38 \w1.0 .if \n(50<\n(38 .nr 50 \n(38 .nr 38 \wNULL .if \n(50<\n(38 .nr 50 \n(38 .nr 38 \w0 .if \n(50<\n(38 .nr 50 \n(38 .nr 38 \w1.0 .if \n(50<\n(38 .nr 50 \n(38 .nr 38 \wFalse .if \n(50<\n(38 .nr 50 \n(38 .nr 38 \wAtGRAY0 .if \n(50<\n(38 .nr 50 \n(38 .nr 38 \wAtPositionCENTER .if \n(50<\n(38 .nr 50 \n(38 .50 .rm 50 .nr 38 \w\f3AtBarchart Resources\fP-\n(48-3n-\n(49-3n-\n(50 .if \n(38>0 .nr 38 \n(38/2 .if \n(38<0 .nr 38 0 .nr 49 +\n(38 .nr 50 +\n(38 .nr 38 1n .nr 47 0 .nr 40 \n(47+((0*\n(38)/2) .nr 48 +\n(40 .nr 41 \n(48+((6*\n(38)/2) .nr 49 +\n(41 .nr 42 \n(49+((6*\n(38)/2) .nr 50 +\n(42 .nr TW \n(50 .if t .if (\n(TW+\n(.o)>7.65i .tm Table at line 50 file AtBarchart.man is too wide - \n(TW units .nr #I \n(.i .in +(\n(.lu-\n(TWu-\n(.iu)/2u .fc   .nr #T 0-1 .nr #a 0-1 .eo .de T# .nr 35 1m .ds #d .d .if \(ts\n(.z\(ts\(ts .ds #d nl .mk ## .nr ## -1v .ls 1 .ls .. .ec .ta \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'\f3AtBarchart Resources\f\n(31 .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'\f2Name\f\n(31\h'|\n(41u'\f2Type\f\n(31\h'|\n(42u'\f2Default\f\n(31 .sp .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'XtNxMin\h'|\n(41u'double\h'|\n(42u'0.0 .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'XtNxMax\h'|\n(41u'double\h'|\n(42u'1.0 .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'XtNyPoints\h'|\n(41u'double *\h'|\n(42u'NULL .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'XtNnumPoints\h'|\n(41u'int\h'|\n(42u'0 .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'XtNdensity\h'|\n(41u'double\h'|\n(42u'1.0 .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'XtNshading\h'|\n(41u'Boolean\h'|\n(42u'False .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'XtNpattern\h'|\n(41u'AtPattern\h'|\n(42u'AtGRAY0 .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'XtNposition\h'|\n(41u'int\h'|\n(42u'AtPositionCENTER .fc .nr T. 1 .T# 1 .in \n(#Iu .35 .TE .if \n-(b.=0 .nr c. \n(.c-\n(d.-16 .IP XtNxMin Specifies the first bar's position on the X axis. .IP XtNxMax Specifies the last bar's position on the X axis. Together xMin and xMax specify the range of the X values, therefore avoiding the need to pass an array of X values. .IP XtNyPoints An array of Y coordinates for the Barchart plot. Each coordinate corresponds to a bar (i.e. the bar's "height"). .IP XtNnumPoints Specifies the number of bars in a set. There are bars, equally spaced in the XtNxMin to XtNxMax range. .IP XtNdensity Controls the thickness of the plot's bars. Valid values are between 0.0 and 1.0, inclusive. If set to 0.0, each bar looks like a straight line. As this resource is increased, each bar becomes wider. If set to 1.0, each bar's rightmost edge will touch its set's next immediate neighbor's leftmost edge. .IP XtNshading If set to True, all bars will be filled with the pattern specified in XtNpattern (useful on monochrome displays). In addition, color can be specified if using a color display. .IP pattern A predefined set of six patterns (pixmaps) to use if XtNshading is True. Valid values are AtGRAY0, AtGRAY1, AtGRAY2, AtGRAY3, AtGRAY4, and AGtRAY5. AtGRAY0 is the lightest shade of gray, progressing to the darkest shade of AtGRAY5. If this resource is specified from a resource file, omit the leading 'At'. This resource is ignored if XtNshading is False. .IP XtNposition Controls positioning of the bars on the axis. If set to AtPositionCENTER, it positions each bar such that it is centered on its corresponding X value (or Y value, if in a horizontal barchart). If set to AtPositionLEFT, each bar is positoned such that its rightmost edge is on its corresponding X value. If set to AtPositionRIGHT, each bar is positoned such that its leftmost edge is on its corresponding X value. .sp .SH NAME .B AtFBarchart -- the FBarchart object class .SH SYNOPSIS .B #include .SH DESCRIPTION The AtFBarchart object is a specialized form of the AtBarchart object which gets its data from a file (or maybe a socket, in the future) specified by the user. The user does not need to specify the numPoints resource, when using FBarchart. .SH CLASSES The AtFBarchart object is a subclass of AtBarchart, which is an Xt object. The class pointer is atFBarchartWidgetClass, and the class name is AtFBarchart. The AtFBarchart object is intended to be used as a child of the AtPlotter widget. .SH RESOURCES The FBarchart widget inherits all the resources of AtBarchart, AtPlot, and Object. In addition, it has the following new resource. .TS .if \n+(b.=1 .nr d. \n(.c-\n(c.-1 .de 35 .ps \n(.s .vs \n(.vu .in \n(.iu .if \n(.u .fi .if \n(.j .ad .if \n(.j=0 .na .. .nf .nr #~ 0 .if \n(.T .if n .nr #~ 0.6n .ds #d .d .if \(ts\n(.z\(ts\(ts .ds #d nl .fc .nr 33 \n(.s .rm 48 49 50 .nr 48 0 .nr 38 \w\f2Name\fP .if \n(48<\n(38 .nr 48 \n(38 .nr 38 \wXtNdataFile .if \n(48<\n(38 .nr 48 \n(38 .48 .rm 48 .nr 49 0 .nr 38 \w\f2Type\fP .if \n(49<\n(38 .nr 49 \n(38 .nr 38 \wString .if \n(49<\n(38 .nr 49 \n(38 .49 .rm 49 .nr 50 0 .nr 38 \w\f2Default\fP .if \n(50<\n(38 .nr 50 \n(38 .nr 38 \wNULL .if \n(50<\n(38 .nr 50 \n(38 .50 .rm 50 .nr 38 \w\f3AtFBarchart Resources\fP-\n(48-3n-\n(49-3n-\n(50 .if \n(38>0 .nr 38 \n(38/2 .if \n(38<0 .nr 38 0 .nr 49 +\n(38 .nr 50 +\n(38 .nr 38 1n .nr 47 0 .nr 40 \n(47+((0*\n(38)/2) .nr 48 +\n(40 .nr 41 \n(48+((6*\n(38)/2) .nr 49 +\n(41 .nr 42 \n(49+((6*\n(38)/2) .nr 50 +\n(42 .nr TW \n(50 .if t .if (\n(TW+\n(.o)>7.65i .tm Table at line 130 file AtBarchart.man is too wide - \n(TW units .nr #I \n(.i .in +(\n(.lu-\n(TWu-\n(.iu)/2u .fc   .nr #T 0-1 .nr #a 0-1 .eo .de T# .nr 35 1m .ds #d .d .if \(ts\n(.z\(ts\(ts .ds #d nl .mk ## .nr ## -1v .ls 1 .ls .. .ec .ta \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'\f3AtFBarchart Resources\f\n(31 .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'\f2Name\f\n(31\h'|\n(41u'\f2Type\f\n(31\h'|\n(42u'\f2Default\f\n(31 .sp .ta \n(48u \n(49u \n(50u .nr 35 1m .nr 31 \n(.f \&\h'|\n(40u'XtNdataFile\h'|\n(41u'String\h'|\n(42u'NULL .fc .nr T. 1 .T# 1 .in \n(#Iu .35 .TE .if \n-(b.=0 .nr c. \n(.c-\n(d.-9 .IP XtNdataFile The file name which contains the data (the Y values). Each Y value is expected to be on a line by itself (end with newline character). .SH "PUBLIC ROUTINES" .nf .nj void ReadFile (AtFBarchartWidget) .fi .IP ReadFile() Initially opens and reads the given data file, during the widget's creation time. Subsequently, each time the contents of the file change, the user can call this function which will reread the file and updates the bars if there were changes. This function gets called automatically, if the file name changes. .SH BEHAVIOR .SH Actions None. .SH Default Translations None. .SH STATUS Barchart and FBarchart widgets are available in the At library. The XtNposition resource is not functional yet. For now it uses the default center position. To cover the case of overlapping or partially overlapping barcharts two new resources have been added to the Plotter widget and the Plot object. The Plotter widget now has a resource called "rankChildren" (set to false by default). This resource affects the order by which children of the plotter are drawn (in the case of exposures or incremental updates, for instance). By default the children are drawn in the order that they are created. Another words, by default the first child created is alway drawn first and the second child is drawn next, ..., and the last child is drawn last. Therefore, in the case of overlapping barcharts, the first child is always covered by its sibling, and the last child is always on top of all its siblings. By seting the "rankChildren" resource of the Plotter widget to True, You can tell the Plotter widget to draw its children in the order that you specify, rather than the order that they were created. This would allow you to control which set of barcharts will be on top, which on bottom, and which in the middle, at any given time. To do this you first set the "rankChildren" resource of the plotter widget to True, then you assign a ranking to each of the Barchart children, by setting the "rankOrder" resource of the Plot object to an integer. This should be done for each Barchart child. The child with the highest ranking will be drawn last and therefore covers all its siblings (in the case of overlapping barcharts), and the child with the lowest ranking will always be drawn first, and therefore in the bottom (in the case of overlapping barcharts). .SH "TO DO" Postscript output, horizontal barcharts, XtNposition resource. .SH "SEE ALSO" AthenaTools(3), AtPlotter, AtPlot, AtXYPlot. .SH BUGS .SH AUTHOR Kambiz Soroushian (MIT Project Athena), Chris Craig (MIT Project Athena) .SH COPYRIGHT Copyright (C) 1990 by the Massachusetts Institute of Technology Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting. WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.