Object Type:	xview

Description:	Object for displaying large numbers of numerical values
	graphically. Xview can be thought of as an array of xvars, though it
	uses much less memory than multiple xvars would. It also provides
	many more features for accessing the fields and messages of groups
	of elements.  Xview is subclassed from pix and can only be displayed
	in coredraw or its subclasses.

	Xview displays multiple 'points' in space, each behaving rather like
	an xvar.  Each 'point' in xview usually represents a single entity
	in the simulation, such as a compartment.

	Each 'point' in xview can be clicked to select, and the 'value'
	field of the xview will be set according to the 'valuemode'. By
	default the 'valuemode' is set to "path", so a click action will
	place the path of the element represented by the clicked point in
	xview into the 'value' field. Alternative valuemodes are "index",
	which returns the index of clicked point in the internal xview list;
	and "lookup", which looks up the value displayed for the clicked
	point.

	Values in xview are specified in three ways.

	- First, one can set the 'values' array directly (e.g., using the set
	command). Note that 'values' is 2-dimensional in xview.

	- Second, one can send up to 5 messages (VAL1, VAL2, VAL3, VAL4,
	VAL5), for each point. The points themselves must be previously
	specified using the COORDS message. It is assumed that the order of
	sending the COORDS messages is identical to the order of sending the
	values.  This is guaranteed if a wildcard list is used to set up the
	messages.  This method is recommended for all dynamic displays, as
	it is far and away the most efficient. The use of messages also
	enables displays on parallel machines.

	- Third, one can specify 'path' for looking up the coords. 'path' is
	usually a wildcard list of elements.  'relpath' is used for finding
	the actual elements containing the fields, relative to the coords.
	This is NOT a wildcard list. If no relpath is used, it can be set to
	"" or ".".  Only two values can be displayed in this mode, using
	'field' and 'field2'. 

	In addition, one can set 'field' to one of "msgout" or "msgin". If
	these options are selected, one can view values that are contained
	in messages. The 'msgpath' is a wildcard list of elements connected
	to the 'path' by the message type specified in 'msgtype'. The
	direction of the messages is specified, as mentioned above, by
	'field'. The view looks for the first message that satisfies all the
	above criteria for each coordinate, and displays the appropriate
	value. If it fails to find a suitable message the value becomes 0.
	This option enables one to display connectivity patterns in a
	network.  Using 'path' and its related options for displaying values
	is the most flexible option, and the slowest. Connections can only be
	displayed using this option. It is recommended for static displays
	such as during setup.

	The display options outlined below are essentially identical to
	the 'xvar' widget. 

	The following parameters of the graphical display can be
	used to display values in xview:
		1. Color
		2-4. x,y and z offsets
		5. Coordinates (morphing)
		6. Line thickness. *
		7. Text color *
		8. Text
		9. Minigraph. *
		10. Surface *
		11. Contour *
	* Not yet available.
	Any or all of the display parameters can in principle be used to 
	simultaneously display values pertaining to each point.
	In practice it gets rather confusing if more than 2 or 3 are
	used at a time.
	The color_val, xoffset_val, morph_val etc.
	fields are used to bind the message number to the specified
	display variable. Thus setting color_val to 1 means that
	message VAL1 will be used to control the color of the xview pix.
	By default all _vals are set to 0, which disables them.

	The xview pix displays values (except text and minigraph) by linear 
	interpolation. Every xview has at least two child elements of class
	xshape, named shape[0], shape[1], etc. These shapes determine the
	extreme points for the linear interpolation. Therefore if shape[0]
	has foreground color 0, and shape[1] has color 10, the range of
	colors displayed would be interpolated between 0 and 10. Likewise,
	if shape[0] displays a tall thin rectangle, and shape[1] a short
	wide rectangle, the shapes displayed would be 'morphed' between
	these two extremes. Of course, to get these effects one would have
	to set the color_val and morph_val to the appropriate values.
	In addition to the shapes themselves, three arrays are used to specify
	how the xview does interpolation. As already mentioned, the 'values'
	array specifies the actual values to be displayed. 'value_min'
	contains the values that correspond to the lower end of the 
	interpolated range. Thus if value[0][0] was equal to value_min[0],
	the parameter displayed would correspond to shape[0]. Likewise,
	value_max contains the upper end of the interpolated range.

	One can have multiple xshapes. In this case the interpolation first
	decides which pair of shapes to use. In this version, each pair of
	shapes handles an equal range between value_min and value_max.
	Having selected the appropriate pair of shapes, the algorithm then
	proceeds as outlined above.

	The 'text' option simply prints out the floating point value of the
	appropriate message. The 'minigraph' option (which will be
	implemented one of these days) displays a little graph of the 
	value, without any optional extras like axes.

	By default, the xview object is created along with two child shapes,
	shape[0] and shape[1]. The default shapes are squares, shape[0] being
	a small one with color 0 and shape[1] a big (1x1) square in color 63.
	The child shapes can have parameters set in the usual ways, but are
	not displayed independently of the xview pix. For the technically
	minded, this is because their pixflags have been set to visible_not.

	Note on 'morphing': Morphing in the xview pix is simply linear
	interpolation between corresponding points. When one shape has a 
	different number of points from the other, then the algorithm
	assumes that the missing points are [0,0,0] and does interpolation
	accordingly. This may lead to peculiar effects, so usually one
	uses the same number of points in all xshapes.

	Note on 'value_min' and 'value_max' arrays: The same min and max
	apply to all points in an xview. At this time autoscaling has
	not been implemented, but this should be easy.

