[_CD4_]<datools7.0>PlotGraph>PlotGraph.mesa!2

PlotGraph.mesa

Barth, August 25, 1986 12:11:02 pm PDT

Christian Le Cocq May 12, 1987 6:58:38 pm PDT

DIRECTORY

Imager, Vector2, ViewerClasses;

PlotGraph: CEDAR DEFINITIONS = BEGIN

Theory

This interface is used to display a collection of graphs on a collection of axis within one viewer. A graph is a set of point pairs relating x and y values. Color is used to differentiate multiple graphs on a single axis. Line styles can be used to simulate color on a black and white display. The axis are laid out within the viewer in a single vertical column. The plot coordinate system, which has [0.0, 0.0] in the lower left corner and [1.0, 1.0] in the upper right corner, is used to specify locations which are not relative to an axis.

This interface provides a procedural mechanism for enumerating the points of a graph so that client code can make appropriate space-time tradeoffs. Note that this burdens the client with enforcing synchronization constraints.

Types

ROPE: TYPE = Imager.ROPE;

VEC: TYPE = Imager.VEC; --maps into Vector2.VEC TYPE = RECORD [x, y: REAL]

Rectangle: TYPE = Imager.Rectangle; -- x, y, w, h

AxisList: TYPE ~ LIST OF Axis;

GraphList: TYPE ~ LIST OF Graph;

Viewer: TYPE ~ ViewerClasses.Viewer;

WorldRectangle: Rectangle = [0.0, 0.0, 0.0, 0.0];

XY: TYPE = {X, Y};

Plot: TYPE = REF PlotRec;

PlotRec: TYPE = RECORD [

private: PlotGraphPrivate ← NIL,

selection: LIST OF REF ANY ← NIL,

Union[Axis, Graph, GraphPoint, PlotText]

axis: AxisList ← NIL, -- in order from bottom to top

texts: LIST OF PlotText ← NIL,

lowerBounds: VEC, -- Min all X, Min all Y,

upperBounds: VEC, -- Max all X, Max all Y over all graphs

eventProc: EventProc ← NIL, -- To interprete events unknown by the NotifyProc

data: REF ANY ← NIL -- Client data.

];

