Data Dialogs

The data dialog commands include: Data Dialog (with the following types: Slider, Adjuster, Y Graph, XY Graph, User-defined Graph, Data Editing Cells, PopUp, Button, Text, Matrix Graph, Check Box, Radio Buttons), Data Dialog Update, Data Dialog Position, Data Dialog Close.

Data Dialog

This command creates dialog windows which display the users data in a variety of formats which permit the modification and display of the data interactively. Data Dialogs are usually displayed in groups such that some of the dialogs are used to control data values interactively, and others are used to display the results of using these adjusted values in some functional sense e.g. if you change the value of "year", what does the distribution of "landings" look like on a map for the given year.

There are a variable number of parameters.

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - the 1st parameter determines which type of data dialog window is to be created:

0 = Slider

1 = Adjuster

2 = Y Graph

3 = XY Graph

4 = User-defined Graph

5 = Data Editing Cells

6 = PopUp

7 = Button

8 = Text

9 = Matrix Graph

10 = unsupported

11 = unsupported

12 = Check Box

13 = Radio Buttons

w = Data_Dialog(w,type,...);

The window number of the created window (w) is returned as the result of the command execution.

Slider

A sliding control which may be dragged to adjust the value of the specified integer or real number.

There are 5+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 0

variable name - the name of the variable to be displayed and adjusted using the dialog.

min value - the miminum value that the slider will generate.

Optionally, this may be a character string giving the name of the variable providing the value of the limit.

max value - the maximum value that the slider will generate.

Optionally, this may be a character string giving the name of the variable providing the value of the limit.

decimal digits - the number of decimal digits displayed for the numeric value.

w = Data_Dialog([w,] 0,"variable name",min value, max value, decimal digits);

year = 1993;
Data_Dialog(0,"Year",1970,2002,0);

Adjuster

An adjuster control which may be clicked to adjust the value of the specified integer or real number. Unlike the slider control, there are no boundaries on the upper and lower ranges of permissible values.

There are 3+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 1

variable name - the name of the variable to be displayed and adjusted using the dialog.

decimal digits - the number of decimal digits displayed for the numeric value, and sets the ajustment increment.

w = Data_Dialog([w,] 1,"variable name", decimal digits);

Y Graph

A Y-Graph control displays a vector (or an expression which evaluates to a vector) as an auto-scaled line graph using the ordinal values 1...n as the matching x axis data. If the variable name is the name of a vector and not an expression, the data points in the graph may be dragged to adjust the numeric value of the selected points.

There are 2+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 2

variable name - the name of the vector (or an expression which evaluates to a vector) to be displayed and adjusted using the dialog.

w = Data_Dialog([w,] 2,"variable name");

XY Graph

An XY-Graph control displays a x and y vectors (of equal length) as an auto-scaled line graph. If the variable name is the name of a vector and not an expression, the data points in the graph may be dragged to adjust the x and y values of the selected points. The variable name or expression is plotted at the top of the graph.

There are 3+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 3

x variable name - the name of the x vector (or an expression which evaluates to a vector) to be displayed and adjusted using the dialog.

y variable name - the name of the y vector (or an expression which evaluates to a vector) to be displayed and adjusted using the dialog.

w = Data_Dialog([w,] 3,"x variable name", "y variable name");

/* and example with 2 vectors */
x = 3 *seq(1, 10);
y = 0 3 7 2 5 1 4 6 9 8;
w = data_dialog(3,"x","y");

/* an example with the Von B equation as the y data */
x = seq(1,20);
Linf = 152.46; k = 0.3374; t0 = 1.4544;
data_dialog(3,"x","Linf * (1.0 - EXP(-1.0 * k * (x - t0)));")

User-defined Graph

A User-defined-Graph control displays almost anything. It is up to the user to provide the function which does the drawing. Thus while it is quite powerful, it is not automatic. The function is called whenever the window needed to be displayed or updated, including when any of the other data dialog controls have their values changed. The degree of updating is set by the Data_Dialog_Update() command. Optional functions may be defined which let the users interact with the user-defined graph window contents.

There are 6+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 4

Drawing function name - the name of the function to be called to do the drawing. All drawing from this function will be routed to the control´s window. The function is passed the window number, and the coordinates of the current boundary of the control frame (left, right, bottom, top NDC´s) to indicate where and what size the graph should be.

Initialization function name - the name of the optional function to be called before the any drawing begins; to setup initial data. This function will plot to the graph window if any graphing commands are issued. The function is passed the window number, and the coordinates of the boundary of the control frame (left, right, bottom, top NDC´s) to indicate where and what size the graph should be.

MouseDown function name - the name of the optional function to be called when a mouse down event is detected in the control´s window. The function is passed the window number, the coordinates of the boundary of the control frame (left, right, bottom, top NDC´s), and the position of the mouse click (x,y NDC´s).

MouseStillDown function name - the name of the optional function to be called when the mouse button is held down in the control´s window. The function is passed the window number, the coordinates of the boundary of the control frame (left, right, bottom, top NDC´s), and the position of the mouse click (x,y NDC´s).

MouseUp function name - the name of the optional function to be called when a mouse up event is detected in the control´s window. The function is passed the window number, and the coordinates of the boundary of the control frame (left, right, bottom, top NDC´s), and the position of the mouse click (x,y NDC´s).

w = Data_Dialog([w,] 4,"Draw func name" [, "Init func name", "MouseDown func name", "MouseStillDown func name", "MouseUp func name"]);

Data Editing Cells

A Data-Editing-Cell control displays a vector or matrix as spreadsheet style grid of editable text.

There are 2+ parameters:

type -5

variable name - the name of vector or matrix to be displayed and edited using the dialog.

