HistographDoc.tioga
Copyright Ó 1986 by Xerox Corporation. All rights reserved.
Russ Atkinson (RRA) May 22, 1986 7:19:38 pm PDT
HISTOGRAPH
CEDAR 6.1 —
Histograph
-- a strip-chart Viewer class
Russ Atkinson
© Copyright 1986 Xerox Corporation. All rights reserved.
Abstract: A Histograph viewer displays a history graph of samples. Each sample is displayed as a one-pixel wide vertical bar. A Histograph viewer can be either a top-level viewer or an embedded viewer. A Histograph viewer can be historical, as with a strip-chart, or random access, as with a histogram.
Created by: Russ Atkinson
Maintained by: Russ <Atkinson.pa>
Keywords: histograph, strip chart, Viewers
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304

Introduction
A Histograph viewer displays a history graph of samples.
If historical = TRUE, then samples can be added (via AddSample) at any time and by any process (the data is properly monitorized). Each sample is added at the next X position. Only the most recent samples are displayed. Samples "older" than dataWidth are lost, and cannot be displayed regardless of the viewer width.
If historical = FALSE, then samples can be added (via StoreSample & ModifySample) at any time and by any process (the data is properly monitorized). The viewer is always wide enough to accomodate dataWidth samples.
The X-axis is linear, one sample per pixel, and is not labelled beyond periodic tick marks (period selected by the client). The X-axis will expand or contract depending on dataWidth and the viewer size. If the parent is a Container and childXbound = TRUE, then the right edge of the Histograph viewer will track the right edge of the Container viewer.
The Y-axis is labelled with positive REAL numbers as specified by the client, and can be either linear or logarithmic. Samples are clipped as necessary. Regardless of the scale, if the sample is <= 0.0 it is not displayed, and if the sample is > 0.0 then at least one pixel is used. When the Y-axis is logarithmic (vertiLog > 1), the maxSample parameter is the number at the top of the axis, and every tickY pixels down a number that is a factor of vertiLog less is displayed.
The title and subtitle are displayed on the left, with the title on top, and the subtitle underneath and slightly indented. The title uses the large font, and the subtitle uses the small font. All numbers displayed use the number font. The top number at the left is the last sample added, and the number below it is the exponentially declining average for historical viewers, and the average of all of the points for non-historical viewers.
The procedure HistographImpl.Test demonstrates how a program might use Histograph viewers. The figure below was produced by the following calls:
HistographImpl.Test[44, 120, 60]
HistographImpl.Test[22, 30]
HistographImpl.Test[11, 10]
[Artwork node; type 'ArtworkInterpress on' to command tool]
The interface
General operations
NewHistograph: PROC [
dataWidth: NAT ← 480, -- # of samples buffered for display
dataHeight: NAT ← 100, -- # of vertical units for samples
maxSample: INT ← 100, -- sample corresponding to the height
averageFactor: REAL ← 0.9, -- used to compute declining average
vertiLog: NAT ← 0, -- log base to use on Y-axis (0, 1 => linear)
title: ROPE ← NIL, -- graph title
subTitle: ROPE ← NIL, -- graph sub-title
firstSampleX: NAT ← 64, -- x position of first sample
numberW: INTEGER ← 32, -- # of units for displaying numbers
name: ROPE ← NIL, -- name to use if top-level viewer
parent: Viewer ← NIL, -- parent viewer
wx: INTEGER ← 0, -- x position in parent
wy: INTEGER ← 0, -- y position in parent
historical: BOOL ← TRUE, -- => strip chart style, else random access
border: BOOL ← FALSE, -- => give returned viewer a border
childXbound: BOOL ← FALSE, -- => make right bound match parent
tickX: NAT ← 60, -- # of units to use between horizontal ticks
tickY: NAT ← 25, -- # of units to use between vertical ticks
numberFont: Font ← NIL, -- font for numbers (default: Helvetica8)
smallFont: Font ← NIL, -- font for subTitle (default: Helvetica8)
largeFont: Font ← NIL] -- font for title (default: Helvetica10)
RETURNS [Viewer];
... creates a new Histograph class of viewer.
FetchSample: PROC [viewer: Viewer, index: NAT] RETURNS [REAL];
Fetches the sample at the given index. Returns 0.0 if the sample was never written. Useful if using this viewer class as a histogram instead of as a strip chart.
Reset: PROC [viewer: Viewer, paint: BOOL ← TRUE];
Clears all of the data samples. If paint, also forks a paint update.
Historical operations (requires viewer created with historical: TRUE)
AddSample: PROC [viewer: Viewer, sample: REAL, paint: BOOL ← TRUE];
Adds a data sample to the histograph. Requires that the viewer was created with historical = TRUE, otherwise Error[$notHistorical] is raised. If paint, also forks a paint update.
Random access operations (requires viewer created with historical: FALSE)
StoreSample: PROC [viewer: Viewer, index: NAT, sample: REAL, paint: BOOL ← TRUE];
Stores the sample at the given index. Returns 0.0 if the sample was never written. Requires that the viewer was created with historical = FALSE, otherwise Error[$historical] is raised. If paint, also forks a paint update.
ModifySample: PROC [viewer: Viewer, index: NAT, sample: REAL, paint: BOOL ← TRUE];
Adds the sample to the sample at the given index. Requires that the viewer was created with historical = FALSE, otherwise Error[$historical] is raised. If paint, also forks a paint update.
Exceptions
Error: ERROR [code: ATOM, message: ROPE];
The error raised when certain preconditions are not met.