Author:		Upi Bhalla Caltech Dec 93

-----------------------------------------------------------------------------

ELEMENT PARAMETERS

DataStructure:	xview_type [in src/Xodus/draw/xview_struct.h]

Size:		?	Depends on number of associated shapes and number of
			points being displayed.


Fields:
	The following fields are the same as for xvar:
		fg	Foreground color of view.
		script	Script operation(s) to perform on a mouse
			click. The script calls of the view are only made
			if the draw determines that the view is the nearest
			to the event and if the event occurred within the
			bounding region of the view. 
		tx	Transposition distance in the x dimension. The
			view is transposed (ie, displaced, offset) by this
			amount.
		ty	Transposition in y.
		tz	Transposition in z.
		pixflags	Set of flags specifying visibility,
			refreshes, mouse sensitivity and many other options.
			Use the 'pixflags' utility function to find out more.

		viewmode	Specifies the mode of operation of the
				xview. Can be one of:
			shape - Does interpolation between shapes
			graph - draws a minigraph (Not yet implemented)
			surface - Draws a plane in 3-d, specified by 3
					points in space (not yet implemented)
			contour - Draws contour lines for a plane in 3-d. NYI.
			colorview - Backwards compatibility hack. Uses 'shape'
				  mode to display boxes of different color. 
			boxview - Backwards compatibility hack. Uses 'shape'
				  mode to display boxes of different sizes. 
			colorboxview - Backwards compatibility hack. Default
				  viewmode. Uses 'shape' mode to display VAL1
				  using both the morph and color modes for
				  a box.
			fillboxview - Backwards compatibility hack. Uses
				'shape' mode to display filled boxes of
				different sizes. 
		value_min 	1-d array with lower limits for shape
				  parameters.
		value_max	1-d array with upper limits for shape
				  parameters.
		values		2-d array with display values.
		color_val	Specifies message to use for color
				  display values. 0=disabled is default.
				  If you wish to cause view to change
				  colors, use color_val.
		morph_val	Specifies message to use for morphing.
				  If you wish to have the view change
				  shape, use morph_val.
		xoffset_val	Specifies message to use for xoffset.
				  If you wish to cause a view to
				  bounce around on the screen, 
				  use the offset_vals.
		yoffset_val	Specifies message to use for yoffset.
		zoffset_val	Specifies message to use for zoffset.
		text_val	Specifies message whose value should
				  be printed out.
		textcolor_val	Specifies message which determines
				  the color of the text.
		linethickness_val  Specifies message determining the
				  line thickness used in the view.
		sizescale	Rescales all the shapes. The default
				  shapes have a size of 1.

	The following fields are new for xview:
		xpts		1-d array with x-coordinates of points.
				This is automatically set if the 'path' field
				is set, or if COORD messages are present.
		ypts		1-d array with y-coordinates of points.
				This is automatically set if the 'path' field
				is set, or if COORD messages are present.
		zpts		1-d array with z-coordinates of points.
				This is automatically set if the 'path' field
				is set, or if COORD messages are present.
		ncoords		Number of points.
				This is automatically set if the 'path' field
				is set, or if COORD messages are present.
		autoscale	Flag for determining if the xview should
				calculate value_min and max by itself. Options:
				0 = off. 1 = max ever reached. 2 = max current.
				(Not Yet Implemented)
		undraw_by_blanking 
				Flag for deciding if the xview should clear
				the whole display every step for redrawing.
				This may be faster in some cases, but may also
				leads to flicker. 
				(Not Yet Implemented)
		path		Wildcard path for elements specifying
				coordinates. (xpts, ypts and zpts)
		relpath		Relative path for child elements off 'path',
				determining where the fields are located.
		field		Name of field to display. Can have the
				special values "msgin" or "msgout".
		field2		An extra field to display. Cannot have
				"msgin" or "msgout"
		msgpath		Wildcard path for elements connected via
				msgs to 'path'. Only used for "msgin" or
				"msgout" modes of 'field'.
		msgtype		Specifies type of msgs to display.
		msgslotno	Specifies slot number of msgs to display.
                value           Set by a click action, according to valuemode.
		valuemode	Specifies how xview fills the 'value' field
				when a click event occurs on the view. 
				Can be one of "path"; "index"; "lookup"
				Default = "path".
				path: Finds the path of the element represented
					at the click site
				index: Returns the internal xview 
					index of the click site
				lookup: Returns the value displayed at
					the click site from values[0].