data window - optional data window must be a vector of length 4, left right bottom top of data values in the matrix, e.g. 1970 2002 2 10. If present, the editor will display row and column headings with these values (interpolated for each column e.g. X: 1970 1971 1972...2002 Y: 2 3 4... 10)

user function name - optional name of an existing function which will be called when the contents of the matrix are edited.

w = Data_Dialog(5,"variable name"["data window" "user function name"]);

y= shape(2 10, seq(1,20));
w = data_dialog(5, "y");


PopUp

A PopUp control displays a popup list of menu items to permit changing of selected options. If the user selects the nth menu item, then the specified variable is assigned the corresponding value of n. This value may be used to index the character matrix or to perform other user defined operations.

There are 3+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 6

variable name - the name of the data value to be adjusted using the dialog.

character matrix - the character matrix containing the text of the menu items.

user-defined function - optional name of user-defined function to execute when the PopUp command is executed.

w = Data_Dialog([w,] 6,"variable name",character matrix [,"user-defined function name"];

Button

A Button control displays a button which executes a user-defined function when pressed.

There are 3+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 7

button label - the optional label for button. If this parameter is missing, the label is set to the name of the user-defined function.

user-defined function name - the name of the user-defined function to execute.

w = Data_Dialog([w,] 7,["button label",]"function name");

Function Increase_Scale() { scale += 10; };
scale = 1;
w = Data_Dialog(7,"Zoom Out","Increase_Scale");

Print(cat("scale now equals ",str(scale)));
scale now equals 11

Text

A text control displays the contents of a character string for user editing. The value of the string is set when the enter key is pressed.

There are 2+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 8

variable name - the name of a character string to be displayed and adjusted using the dialog.

w = Data_Dialog([w,] 8,"variable name");

"my new text string" is entered into the text box

Matrix Graph

A Matrix-Graph control displays a numeric 2D matrix as an auto-scaled contour graph using the ordinal values 1...n as axis labels. The data is contoured using a simple linear interpolation with either the current Data_Contour_Ramp() or a pre-defined colour scale.

There are 2+ parameters:

type - 9

variable name - the name of the matrix to be displayed using the dialog.

colour scale flag - the type of colour scaling to use. 0 = default data_contour_ramp() colours;

1 = 5 level red, white, blue colour ramp; 2 = 20 level red, white, blue colour ramp;

3 = 20 level colour spectrum ramp; 4 = 20 level purple, blue colour ramp.

data window - optional data window must be a vector of length 4, left right bottom top of data values in the matrix, e.g. 1970 2002 2 10. If present, the dialog will display axis labels using these values.

w = Data_Dialog(9,"variable name"[,colour scale flag][,data window]);

Check Box

A Check-Box control displays an integer and toggles its value (0-1) when checked or unchecked.

There are 2+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 12

CheckBox label - the optional label for Check Box.

If this parameter is missing, the label is set to the name of the variable.

variable name - the name of the integer to be displayed and adjusted using the dialog.

user-defined function - optional name of user-defined function to execute when the Check Box command is executed.

w = Data_Dialog([w,] 12,[,"label"],"variable name"[,"user-defined function name"]);

Once the check box is checked, show_map variable equals 1

Radio Buttons

A Radio Button control displays a set of radio button set by an integer vector of 2 - 4 elements, and toggles their values (0-1) when the matching radio controls are checked or unchecked.

There are 3+ parameters:

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

type - 13

Radio button label 1 - the label for Radio Button 1.

Radio button label 2 - the label for Radio Button 2.

Radio button label 3 - the label for the optional Radio Button 3.

Radio button label 4 - the label for the optional Radio Button 4.

variable name - the name of the integer vector which sets and is adjusted using the dialog.

user-defined function - optional name of user-defined function to execute when the Radio Button command is executed.

w = Data_Dialog([w,] 13,[,"label"],"variable name"[,"user-defined function name"];

Once Catch radio button is selected, show_buttons variable equals 1 0 0

Data Dialog Update

This command defines the frequency of dialog window updates. Data Dialogs are usually displayed in groups such that some of the dialogs are used to control data values interactively, and others are used to display the results of using these adjusted values in some functional sense e.g. if you change the value of "year", what does the distribution of "landings" look like on a map for the given year.

There are 2+ parameters.

window number - optionally the 1st parameter may be the window number of an existing Data_Dialog, to which this dialog is appended.

frequency - controls when to update sets of dialogs. When the user adjusts a value in one dialog, the other dialogs may:

-2 - only user-override functions execute, no graphic redraw;

-1 - no update at all;

0 - update only when finished dragging (adjusting) the data in the controling dialog;

1 - update continuously as the control is adjusted.

dialog size - optional flag determining the size of subsequently created data dialogs. 0 = normal sized dialogs, 1 = reduced size dialogs.

Data_Dialog_Update(frequency [,dialog size]);

initial program state - 0 update when finished, 0 small sized dialogs.

Data Dialog Position

This command defines the position of a dialog window. The coordinates are given in pixel units. On mulitple monitor machines, these values may be negative.

There are 3 or 5 parameters.

window number - the window number of an existing Data_Dialog, to be repositioned.

if there are 3 parameters:

left - the screen coordinate of the left edge of the window,

top - the screen coordinate of the top edge of the window.

if there are 5 parameters:

left - the screen coordinate of the left edge of the window,

right - the screen coordinate of the right edge of the window,

bottom - the screen coordinate of the bottom edge of the window.

top - the screen coordinate of the top edge of the window.

Data_Dialog_Position(window, left, [right, bottom,] top);

initial program state - Dialog windows are created large enough to display the control, in a position which does not, if possible, hide previous dialogs.

Data Dialog Close

This command closes the given dialog window.

There is 1 parameter.

window number - window number of an existing Data_Dialog.

Data_Dialog_Close(w);