EventProc: TYPE = PROC [

plot: Plot, -- the clicked Plot

axis: Axis, -- the clicked Axis (could be # of the selected Axis)

pos: VEC, -- client coordinates of the mouse, if available.

event: ATOM -- Atom specified by the Tip table

];

PlotGraphPrivate: TYPE = REF PlotGraphPrivateRec;

PlotGraphPrivateRec: TYPE = RECORD [

viewer: Viewer, -- the Viewer used for the display

locked: BOOL ← FALSE, -- the Plot is protected through a CONDITION,

unlocked: CONDITION -- rather than through a monitor lock.

];

Axis: TYPE = REF AxisRec;

AxisRec: TYPE = RECORD[

graphs: GraphList ← NIL,

bounds: Rectangle,

style: DrawingStyle ← analog,

maxChars: NAT ← 8, -- used to determine the heigth of the hexaV style row

axisData: ARRAY XY OF AxisData];

AxisData: TYPE = RECORD[

ticks: REAL ← 1.0,

visible: BOOL ← TRUE -- draw axis itself

];

DrawingStyle: TYPE = {

analog, -- draws a segment between each point

mark, -- draws a segment between each point, and marks the point

hexaH, -- writes the rope provided or the hexadecimal value of y horizontally

hexaV -- writes the rope provided or the hexadecimal value of y vertically

};

GraphClass: TYPE = REF GraphClassRec;

GraphClassRec: TYPE = RECORD[

insert: GraphProc ← NIL,

delete: GraphProc ← NIL,

enumerate: GraphEnumerateProc ← NIL];

GraphProc: TYPE = PROC [graph: Graph, x, y: REAL];

GraphEnumerateProc: TYPE = PROC [plot: Plot, graph: Graph, bounds: Rectangle, eachPoint: PointProc] RETURNS [invalidEnumeration: BOOL ← FALSE];

The bounding rectangle is a hint to the enumeration indicating which points will really be used. eachPoint must be called for each of the points in the graph which bracket or are contained in the bounds. Points outside the bounds may also be passed to eachPoint. The implementation does a moveto for the first point and a drawto for the rest of them. If invalidEnumeration is TRUE this indicates that the data in the backing data structure has changed in such a way as to invalidate the points already enumerated. The axis will be erased and all of the graphs on the axis will be redrawn.

PointProc: TYPE = PROC [x, y: REAL, rope: ROPE ← NIL] RETURNS [quit: BOOL ← FALSE];

x and y are, of course, relative to the axis upon which the graph is currently being drawn. If rope is specified then rope will be printed on the "hexa" style axis at location [x, 0.0]. If not, the value printed will be Convert.RopeFromInt[Real.Fix[y], 16, FALSE] i.e. the transcription of y in hexadecimal; rope is ignored on analog axis. If quit is true then the enumeration should be stopped.

Graph: TYPE = REF GraphRec;

GraphRec: TYPE = RECORD[

data: REF ANY ← NIL,

mark: BOOL ← FALSE];

GraphPoint: TYPE = REF GraphPointRec;

GraphPointRec: TYPE = RECORD[

graph: Graph,

x, y: REAL];

PlotText: TYPE = REF PlotTextRec;

PlotTextRec: TYPE = RECORD[

contents: ROPE ← NIL,

wrt: Axis ← NIL, -- if nil then wrt entire plot

bounds: Rectangle, -- w or h = 0.0 mean use bounding box of ROPE

rotation: REAL ← 0.0, -- angle of rotation, ccw, in degrees

justifyX: JustifyX ← left,

justifyY: JustifyY ← bottom];

JustifyX: TYPE = {left, center, right};

JustifyY: TYPE = {top, center, bottom};

Operations

CreatePlot: PROC [name: ROPE ← NIL] RETURNS [plot: Plot];

Creates a new viewer. The name of the plot is immutable.

Client must lock a plot prior to changing the data structures so that interactive updates will be suspended.

LockPlot: PROC [plot: Plot];

UnlockPlot: PROC [plot: Plot];

RefreshPlot: PROC [plot: Plot, axis: AxisList ← NIL, graphs: GraphList ← NIL, within: Rectangle ← WorldRectangle, eraseFirst: BOOL ← FALSE];

Call this to update the display. If either graphs or axis are not NIL then only the indicated graph and/or axis will be refreshed. within will be passed to the GraphProcs as the bounding rectangle and so should include the point to which a moveto must be done to setup for drawing. Generally eraseFirst should only be TRUE if previously enumerated points have been changed.

DeletePlot: PROC [plot: Plot];

Makes the viewer disappear.

Interaction

General

DeleteSelection: PROC [plot: Plot];

Delete the current selection.

Axis

SelectAxis: PROC [plot: Plot, axis: Axis];

Deselect all current selections and then select the axis.

AddAxis: PROC [plot: Plot, axis: Axis];

Add the axis to the selection.

GetSelectedAxis: PROC [plot: Plot] RETURNS [axis: Axis];

Returns last selected axis.

GetSelectedAxisList: PROC [plot: Plot] RETURNS [axisList: LIST OF Axis];

Returns currently selected axis.

Various proc to edit a plot Axis List. DO NOT INSERT THE SAME AXIS TWICE (even in two plots).

InsertAxis: PROC [plot: Plot, axis, after: Axis];

DeleteAxis: PROC [plot: Plot, axis: Axis];

MoveAxis: PROC [plot: Plot, axis, after: Axis];

XChangeAxis: PROC [plot: Plot, axis1, axis2: Axis];

CopyAxis: PROC [axis: Axis] RETURNS [duplicate: Axis];

ForkAxis: PUBLIC PROC [plot: Plot, axis: Axis];

MoveGraphInAxis: PUBLIC PROC [plot: Plot, axis: Axis, graph: Graph];

NormalizeScaleAndOrigin: PUBLIC PROC [plot: Plot] RETURNS[unit: REAL];

unit is 1, 2 or 5 times a power of ten in client x coordinates, which are supposed to be coherent all over the graphs.

Graph

SelectGraph: PROC [plot: Plot, graph: Graph];

Deselect all current selections and then select the graph.

AddGraph: PROC [plot: Plot, graph: Graph];

Add the graph to the selection.

GetSelectedGraph: PROC [plot: Plot] RETURNS [graph: Graph];

Returns currently selected graph. Complains on terminal if none or more than one selected.

GetSelectedGraphList: PROC [plot: Plot] RETURNS [graphList: LIST OF Graph];

Returns currently selected graphs. Complains on terminal if none selected or some selection is not a graph.

Graph Point

SelectPoint: PROC [plot: Plot, point: GraphPoint];

Deselect all current selections and then select the given point on the graph.

AddPoint: PROC [plot: Plot, point: GraphPoint];

Add the point to the selection.

GetSelectedPoint: PROC [plot: Plot] RETURNS [point: GraphPoint];

Returns currently selected point. Complains on terminal if none or more than one selected.

GetSelectedPointList: PROC [plot: Plot] RETURNS [pointList: LIST OF GraphPoint];

Returns currently selected points. Complains on terminal if none selected or some selection is not a point.

InsertPoint: PROC [graph: Graph, x, y: REAL] RETURNS [ok: BOOL ← TRUE];

Adds the point to the graph. Not all classes support insertion and so ok may be false. An appropriate complaint will be sent to the terminal.

DeletePoint: PROC [graph: Graph, x, y: REAL] RETURNS [ok: BOOL ← TRUE];

Deletes the point from the graph. Not all classes support deletion and so ok may be false. An appropriate complaint will be sent to the terminal.

Text

SelectText: PROC [plot: Plot, text: PlotText];

Deselect all current selections and then select the text.

AddText: PROC [plot: Plot, text: PlotText];

Add the text to the selection.

GetSelectedText: PROC [plot: Plot] RETURNS [text: PlotText];

Returns currently selected text. Complains on terminal if none or more than one selected.

GetSelectedTextList: PROC [plot: Plot] RETURNS [textList: LIST OF PlotText];

Returns currently selected texts. Complains on terminal if none selected or some selection is not a text.

MoveText: PROC [plot: Plot, text: PlotText, position: Imager.VEC];

Moves the text.

RotateText: PROC [plot: Plot, text: PlotText, alpha: REAL];

Rotates the text.

END.

Christian LeCocq August 11, 1986 5:37:16 pm PDT

Changed the Plot.name to be a REF READONLY ROPE to take care of the instability of life. I need to know the name at viewer creation.

changes to: Plot.name, CreatePlot[name]

added a field named "data" to the enumeration proc to ease the sharing of the "leaves" of the call tree beetween the screen procs and the interpress procs and avoid global variables.

changes to: GraphClass

Christian LeCocq October 17, 1986 3:26:07 pm PDT

Added the possibility to send back to the client the events notified to the viewer but not understood by its NotifyProc. Added the lock mechanism to Plot.private., InsertAxis, DeleteAxis, MoveAxis, XChangeAxis, CopyAxis