----------------------------------------------------------------------------

SIMULATION PARAMETERS

Function:	XVar [in src/Xodus/draw/xview.c]

Classes:	gadget output

Actions:	PROCESS: Redo interpolation and display.
		RESET:	Required when changing child xshapes,
			looks up coordinates.
		CREATE: Automatically creates 2 child xshapes.
		XUPDATE: update internal fields when
			displayed widget is changed.
		B1DOWN:	Invoked when mouse Button 1 is pressed.
		B2DOWN:	Invoked when mouse Button 2 is pressed.
		B3DOWN:	Invoked when mouse Button 3 is pressed.
		ANYBDOWN:	Invoked when any mouse button is pressed.
		B1DOUBLE: Invoked on a double click on mouse button 1.
		B2DOUBLE: Invoked on a double click on mouse button 2.
		B3DOUBLE: Invoked on a double click on mouse button 3.
		XOCOMMAND: an action that can invoke the functions
			in the 'script' field
		XODROP: Called when a another pix is dropped onto this one.
		XODRAG: Called when the mouse is clicked on this pix, and
			the mouse moves while the mouse button is held down.
		XOWASDROPPED: Called after this pix has been dropped onto
			another one.

Messages:	VAL1 data
		VAL2 data
		VAL3 data
		VAL4 data
		VAL5 data

		All messages can contain values for any display parameter.
			
----------------------------------------------------------------------------

Notes:		Can only be displayed in a coredraw widget subclass.
		The xview performs the interpolation between shapes and
		redraws them on every clock tick.

Examples:	
//=================================CUT HERE=================================

//genesis
//
// This example demonstrates how xview can use the fields
// 'path', 'field' and 'field2' to display a combination of message
// values and field values. Note how the
// color of the boxes (displaying msgin) in the view display is
// related to the size of the boxes (displaying the 'output' field
// of the tables) preceding them.
//
int side = 10

xcolorscale rainbow2
create xform /form [0,0,500,550]
xshow /form
create xdraw /form/draw [0,0,100%,500]
	setfield /form/draw xmin -1 xmax 11 ymin -1 ymax 11
create xview /form/draw/view

create xbutton /form/run -wgeom 50% -script "step 100"
create xbutton /form/quit -ygeom 0:draw -xgeom 50% -wgeom 50% \
	-script quit

/* Set up the connectivity that the view will look at */
create table /tab
call /tab TABCREATE 1 0 1
setfield /tab \	
	stepsize 1 \
	step_mode 0 \
	table->table[0] 0 \
	table->table[1] 1
addobject tabobj /tab

createmap tabobj /manytabs {side} {side}

gen_3d_msg /manytabs/tab[] /manytabs/tab[] 0.5 1 INPUT output -o -1 0 0
gen_3d_msg /manytabs/tab[] /manytabs/tab[] 0.5 1 INPUT output -o 9 -1 0

call /manytabs/tab[99] TABCREATE 100 0 1 
setfield /manytabs/tab[99] \
	stepsize 0.01 \
	step_mode 1
/* Set up some values for the tabs to display */
int i
for(i = 0 ; i < 100 ; i = i + 1)
	setfield /manytabs/tab[99] table->table[{i}] {{rand 0 100 }/100.0}
end

/* Set up the view widget */
setfield /form/draw/view \
	 path /manytabs/tab[] \
	 field msgin \
	 field2 output \
	 morph_val 2 \
	 relpath "" \
	 msgpath "" \
	 msgtype INPUT \
	 msgslotno 0

reset

//=================================CUT HERE=================================

See also:	xvar, xshape
